Course 2.1Lesson 5 of 5

Project: a marks book that remembers

In this project we build a marks book that remembers its marks between runs. The data is a dictionary of names and lists of marks, kept in a JSON file. Functions load and save, add_mark, average and report do the work. A mark must be a whole number from 0 to 100, and a refused mark must not change the file. The load survives a missing or damaged file. We plan the expected states by hand, build the functions, test the refused marks, the new student, the missing file and the damaged file, and extend the book with removal of a mark, a CSV export and a backup.

about 25 min1 simulation2 practice questions

Lesson 5 of 5Show all lessons

Try the code and the simulations beside the lesson.

What you will be able to do

After this lesson you can

design a small program whose data lives in a file,
write the load, change and save parts as functions,
protect the file from bad input, and
test a program that reads and writes files.

The goal

A teacher keeps the marks of a class. The marks arrive over the term, one at a time, so the program must remember them from one run to the next. It must

add a mark to a student (a new student starts with an empty list),
refuse a mark that is not a whole number from 0 to 100, and change nothing when it refuses,
tell the average of a student, or None for a student who is not in the book,
make a report, one line for each student, in alphabetical order,
not crash when the file is missing or damaged.

Step 1: the data and the expected states

The data is a dictionary: the key is the name, and the value is the list of marks. In the file, it is JSON.

Action	The book after it
(the file does not exist)	`{}`
add Asha 72	Asha: 72
add Ravi 85	Asha: 72, Ravi: 85
add Asha 90	Asha: 72, 90, Ravi: 85
add Meera 64	Asha: 72, 90, Ravi: 85, Meera: 64
add Ravi 150	refused, the book is unchanged

The averages: Asha 81.0, Ravi 85.0, Meera 64.0. The average of Zoya, who is not in the book, is None.

Step 2: the program

Run it, and compare each line with the table.

Look at how it is built.

- FILE is a constant at the top. The name of the file is in one place.

- load returns the dictionary of the file, or {} if the file is missing or damaged. The same function as in the last lesson.

- save writes the whole book. It is the only place that writes.

- add_mark checks the rule first: the mark must be an int from 0 to 100. If it is bad, it raises a ValueError before it loads or saves, so the file cannot change. Then the three steps: load, change, save. book.setdefault(name, []).append(mark) gives the student an empty list if the name is new, and appends the mark. (It is the grouping pattern of the dictionaries course, in one line.)

- average gives None for a student who is not in the book, or has no marks, so that the caller can decide what to say. It does not divide by zero.

- report returns a list of lines, sorted by name. It does not print: the caller prints.

- Each function loads the file. That is slower than keeping the data in a variable, but it is simple, and always shows what is really in the file. For a small book, it is fine. For a big one, you would load once at the start, and save at the end.

- The last line of the program checks that load() gives exactly what is in the file.

Step 3: test

Test	Expected
a missing file	`load()` gives `{}`
a damaged file (`"not json"`)	`load()` gives `{}`
a mark of 0 and a mark of 100	accepted (the ends are allowed)
a mark of -1 and of 101	refused
a mark that is text, or a decimal	refused
a refused mark	the file is unchanged
a second "run" (call `load()` again)	holds the marks of the first
average of a student with no marks	`None`

The sixth row is the key idea of the whole course: a refused action must leave the file as it was.

The check comes before load(). A refused mark never opens the file, so it can never damage it.

Step 4: extend it

Pick one or two, and do them without looking at a solution. Write the expected states first.

Remove a mark. remove_mark(name, mark) removes one mark, and removes the student when the list is empty.
A CSV export. Write the report as a CSV file with the columns name, count and average.
A backup. Before each save, copy the old file to marks_book.json.bak.
A history. Keep the date of each mark: a list of dictionaries with mark and date.
A command menu. Join the functions into the menu of the course on classes, so that the book is used from the keyboard.

Common mistakes

Checking the rule after changing the file.
Writing with "a" and getting two JSON documents in one file, which cannot be loaded.
A load that crashes on a missing file, so the program fails the first time that it runs.
Printing inside the functions. You cannot test them.
Forgetting that a tuple or a set will not survive a JSON file.

Practice

Start with two quick questions. Each New numbers gives you a fresh one, so you can practise as long as you like.

Then the labs and the problems:

Warm-up. Open the lab Project: a marks book that remembers. The checker uses its own file, tests the refused marks, the missing file and the damaged file, and removes its file at the end.
Build. Do Step 4 for one extension.
Stretch. Open the lab JSON round trip again and explain what happens to a tuple.

Remember these

Keep the name of the file in one place. One function loads, one function saves.
Check the rules before you touch the file. A refused action leaves the file as it was.
load survives a missing or damaged file with a default value.
Test the missing file, the damaged file, the ends of the allowed range, and a second run.