Project: a flashcard trainer

Checkpoint 1: cards as objects

Each card is a small object with a box number. csv.DictReader reads the file one row at a time, as dictionaries keyed by the header row:

import csv

with open("cards.csv", "w") as f:
    f.write("front,back\nvariable,A name that holds a value\nloop,Code that repeats\n")

class Card:
    def __init__(self, front, back, box=1):
        self.front = front
        self.back = back
        self.box = box

    def __repr__(self):
        return f"Card({self.front!r}, box {self.box})"

def load_cards(path):
    with open(path) as f:
        return [Card(row["front"], row["back"]) for row in csv.DictReader(f)]

print(load_cards("cards.csv"))

The first lines write the CSV, so the example has a file to read. In the real program it would already exist, perhaps exported from a spreadsheet. __repr__ gives each card a readable printout, which makes the list on the last line easy to check.

class Card:
    def __init__(self, front, back, box=1):
        self.front = front
        self.back = back
        self.box = box

def mark(card, known):
    pass

Checkpoint 2: saving progress as JSON

The CSV holds the cards; progress also needs each card's box. JSON fits, because a list of dictionaries turns into JSON text and back without any extra code:

import json

progress = [
    {"front": "variable", "back": "A name that holds a value", "box": 2},
    {"front": "loop", "back": "Code that repeats", "box": 1},
]
with open("progress.json", "w") as f:
    json.dump(progress, f, indent=2)

with open("progress.json") as f:
    back_again = json.load(f)
print(back_again == progress, back_again[0]["box"])

json.dump writes the data to an open file, and json.load reads it back. indent=2 spreads it over several lines, so a person can open the file and read it. The comparison prints True: what you save is exactly what you get back.

Checkpoint 3: the first run, and the bad day

Loading progress can go wrong in two ways, and they deserve different answers:

• There's no file yet. open raises FileNotFoundError. That isn't a problem at all; it's the first run. Start from the CSV, quietly.
• The file is damaged: half-written, or edited by hand. json.load raises json.JSONDecodeError. Say so, so the person knows their progress was lost, then start from the CSV.

import json

def load_progress(path):
    try:
        with open(path) as f:
            return json.load(f)
    except FileNotFoundError:
        return None
    except json.JSONDecodeError:
        print(f"Couldn't read {path}, so starting again.")
        return None

with open("broken.json", "w") as f:
    f.write('[{"front": "loop", "box": ')

print(load_progress("never-saved.json"))
print(load_progress("broken.json"))

Both cases return None, meaning "no usable progress", and the caller then builds a fresh deck from the CSV. Each except names the exact error it expects. A bare except: would also hide real bugs, like a typo in a variable name, which you'd much rather see.

class Card:
    def __init__(self, front, back, box=1):
        self.front, self.back, self.box = front, back, box

cards = [Card("variable", "A name that holds a value"), Card("loop", "Code that repeats"),
         Card("function", "A named, reusable piece of code")]

score = 0
for card in cards:
    answer = input(f"{card.front}? (y = knew it, n = didn't) ").strip().lower()
    if answer == "y":
        card.box = min(card.box + 1, 3)
        score = score + 1
    else:
        card.box = 1
        print("  It means:", card.back)

print("Score:", score, "of", len(cards))
print([(c.front, c.box) for c in cards])

Go further

The trainer is complete. Some ways to extend it:

• Shuffle the due cards, so the order changes each session.
• Show a summary at the end of each session: how many cards are in each box.
• Let the cards come from the practice API instead of a file, with one function that fetches them. The rest of the program shouldn't need to change.
• Save after every answer, not just at the end, so closing the program halfway loses nothing.

The last idea is about durability: the less work a crash can lose, the better the program. That idea comes back, at a much bigger scale, when you store data in databases and run services that must not lose anything.