Salta ai contenuti

15. Progetto finale

Mettere insieme tutto ciò che hai visto nella Sezione 1 in un programma che potresti usare davvero:

  • scaricare dati in streaming (cap. 11);
  • validare ogni record con un modello tipizzato (cap. 7–8) scartando quelli rotti;
  • aggregare (conteggi, medie, top-N) con strutture dati del linguaggio;
  • scrivere un report JSON leggibile (cap. 4–6);
  • verificare il risultato contro una fonte indipendente (/api/v1/stats).

Dal catalogo della Libreria Aurora produrre report.json con questa forma:

{
"books": 80,
"avg_price": 19.9,
"by_category": [ { "category": "saggistica", "books": 14, "avg_price": 17.04 }, … ],
"top_authors": [ { "name": "Matteo Rinaldi", "books": 8 }, … ],
"formats": { "tascabile": 30, "brossura": 26, "rilegato": 24 }
}

Fonte: GET /api/v1/export/books.ndjson (un libro per riga, con author_name e category già risolti dal server). Verifica: GET /api/v1/stats, che calcola le stesse cose in SQL.

  1. Scarica l’export in streaming e, riga per riga, valida con un modello (Libro). Conta le righe scartate.
  2. Accumula gli aggregati mentre leggi (non tenere in memoria tutti i libri, anche se qui sono solo 80: è l’abitudine che conta).
  3. Costruisci il report e scrivilo su file con indentazione e UTF-8.
  4. Scarica /stats e confronta prezzo medio e libri per categoria: devono coincidere.

Le due chiamate che il programma farà, viste “nude”:

terminale
curl -s https://corso-api-json.giuseppebosi.com/api/v1/export/books.ndjson | wc -l
curl -s https://corso-api-json.giuseppebosi.com/api/v1/stats | jq '{prices, cat: .books_by_category[0:2], top: .top_authors[0:2]}'
| wc -l
conta le righe dell'export: 80, cioè i record, senza parsing
jq '{prices, cat: .books_by_category[0:2], top: .top_authors[0:2]}'
estrae i tre pezzi che il report deve riprodurre; [0:2] è uno slice: i primi due elementi
80
{
"prices": { "min": 7.13, "avg": 19.9, "max": 34.49 },
"cat": [ { "slug": "saggistica", "name": "Saggistica", "books": 14, "avg_price": 17.04 }, { "slug": "ragazzi", "name": "Ragazzi", "books": 12, "avg_price": 16.72 } ],
"top": [ { "id": 18, "name": "Matteo Rinaldi", "books": 8, "avg_rating": 4.22 }, { "id": 1, "name": "Elena Marchetti", "books": 6, "avg_rating": 3.12 } ]
}
"""Progetto finale: da NDJSON a report. pip install httpx pydantic · python progetto.py [report.json]"""
import json, sys
from collections import Counter, defaultdict
import httpx
from pydantic import BaseModel, Field, ValidationError
BASE = "https://corso-api-json.giuseppebosi.com"
class Libro(BaseModel): # il contratto: ciò che DEVE esserci per contare il libro
id: int
title: str = Field(min_length=1)
price: float = Field(ge=0)
author_name: str
category: str
in_stock: bool
attributes: dict
def scarica() -> list[Libro]:
libri, scartati = [], 0
with httpx.stream("GET", f"{BASE}/api/v1/export/books.ndjson", timeout=30) as r:
r.raise_for_status()
for riga in r.iter_lines():
if not riga:
continue
try:
libri.append(Libro.model_validate_json(riga)) # parsing + validazione in un colpo
except ValidationError as e:
scartati += 1
print("riga scartata:", e.errors()[0]["msg"], file=sys.stderr)
print(f"letti {len(libri)} libri, scartati {scartati}", file=sys.stderr)
return libri
def report(libri: list[Libro]) -> dict:
per_cat = defaultdict(list)
for l in libri:
per_cat[l.category].append(l.price)
autori = Counter(l.author_name for l in libri)
return {
"books": len(libri),
"avg_price": round(sum(l.price for l in libri) / len(libri), 2),
"by_category": sorted(
[{"category": c, "books": len(p), "avg_price": round(sum(p) / len(p), 2)} for c, p in per_cat.items()],
key=lambda x: -x["books"]),
"top_authors": [{"name": n, "books": k} for n, k in autori.most_common(3)],
"formats": dict(Counter(l.attributes.get("format", "n/d") for l in libri)),
}
def confronta(mio: dict) -> None:
ufficiale = httpx.get(f"{BASE}/api/v1/stats").json()
print("prezzo medio: mio", mio["avg_price"], "| server", ufficiale["prices"]["avg"], file=sys.stderr)
miei = {c["category"]: c["books"] for c in mio["by_category"]}
loro = {c["slug"]: c["books"] for c in ufficiale["books_by_category"]}
print("categorie uguali:", miei == loro, file=sys.stderr)
if __name__ == "__main__":
libri = scarica()
r = report(libri)
confronta(r)
destinazione = sys.argv[1] if len(sys.argv) > 1 else "report.json"
with open(destinazione, "w", encoding="utf-8") as f:
json.dump(r, f, indent=2, ensure_ascii=False)
print("scritto", destinazione, file=sys.stderr)

Output su stderr (il report va su file, così python progetto.py > altro non lo mescola):

letti 80 libri, scartati 0
prezzo medio: mio 19.9 | server 19.9
categorie uguali: True
scritto report.json

Scelte da notare: model_validate_json fa parsing e validazione insieme (più veloce di json.loads + model_validate); la lista libri è tenuta solo per chiarezza — per un export enorme passeresti i dati a report() mentre leggi; ensure_ascii=False mantiene leggibili le lettere accentate nel file.

GET/api/v1/stats— i numeri ufficiali con cui confrontare il tuo report

Provalo online, senza installare nulla:

Apri il notebook in Google Colab Apri il progetto TypeScript in StackBlitz

La richiesta GET diretta nel browser: https://corso-api-json.giuseppebosi.com/api/v1/stats

Python su Google Colab (serve un account Google gratuito per eseguire le celle); TypeScript su StackBlitz (si apre e parte da solo nel browser). Se l’API di prova è spenta, accendila da /api-attiva/.

  1. Robustezza: simula una riga corrotta (modifica una copia locale dell’export: togli una virgola, metti "price": "n/d") e verifica che il programma la scarti senza fermarsi.
  2. Top autori con pareggi: il server ordina gli autori a pari libri per nome. Fai lo stesso nel tuo report e confronta anche top_authors.
  3. Un secondo report: ordini.json da GET /api/v1/orders?limit=100 (paginato: leggi links.next finché non è null) con fatturato per stato e per città (shipping_address.city), da confrontare con /api/v1/stats (orders_by_status) e /api/v1/stats/sales?group_by=city.
Suggerimenti
  1. Salva l’export con curl -o libri.ndjson, modificalo, e fai leggere il file al programma (open("libri.ndjson") / createReadStream): il resto del codice non cambia — è il vantaggio di aver separato lettura e validazione.
  2. Python: sorted(autori.items(), key=lambda x: (-x[1], x[0]))[:3]. TS: .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).
  3. Un ciclo while url: r = get(url); …; url = r["links"]["next"]. Il fatturato per stato: somma di total raggruppata per status, escludendo cancelled se vuoi combaciare con /stats/sales.
  • Validare dopo aver aggregato: una riga rotta finisce nei conti prima che tu te ne accorga. Valida al confine, subito.
  • Arrotondare a metà strada: arrotonda solo nel report finale; nelle somme intermedie usa i numeri pieni.
  • Stampare il report su stdout insieme ai log: usa stderr per i messaggi e file/stdout per i dati.
  • sum(p) / len(p) con p vuoto: divisione per zero; qui non capita ma in un dataset vero sì.

Scarica in streaming, valida al confine, aggrega mentre leggi, scrivi UTF-8 leggibile, verifica contro una fonte indipendente. Prossimo passo: Sezione 2, capitolo 1 — HTTP e REST.