0%

Mit einer API kommunizieren · Abschlussprojekt

Abschlussprojekt: Projekt: Eine Seite sicher abrufen

Vervollständige einen Befehl, der genau eine Seite abruft, validiert und schreibt.

Die vorübergehende .venv der Website wird beim Wechsel zwischen Lektionen ausgeschlossen. Baue sie aus der gespeicherten Abhängigkeit neu auf, bevor du diesen Befehl ausführst:

python -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Verwende auf deinem eigenen Rechner die vorhandene Projektumgebung weiter, wenn die festgehaltene Abhängigkeit dort bereits installiert ist. Die Schnittstelle des Befehls ist bewusst klein:

.venv/bin/python api_catalog.py requested-page.json --page 1 --page-size 2

Der positionale Ausgabepfad ist erforderlich. Die Seite ist standardmäßig 1, die Seitengröße 2. --page muss mindestens 1 sein und --page-size zwischen 1 und 3 liegen. Weise ungültige Werte in argparse vor jedem HTTP-Aufruf mit Status 2 und stderr zurück. Es gibt keine Option für Basis-URL, Host, Token, Geheimnis oder Wiederholungen.

write_page(document, output_path) schreibt sichtbares UTF-8-JSON mit zwei Leerzeichen Einrückung, allow_nan=False und genau einem abschließenden Zeilenumbruch und gibt danach dasselbe Dokument zurück.

run_api_catalog(output_path, page, page_size, *, timeout=DEFAULT_TIMEOUT, session=None) ruft zuerst fetch_items_page auf. Erst nach erfolgreichem Abruf und erfolgreicher Validierung darf es write_page aufrufen. Bei Erfolg gibt es genau Wrote N items to OUTPUT_PATH. aus, schreibt nichts nach stderr und gibt 0 zurück.

Fange an dieser Befehlsgrenze nur die folgenden erwarteten Fehler mit dieser Bedeutung ab:

  • requests.Timeout: Practice API request timed out.

  • requests.ConnectionError: Could not connect to the practice API.

  • requests.HTTPError: Practice API returned HTTP STATUS. Nur bei 429 wird Retry after N second(s). aus dem Antwort-Header angehängt.

  • requests.exceptions.JSONDecodeError: Practice API returned invalid JSON.

  • ValueError aus der Antwortvalidierung: Practice API returned invalid data: MESSAGE

  • OSError bei der Ausgabe: Could not write OUTPUT_PATH: MESSAGE

Jede Fehlermeldung geht an stderr und führt zum Rückgabewert 1. Unerwartete RuntimeError, TypeError, Assertions, Fehler durch ungültige URLs und unabhängige Programmierfehler müssen mit ihrem Traceback weitergegeben werden. Ein vorher vorhandener Kontrollinhalt in der Ausgabedatei bleibt bei jedem Fehler vor Schreibbeginn unverändert. Dieses Projekt verspricht keine Wiederherstellung, sobald der Schreiber begonnen hat.

Halte main(argv=None) beim Import frei von Ausführung: Parse zuerst und übergib dann die drei Werte an run_api_catalog. Untersuche bei Erfolg die angeforderte JSON-Datei und lasse api_catalog.py, requirements.txt, API_CONTRACT.md und diese Datei im Arbeitsbereich. .venv, Caches und Bytecode sind abgeleitet und ausgeschlossen.

Eine Idee verbindet das ganze Projekt und sollte vor dem Bau klar ausgesprochen werden. Jede dieser Fehlermeldungen ist kurz, konkret und sagt der Person, die den Befehl ausführt, etwas, auf das sie reagieren kann. Keine ist ein Traceback, und keine besteht nur aus dem Wort „error“. Das ist der Unterschied zwischen einem Programm, das scheitert, und einem Programm, das hilfreich scheitert.

Die unerwarteten Fehler bleiben absichtlich unschön. Ein TypeError durch einen Fehler in deinem eigenen Code sollte beunruhigend aussehen, denn er bedeutet, dass eine deiner Annahmen über das Programm nicht stimmt.

Wann darf der Befehl die angeforderte Ausgabe erstmals zum Schreiben öffnen?

Aufgabe

Vervollständige die genauen Vorgaben für den Parser, write_page, run_api_catalog und das beim Import sichere main(argv=None). Rufe vor dem Schreiben ab und validiere; erhalte die Ausgabe bei jedem Fehler vor Schreibbeginn; erzeuge die vorgeschriebenen stdout-/stderr-Meldungen und Statuswerte; fange nur die dokumentierten erwarteten Ausnahmen ab. Behalte die dauerhaften Quellen, die genau festgelegte Abhängigkeit, die Vertragsnotiz und deine angeforderte JSON-Datei bei, ohne Aussagen über öffentliche Hosts, Wiederholungen, Geheimnisse, Belege aus Live-Aufrufen oder Bereitstellung zu machen.