Files and Games

Word Practice asks for translations between Finnish and English. Its questions come from a vocabulary file, and its history remembers the learner’s answers. The files have visible effects: adding a word creates another question, and recording an answer changes the statistics.

Download Word Practice and work in its own folder in your IDE. The Pyxel interface is supplied. You complete ordinary functions in word_files.py, using the imports and file operations from this part, then submit through the IDE plugin or as a ZIP.

Two Files with Different Responsibilities

The vocabulary file describes the current questions:

finnish,english
yksi,one
kaksi,two
kolme,three

In Finnish-to-English mode, the game asks What is ‘yksi’ in English? In the other direction, it asks What is ‘one’ in Finnish?

An answer produces one history row:

direction,source,target,response,correct
fi-en,yksi,one,one,1
fi-en,kaksi,two,thu,0
fi-en,kolme,three,tree,0
en-fi,one,yksi,yksi,1

source is the displayed word, target is the expected translation, and response is what the learner typed. The direction keeps the two kinds of practice distinct. correct is written as 0 or 1 and converted to an integer when loaded.

These are flat records, so CSV suits both files. The JSON chapter compared this design with linked CSV tables and nested documents. Here a history row keeps its own question and expected answer, so removing a word from today’s vocabulary does not erase the meaning of an earlier attempt.

Keep the Answer Rule Explicit

The supplied answer_matches(response, target) ignores capitalization and surrounding whitespace. It preserves accents: "YÖ" matches "yö", while "yo" does not.

For a matching answer, the game displays Correct! Otherwise it displays Incorrect, the correct translation is ’…’. The recorded response keeps its original text.

Each vocabulary word has one translation in either direction for this exercise. The loader rejects repeated Finnish or English words after trimming and ignoring case. Supporting several accepted translations would require a richer record contract; it is not inferred from duplicate rows.

Record One Attempt at a Time

Follow the data through one question:

vocabulary.csv → checked word pairs → question
typed response → checked attempt → append to history.csv
history records → summary → statistics and review suggestions

Loading vocabulary and history happens at startup. Appending happens once when an answer is submitted. Drawing the next frame does not append another row.

A missing history file means there have been no saved attempts yet. A malformed existing history means loading failed. Do not silently replace that history with an empty list.

For a new history file, write the header once. For an existing valid file, append only the new row. Validate both the new attempt and any existing history before opening for append. The supplied validator checks the record fields and whether the correctness flag agrees with the recorded answer.

A manually edited CSV file may have no newline at its end. Before appending, check whether valid existing text ends with "\n" or "\r"; add a separator if neither is present, so the new answer begins on its own row.

Calculate Before Drawing

Statistics do not need Pyxel or an open file. This example starts with already-checked records. Predict the totals before running it:

Change history to [] and adjust the assertions. The counts should all be zero. The interface must also avoid dividing by zero when displaying an accuracy percentage.

The exercise extends this calculation with per-question groups. Keep the direction and both words together when deciding which group an attempt belongs to. Practising yksi → one and one → yksi can produce different results.

Test Before Opening the Game

Download the exercise with the IDE plugin or Download starter code below. Open the downloaded folder in your IDE. The supplied files have these roles:

The game uses the supplied Misc Fixed 6×10 font, which is in the public domain. The 6x10.bdf file contains its Latin-1 characters, including ä, ö, Ä, and Ö, and retains its public-domain notice. Keep it beside main.py; the interface loads it automatically.

No history file is supplied. Your reader treats a missing history.csv as an empty history, and your writer creates it when the first answer is saved.

The handout divides the 70 points into four steps: vocabulary loading (15), history loading (20), appending (20), and statistics with the complete game (15). Submit after each step to receive its grading feedback.

Write your own checks for each function in word_files.py. Create check.py beside it, import the function you are working on, and assert the results you predict. Save both files, then run py check.py on Windows or python3 check.py on macOS/Linux from the exercise folder. The handout gives a first example. Later functions can remain unfinished while you test the current one.

Use separate test files, such as test_vocabulary.csv and test_history.csv, to keep your learning history intact. Include:

• a quoted comma and Finnish letters;
• two consecutive appends, retaining both records and only one header;
• a missing history, a header-only history, and a malformed existing history;
• an invalid attempt that must not create or change a file;
• both translation directions and an empty summary;
• a removed vocabulary word whose historical attempts remain readable.

A failed assertion shows which expectation was not met. Compare it with the function’s contract, fix the cause, and rerun your checks before submitting.

The handout states the exact return shapes and validation rules.

from word_files import load_vocabulary

with open("test_vocabulary.csv", "w", encoding="utf-8", newline="") as file:
    file.write("finnish,english\nyö,night\n")
assert load_vocabulary("test_vocabulary.csv") == [
    {"finnish": "yö", "english": "night"}
]
print("Checks passed.")

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install pyxel==2.9.9
.\.venv\Scripts\python.exe main.py

python3 -m venv .venv
.venv/bin/python -m pip install pyxel==2.9.9
.venv/bin/python main.py

Play and Inspect the History

Run your own checks first, then use the Pyxel setup and launch commands below to run main.py. The game does not run a test script automatically.

Choose a direction with menu key 1 or 2. Type an answer, use Backspace to correct it, and press Enter. Read the feedback, then press Enter for the next question. Escape returns to the menu. Close the local game window when finished.

Try one correct answer and one deliberate mistake. Open statistics with menu key 5 and compare the counts with your predictions. Start another round: it must add to the history rather than reset it.

The actual history.csv file remains in the game folder between runs. Menu key 6 shows its filename. Open it in your IDE after playing and connect each row with an answer you gave. Close and restart the game to check that earlier attempts still appear in the statistics.

Run Pyxel Locally

The file functions and your assertions need only standard Python. Playing locally also needs Pyxel. Check py --version on Windows or python3 --version on macOS/Linux: Pyxel 2.9.9 requires Python 3.11 or newer. Update Python first if needed, following Chapter 2. In the game folder, create a virtual environment: a separate Python environment for this project’s installed packages.

On Windows:

py -m venv .venv
.\.venv\Scripts\python.exe -m pip install pyxel==2.9.9
.\.venv\Scripts\python.exe main.py

On macOS/Linux:

python3 -m venv .venv
.venv/bin/python -m pip install pyxel==2.9.9
.venv/bin/python main.py

If creating the environment reports that venv or ensurepip is unavailable, follow the error message to install your system’s Python virtual-environment support, then retry.

Create the environment and install Pyxel once; on later runs, use only the final command. These commands use the environment’s interpreter directly; activation is not required. The pinned version matches the course’s Pyxel runtime. Keep the supplied source files, vocabulary file, and 6x10.bdf font in the game folder. If your system needs additional setup, consult Pyxel’s installation instructions.

Run main.py to play. To check the file functions separately, run .\.venv\Scripts\python.exe check.py on Windows or .venv/bin/python check.py on macOS/Linux. Keep personal history, generated test files, and .venv on your computer; use the handout’s file list when submitting through the IDE plugin or as a ZIP.

Build Your Vocabulary and Practise Mistakes

Add a new pair to vocabulary.csv, keeping the header, then run the game again. Use correctly quoted CSV for a field containing a comma. Remove another pair and check that it disappears from new questions while its earlier history remains.

Menu keys 3 and 4 use the supplied review mode. It selects current word pairs with recorded mistakes in that direction, ordered by mistake count. Vocabulary order breaks ties. It does not recommend deleted pairs or silently attach an old attempt to a changed translation.

A count is a simple starting rule. Five mistakes in fifty attempts differ from five mistakes in five attempts. As an optional extension, compare mistake counts with error rates and include opportunities to practise words with no history. Another extension is an in-game vocabulary editor using the same file contract.

Check Your Understanding

1. Why are vocabulary and history separate files?
2. What would happen if every new answer opened history in "w" mode?
3. Why does an old attempt keep its expected translation?
4. Which functions can be tested without starting Pyxel?
5. Why do opposite translation directions need separate statistics?