Nimm das Projekt mit

Das Werkzeug ist fertig. Diese Lektion macht es für andere nutzbar.

Das ist eine andere Aufgabe, als es zum Laufen zu bringen, und darauf hat dieser ganze Kurs hingearbeitet. Kapitel 12 hat es für den API-Client getan. Hier ist dieselbe Übung mit mehr Teilen: zwei Testmodule, zwei Abhängigkeitsdateien, eine Offline-Datendatei und ein Befehl mit sechs Verhaltensweisen.

Schreibe die README, die du selbst erhalten möchtest

Stell dir jemanden vor, der deine zehn Dateien hat, noch nie mit dir gesprochen hat und Python installiert hat. Was braucht diese Person?

Beginne mit zwei Sätzen darüber, was das Werkzeug ist. Danach folgt die Einrichtung, genau wie in Kapitel 12 ohne Aktivierung. So funktioniert sie in jeder Shell, ohne dass jemand daran denken muss, etwas zu aktivieren:

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

Danach folgen die PowerShell-Entsprechung und die Befehle, die das Werkzeug tatsächlich ausführen. Gib Python 3.10+ als Voraussetzung an und erkläre, dass jemand zur reinen Laufzeitnutzung („runtime-only“) requirements.txt statt der Entwicklungs-Abhängigkeitsdatei installiert. Behalte die Aussage „pip uses the interpreter’s configured package index.“ in der Projekt-README bei.

Dokumentiere die Schnittstelle: den positionalen Berichtspfad, jede Option mit ihrem Standardwert und die Tatsache, dass --refresh und --offline-source nicht kombiniert werden dürfen. Wer deine README liest, sollte vorhersagen können, was ein Befehl tut, ohne ihn auszuführen.

Beschreibe die API ehrlich

Eine Sache darfst du nicht auslassen, auch wenn sie unbequem ist.

Die Übungs-API liegt innerhalb von Python Land. Sobald das Projekt auf einem fremden Rechner liegt, funktioniert der Netzwerkpfad nicht. Jeder Befehl, der einen Abruf versucht, wird scheitern. Halte dafür in der Projekt-README fest: „The API host is fixed and internal to Python Land.“ und „After download, network mode cannot work.“

Sage das klar und weit oben. Sage dann, was weiterhin funktioniert: die vollständige Testsuite, weil sie Fake-Antworten verwendet, und der Offline-Modus, weil er eine mitgelieferte Datei liest.

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

Dokumentation, die eine bekannte Einschränkung still auslässt, ist schlechter als Dokumentation, die sie offen nennt. Die lesende Person entdeckt sie in etwa vier Minuten, und alles andere, was du geschrieben hast, wird fragwürdig.

Befolge dann deine eigenen Anweisungen

Speichere zuerst deine fertige README und verwende dann Download project, während du angemeldet bist. Behalte das ZIP und entpacke es in einen neuen lokalen Ordner. Öffne ein Terminal in diesem entpackten Projektstamm.

Befolge dort deine README von oben, ohne Schritte auszulassen und ohne Wissen zu verwenden, das nur in deinem Kopf steht. Wenn du den Weg ausschließlich auf der Website nimmst, prüfe die Anleitung hier und wähle diesen Weg in der letzten Lektion.

Du wirst etwas finden. Das geht fast allen so: einen Befehl, der ein Verzeichnis voraussetzt, dessen Wechsel du nie genannt hast; einen Schritt, der nur funktioniert, weil deine Umgebung bereits eingerichtet war; eine Option, die an zwei Stellen unterschiedlich geschrieben ist.

Genau diese Entdeckung ist der Sinn der Übung.

Führe den Befehl für den Offline-Bericht vor dem Prüfskript in der nächsten Lektion aus. Die dabei erzeugte offline-report.txt gehört zu den Dingen, die das Skript untersucht.

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

offline-report.txt ist nicht im Download enthalten und sollte es auch nicht sein. Der Befehl erzeugt sie im entpackten Projekt, wo das lokale Prüfskript der letzten Lektion sie liest. Beschreibe auch die Nachweisgrenzen in der Projekt-README: „The checker cannot prove a download action, test results, a clean tree, or which command created the report.“

Bitte Monty, deine README aus Sicht einer Person zu lesen, die das Projekt noch nie gesehen hat, und die erste Anweisung zu nennen, die nicht aufgeschriebenes Wissen voraussetzt.