Take the Project with You

The tool is finished. This lesson makes it somebody else’s.

That is a different job from making it work, and it is the one this whole course has been building toward. Chapter 12 did it for the API client. This is the same exercise with more moving parts: two test modules, two dependency recipes, an offline data file, and a command with six behaviors.

Write the README you would want to receive

Imagine someone who has your ten files, has never spoken to you, and has Python installed. What do they need?

Start with what the tool is, in two sentences. Then the setup, activation-free exactly as in Chapter 12, so it works in any shell without anyone remembering to activate anything:

python3 -m venv .venv
./.venv/bin/python -m pip install -r requirements-dev.txt
./.venv/bin/python -m pytest -q

Then the PowerShell equivalent, then the commands that actually run the tool. Say that Python 3.10 or newer is required, and that a runtime-only user installs requirements.txt instead of the dev recipe.

Document the interface: the positional report path, each option with its default, and the fact that --refresh and --offline-source cannot be combined. Someone reading your README should be able to predict what a command will do without running it.

Be honest about the API

There is one thing you must not leave out, and it is the awkward one.

The practice API lives inside Python Land. Once this project is on someone else’s machine, the network path will not work. Any command that tries to fetch will fail.

Say so, plainly, near the top. Then say what still does work: the full test suite, because it uses fake responses, and the offline mode, because it reads a file you shipped.

./.venv/bin/python practice_report.py offline-report.txt --offline-source data/offline-page.json
./.venv/bin/python -m pytest -q

Documentation that quietly omits a known limitation is worse than documentation that admits one. The reader will discover it in about four minutes, and everything else you wrote becomes suspect.

Then run your own instructions

First save your finished README, then use Download project while signed in. Keep the ZIP and extract it into a fresh local folder. Open a terminal in that extracted project root.

Follow your README from the top there, without skipping anything and without using knowledge that is only in your head. If you are taking the site-only path, review the runbook here and select that path in the final lesson.

You will find something. Almost everyone does: a command that assumes a directory you never said to change into, a step that only works because your environment was already set up, a flag mentioned in one place and spelled differently in another.

That discovery is the entire point of the exercise.

Run the offline report command before the checker in the next lesson, because that generated offline-report.txt is one of the things the checker looks at.

./.venv/bin/python practice_report.py offline-report.txt --offline-source data/offline-page.json

offline-report.txt is not in the download, and should not be. The command creates it in the extracted project, where the final lesson’s local checker will read it.

Ask Monty to read your README as someone who has never seen the project and name the first instruction that assumes something you never wrote down.