0%

Met een API communiceren · eindproject

Eindproject: Project: haal één veilige pagina op

Maak één commando af dat precies één pagina ophaalt, valideert en wegschrijft.

De tijdelijke .venv op de site gaat niet mee van les naar les. Bouw die opnieuw op vanuit de opgeslagen dependency voordat je dit commando uitvoert:

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

Gebruik op je eigen computer je bestaande projectomgeving als de vastgelegde dependency daar al is geïnstalleerd. De interface van het commando is bewust klein:

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

Het positionele uitvoerpad is verplicht. Het paginanummer is standaard 1 en de paginagrootte 2. --page moet minstens 1 zijn en --page-size moet 1 tot en met 3 zijn. Wijs ongeldige waarden in argparse af met status 2 en stderr vóór een HTTP-aanroep. Er is geen optie voor een basis-URL, host, token, geheim of nieuwe poging.

write_page(document, output_path) schrijft zichtbare UTF-8-JSON met inspringing van twee spaties, allow_nan=False en precies één afsluitend regeleinde. Daarna geeft de functie hetzelfde document terug.

run_api_catalog(output_path, page, page_size, *, timeout=DEFAULT_TIMEOUT, session=None) roept eerst fetch_items_page aan. Pas nadat ophalen en valideren zijn geslaagd, mag die write_page aanroepen. Succes drukt precies Wrote N items to OUTPUT_PATH. af, schrijft niets op stderr en geeft 0 terug.

Vang bij deze commandogrens alleen de volgende verwachte fouten op, met deze betekenis:

  • requests.Timeout: Practice API request timed out.

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

  • requests.HTTPError: Practice API returned HTTP STATUS. Voeg alleen voor 429 Retry after N second(s). toe vanuit de antwoordheader.

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

  • ValueError bij antwoordvalidatie: Practice API returned invalid data: MESSAGE

  • OSError bij uitvoer: Could not write OUTPUT_PATH: MESSAGE

Elke foutmelding gaat naar stderr en geeft 1 terug. Onverwachte RuntimeError, TypeError, asserties, defecten met ongeldige URL’s en andere programmeerfouten moeten met hun traceback verdergaan. De herkenbare begininhoud van bestaande uitvoer blijft ongewijzigd bij elke fout vóór het schrijven begint. Dit project belooft niet dat wijzigingen worden teruggedraaid nadat de schrijver is gestart.

Houd main(argv=None) veilig om te importeren: ontleed eerst de argumenten en geef de drie waarden daarna door aan run_api_catalog. Bekijk bij succes het gevraagde JSON-bestand en laat api_catalog.py, requirements.txt, API_CONTRACT.md en dat uitvoerbestand in de werkruimte staan. .venv, caches en bytecode zijn afgeleid en worden uitgesloten.

Eén idee verbindt dit hele project. Dat is het waard om vóór het bouwen helder uit te spreken. Elke foutmelding is kort en specifiek en vertelt degene die het commando uitvoert iets waarmee die verder kan. Geen enkele is een traceback en geen enkele bestaat alleen uit het woord “fout”. Dat is het verschil tussen een programma dat faalde en een programma dat bruikbaar faalde.

De onverwachte fouten blijven bewust onaangenaam. Een TypeError door een defect in je eigen code hoort alarmerend te ogen, want die betekent dat iets wat je over je programma geloofde niet waar is.

Wanneer mag het commando het gevraagde uitvoerbestand voor het eerst openen om te schrijven?

Opdracht

Voltooi het exacte contract voor de parser, write_page, run_api_catalog en een veilig importeerbare main(argv=None). Haal op en valideer vóór het schrijven; behoud uitvoer bij elke fout vóór het schrijven; gebruik de opgegeven stdout/stderr en statussen; vang alleen de gedocumenteerde verwachte excepties op. Laat de blijvende broncode, exact vastgezette dependency, contractnotitie en je gevraagde JSON-bestand staan. Doe geen uitspraken over openbare hosts, nieuwe pogingen, geheimen, bewijs van live gedrag of deployment.