Overview
This assignment is our warmup with working with Python, including with agent-generated Python code.
This handout looks long, but that's partly because (a) we're spelling out instructions for setting up Python and folders for the assignment, and (b) we are breaking down the critical comparison of the game versions into many concrete tasks. Over time, we hope you will learn to generate the questions for doing these critiques as well as generating the answers. If you want to do part 2 well (and learn from it), you should expect to spend more than a couple of hours on the Game portion.
Learning objectives
- Read and run code that you did not write, in a language that is new to you
- Compare designs by evidence (a function, a line, a test result), not by impression
- Identify what information an agent needs to produce the program you intend
AI and collaboration policy for this assignment
In Part 1, write the code and answers yourself. You may ask an agent to explain Python you do not understand (an error message, a line of the starter file), but not to write or check your solutions.
In Parts 2 to 4, you will use agents to generate the code. The comparisons and the answers in your worksheet must be done entirely by you. You may ask Claude to explain unfamiliar Python.
Setup
Getting the Interactive Window
Open VS Code, then click the Extensions icon in the left sidebar (four squares with the top-right one tilted on its side). Search for "Python" and install the one published by Microsoft (ms-python.python). Then search for "Jupyter" and install the Microsoft one (ms-toolsai.jupyter).
To use the interactive console, find the right-pointing triangle at the top of your code editor, press the down-arrow that is next to it, then select "Run Current File in Interactive Window". That will load your file as you are used to in Pyret. If you edit your file, the easiest thing to do is either to copy your edits manually into the prompt, close the interactive window entiresly and start a new one.
Get the Worksheet
- Make a copy of the written answer worksheet and submit the link to it in the worksheet submission form (you can do this before filling anything in).
Setting up directories and environments
- In VS Code, choose File, then Open Folder. Make a new folder named
python-mazefor your work on this assignment (the dialog has a "New Folder" button) and open it. - Open the Terminal (Terminal menu, then New Terminal). It opens at the bottom of the window,
already inside
python-maze. Type this and press Enter (it works on both Mac and Windows):
Three new folders should appear in the Explorer sidebar on the left. If they don't, the terminal is not in the folder you opened: close it and open a new one.mkdir part1 mkdir free-form mkdir translated - Your computer's Python doesn't come with the libraries we use (pytest for testing and
Flask for the web version of the game), so create a private Python environment for this
assignment. In the terminal, still inside
python-maze:On a Mac:
python3 -m venv .venv .venv/bin/pip install pytest flaskOn Windows:
py -m venv .venv .venv\Scripts\pip install pytest flaskThis takes a minute and creates a hidden-ish folder named
.venvnext to your three folders; you never edit it. All three folders share it. Because it is not inside any of them, it won't end up in your zip files.
A few terminal basics:
cd part1moves into the folderpart1, andcd ..moves back up.- Before running anything, check which folder you are in: the prompt shows it,
or type
pwd(Mac) orcdwith nothing after it (Windows). Most "file not found" errors come from running a command in the wrong folder. - The environment lives in
python-maze, one level abovepart1,free-formandtranslated. From inside one of those folders, you reach it through..(the folder above):../.venv/bin/pythonon a Mac,..\.venv\Scripts\pythonon Windows.
Getting the starter files for Part 1
- Download these three files and drag them from your Downloads folder onto
part1in the Explorer sidebar: responses.csv, dicts.py and test_dicts.py (the last is a testing file that we set up for you; you'll only write a few additional tests) - To check your setup, run the tests from a terminal inside
part1. You should see failures, because you haven't written the functions yet:../.venv/bin/python -m pytest (Mac) ..\.venv\Scripts\python -m pytest (Windows)
Setting up the maze starter files
- Open the maze Google Sheet
from the previous assignment and export its
maze-layoutanditemstabs as CSV files (File, Download, Comma-separated values; do this once for each tab). - Put copies of the two CSV files in both
free-formandtranslated. Put your finishedmaze-game.arr(Pyret file) intranslatedonly: the free-form version must not see your Pyret code.
Part 1Warm-up: Dictionaries and Dataclasses
To practice with dataclasses, dictionaries, and csv files, we work with the quiz platform example that we'll be developing in lecture. A quiz platform records each student's answer to each question in a CSV file (e.g., the downloaded responses.csv), with the columns student, qid and answer. Your starter file (dicts.py) reads it into a list of dictionaries, one per row, using Python's csv library. Here's what that looks like:
def load_rows(filename):
with open(filename, newline="", encoding="utf-8-sig") as f:
return list(csv.DictReader(f))
RAW_ROWS = load_rows("responses.csv")
The starter also defines two dataclasses, Question and Response. It has function headers and starter code for each of the following tasks. You may use for-loops, map and filter (but not comprehensions, in case you already know from elsewhere what those are).
Open responses.csv (either in a text editor or a spreadsheet application). Then, in the Python console, run from dicts import RAW_ROWS and print RAW_ROWS[0], RAW_ROWS[1], RAW_ROWS[4] and RAW_ROWS[8]. Compare each dictionary with its line in the file. In your worksheet, list what you notice about the values (at least three things) that a program using them would have to handle.
Write ans_is_blank(row), which is true if the row's answer is blank. Two of the 9 rows in RAW_ROWS are blank. Write a corresponding test function using assert. Use RAW_ROWS[n] to extract rows for your tests.
As we just saw, the dictionary that Python created from the csv has various errors and inconsistencies. As part of cleaning up the data prior to use, we will convert the data into a list of Response values (where Response is a dataclass).
Write to_response(row), which turns a raw row into a Response: the answer has surrounding spaces removed and is lowercased, and a blank answer becomes None. For example, " DEF " becomes "def". Then write to_responses(rows), which converts a whole list. Add your own assert tests to test_dicts.py for two rows you make by hand: one whose answer is only spaces, and one with a mixed-case answer with spaces around it.
to_responses(RAW_ROWS) should have 9 responses.
Write blanks_per_question(responses), which creates a dictionary from question id to the number of blank responses to that question. It has an entry only for questions with at least one blank: on RAW_ROWS, q1 and q4 have one each.
Hint: The first time you see a key there is no entry to add to yet. The dictionary
method get takes a default for that case.
A response names its question by id, but to score it you need the question itself. The starter gives you QUESTIONS, a dictionary from each question id to its Question. Write points_earned(response, questions): it returns the question's points if the answer matches the question's correct answer, and 0 if the answer is wrong or blank. (Every response in the data names a question in QUESTIONS.)
Write score_by_student(responses, questions), which creates a dictionary from student name to the total points that student earned. On RAW_ROWS, ana scores 5, ben 2 and cy 1.
For each of the following, would you use a dictionary or a dataclass, and why (one or two sentences)? The answer will go in your worksheet.
- storing data for one question: its id, prompt, correct answer and points
- computing the number of blank responses for each question
- looking up information on a question given its id
- storing data one student's whole submission: their name, and an answer for each question
Part 2Recreating the Maze Game in Python
We want to create a version of your maze game that someone can play in a web browser. Pyret isn't designed to support web applications, but Python is.
As an exercise in both working with Python and understanding the behavior of coding agents, we are going to have you use Claude to create the Maze Game twice: once by asking it to translate your Pyret solution and once by giving it just the description of the game. You'll then compare and critique the two versions.
Here is the description we will give Claude for creating the game. Don't give it to Claude just yet -- you'll want to look at it first to answer the next question.
The game description
A kid walks to school through a maze on a freezing morning, using the arrow keys. The maze is a 25x15 grid of cells (30x30 pixels each), containing one of snow (the kid cannot enter), sidewalk, or the school door (the kid can enter it, and the game ends there). Positions are (x, y), x the column and y the row, from 0 at the top-left. The kid starts at (1, 1) with warmth 30. Each step onto a sidewalk or door costs 1 warmth. Stepping into snow does nothing. Three kinds of items sit on distinct sidewalk cells; stepping onto one uses it up and sets warmth (instead of the usual cost): a coat sets it to 30, a scarf adds 8 (never above 30), flip-flops cut it in half, rounded down. The game ends when warmth reaches 0 or the kid reaches the door. Warmth is shown as a gold bar on the right of the maze. The maze is in maze-layout.csv ("s", "w", "d"; its first row and first column are labels, not cells) and the items in items.csv (name, x, y). Create a web-based version of this game in Python using Flask. The code should be able to run with flask --app app run. Put the Flask app in app.py. The Python environment for this project is in ../.venv (one folder up from this one); use it to run Python and to install anything.
In your worksheet, write down your prediction of what you expect might be the same and different between the translated and free-form versions of the game. Think about things like the data, the tests, and how the code is split into functions. One or two sentences each will suffice.
Switch into your free-form folder and start a new Claude session. Give Claude just the description from the dropdown above and the two csv files.
Now switch into your translated folder and start a new Claude session. Put a copy of your maze-game.arr and the two CSV files in the folder. Give the Claude session only the following prompt (if it asks followup questions, go ahead and answer them):
This folder contains my implementation of a game that was written in
Pyret and two csv files with the game setup data (that used to come
from a google sheet in the Python version). Translate my Pyret version
into a Python one using Flask. The code should be able to run with
flask --app app run. Put the Flask app in app.py. The Python
environment for this project is in ../.venv (one folder up from this one); use it to run
Python and to install anything.
Play both versions. To run one, go to its folder and run ../.venv/bin/python -m flask --app app run (Windows: ..\.venv\Scripts\python -m flask --app app run), then open the address it prints in your browser. You can tell the agent to fix any bugs that you encounter. Log the bugs in your worksheet.
Part 3Audit
For each of the next four tasks, record one finding (what you saw, citing a function, a data definition, or a test by name) and one judgment (which version you prefer for this aspect, using the criteria given). Where a finding surprised you relative to your prediction, say so.
Compare how the data (game state, maze configuration, etc) was represented across the two versions. Consider the kid's position, the items, the cells, and the game state: what did each version use (and your Pyret)? Is the maze part of the state? Can the representation let someone describe a game that makes no sense (for instance, an item in two places)? Write your finding and your judgment in your worksheet.
Compare the (helper) functions that got created: were there similar functions for similar tasks, or did the two versions break the problem down differently? Look specifically at where the drawing versus on-key updates get done. How easily could someone test the free-form version without actually playing the game? Write your finding and your judgment in your worksheet.
Compare the tests. Give both sets of tests to a new Claude session, and ask it to help you compare what scenarios were tested in both, or tested in only one of the two versions. Add descriptions of these differences to your worksheet, along with a reflection on the strengths and weakenesses of each collection.
A designer wants boots: a new item that costs the kid 2 warmth to pick up. Do not implement it. For each version (and your Pyret), list every function and data definition you would have to change to add this. Judge by this: in which version would the change be easiest to make correctly? Write your list and your judgment in your worksheet.
Part 4What the Agent Needed
The description leaves some things open. For each of these, find out what the free-form and translated versions each do, and what your Pyret code does:
- the kid tries to walk off the edge of the maze
- a key is pressed after the game is over
- the maze has two doors, or an item sits in snow
- flip-flops are picked up when the warmth is an odd number
Which of these did the agent decide silently? Which decisions differ between the versions? Write your answers in your worksheet.
Step back and think about what you've observed. If you had to give free-form instructions again, what (if anything) might you do differently? Details you would add, constraints you might state, etc? Put your answer in your worksheet.
How was the experience of working with agent-generated code on this assignment? What surprised you? What frustrated you? Was the programming we've done to this point in the course sufficient for making sense of the two game versions? Put your answer in your worksheet.
Grading
The bulk of grading for this assignment will be on the quality of your observations about the two game versions. We want to see you making concrete statements and careful observations. This is one of your first assignments involving critical assessment of code; we've scaffolded the questions, but want to see signs that you took them seriously.
We will NOT have code review on this assignment.
Handin
Hand in these files, together, in one submission:
dicts.pytest_dicts.pyfree-form.ziptranslated.zip
Submit to Gradescope. You may submit as many times as you like before the deadline; we grade the last submission.
To make a zip file of a folder:
- Find the folder (
free-formortranslated) in your computer's file manager: right-click it in the VS Code Explorer and choose "Reveal in Finder" (Mac) or "Reveal in File Explorer" (Windows). - On a Mac: right-click the folder and choose "Compress" followed by the folder name.
On Windows: right-click the folder, choose "Send to", then "Compressed (zipped) folder".
Either way, a file named
free-form.zip(ortranslated.zip) appears next to the folder. - Open the zip file to check that your code and CSV files are inside, and that it is not empty.
Comments or concerns?
If you have comments or concerns, submit them on the anonymous feedback form. Sign in with your Brown Google account to open it; your email address is not recorded.