Project: CLI Expense Tracker

Build a complete, tested command-line program from scratch, using nearly every chapter of this book: expenses add 12.50 food, expenses list, expenses summary.

The plan

We'll build tracker, a small package in playground/. (The finished version is in playground/reference/ if you get stuck; clone the playground from coder-hop/python-book-playground if you don't have it.) It replaces the little tracker package from Chapter 8's exercise.

Design decisions, and the chapter each one comes from:

Step 1: the data model (models.py)

This module knows nothing about files or the command line. It only describes the data. Keeping it free of input/output makes it easy to test and reuse.

• Category.parse is a classmethod that converts user text into an enum member. It replaces the enum's terse error with a helpful one, and from None hides the internal cause (Chapter 10). ", ".join(cls) works because StrEnum members are strings.
• parse_amount validates the text by hand with partition and isdigit, and accepts both 12.5 and 12,50. Its docstring contains a doctest.
• format_money uses divmod on the absolute value, then :, and :02d format specs (Chapter 9).
• to_dict and from_dict convert to and from JSON-friendly types: dates become ISO strings and enums become their values.

Step 2: storage (storage.py)

• EAFP: just try to read the file. FileNotFoundError means "first run", so return an empty list.
• Any parsing problem (bad JSON, a missing key, an unknown category) becomes one StorageError, chained with from exc so the original cause stays visible to anyone debugging.
• save writes to expenses.json.tmp first, then replace()s the real file in one step. A crash halfway through writing can never corrupt your data.
• max(..., default=0) handles the empty list when picking the next id.

Step 3: reports (report.py)

• select is a generator with keyword-only filters (*, Chapter 5). totals_by_category(select(...)) never builds an intermediate list.
• defaultdict(int) starts each total at 0, and sorted(..., key=lambda kv: kv[1], reverse=True) puts the biggest first. Since dicts keep insertion order, the result stays sorted.
• bar draws a tiny text chart with string repetition (Chapter 2).

Step 4: the command-line interface (cli.py)

• Subcommands: add_subparsers gives each command its own arguments, so expenses add -h shows only the options for add.
• A closure: _arg(convert) returns a wrapper function that remembers convert (Chapter 5). argparse calls it for each argument, and an ArgumentTypeError makes argparse print our message instead of a generic one.
• Functions as values: COMMANDS maps names to functions, a "dispatch table". Each command returns True if the data changed, so main only saves when it needs to. (A match args.command: block would work just as well.)
• Exit codes and stderr: expected problems print error: … to stderr, and main returns 1. Bugs are not caught, so they still show a full traceback, which is exactly what you want while developing.
• main(argv=None): argparse reads sys.argv when argv is None, so tests can pass their own list instead.

Step 5: the package files (__init__.py, __main__.py)

python3 -m tracker runs tracker/__main__.py. sys.exit(main()) turns main's return value into the process exit code.

Step 6: use it

Run these from playground/. --file demo.json keeps the experiment separate from your real data, and --date makes the output repeatable.

Errors are friendly, and the exit codes are right:

And the data file is plain, readable JSON:

Step 7: tests (test_tracker.py)

The tests call main([...]) directly, with a temporary data file, and capture the output with redirect_stdout and redirect_stderr. subTest reports each bad input separately when one of them fails.

Step 8: install it as a real command

The [project.scripts] entry creates an expenses executable in the venv's bin/ that calls tracker.__main__:main, and uses its return value as the exit code.

More examples

1. Using the package as a library

2. A damaged data file is reported, not crashed on

3. Exporting to CSV

4. Monthly totals with Counter

5. The same dispatch, written with match

Both styles are fine. The dict version makes adding a command a one-line change, and the match version is easier to extend with argument patterns.

Exercises

All of these extend your playground/tracker. Add a test for each feature you build.

Official docs

• The Python Tutorial (everything used in this project)
• argparse: sub-commands
• unittest · contextlib.redirect_stdout
• Writing your pyproject.toml