Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

HTTP e API7. CRUD su un dizionariop. 201

La centrale della Linea Menta

Un'API a sette livelli, e la sala controllo

  • 120–150 minuti di lavoro

Milano, 4:30 del mattino. Centrale operativa della Linea Menta.

È la Giornata della Linea. Alle 6:00 Vecchia Fiera, la stazione chiusa al pubblico da vent'anni, riapre per un giorno solo, e il primo treno della giornata, l'M30 nuovo di fabbrica, deve partire da lì.

Ernesto Pozzi, il capo deposito, ti passa il portatile. «Il programma della centrale è nuovo, e mezzo vuoto. Ha l'archivio dei treni e delle stazioni, ma poche rotte. La sala controllo dà il via libera solo se il piano è fatto, e solo con le quattro cifre del codice del mattino. Le cifre te le dà la rete, se le fai le domande giuste.»

Gli esercizi da scaricare

Una cartella con i file da completare e i test già pronti. Come si usa: la guida in cinque passi.

http-crud-su-un-dizionario.zip30 KB

Lo zip è lo stesso della palestra: la storia è nella cartella storia/.

Le quattro cifre

Il codice del mattino è fatto di quattro cifre, una per ogni domanda alla rete. Si leggono prima del piano, con la rete com'è alle 4:30: dopo il livello 5 i conti cambiano. Ogni risposta è un numero da 1 a 9.

  1. Quante stazioni sono aperte (livello 1).
  2. L'id di Vecchia Fiera (livello 2).
  3. Quanti tram ci sono in rete (livello 3).
  4. Quanti treni sono fermi a Vecchia Fiera (livello 4).

Il piano

  1. L'M30 entra in rete, a Vecchia Fiera: metro, 6 vagoni, nessun guasto (livello 5).
  2. I due treni guasti vanno al Deposito, la stazione 7. Restano guasti: un guasto non si ripara con una PUT, il treno si sposta e basta (livello 6).
  3. Il treno di servizio che occupa il binario di Vecchia Fiera esce di rete (livello 7).

I file

FileCosa c'èSi tocca?
rete.pyGli stampi (Stazione, TrenoNuovo, Treno), le stazioni e i treni della notte, prossimo_idNo, si legge
sala_controllo.pyLa sala controllo: POST /sala-controllo/via-liberaNo
centrale.pyLa tua API, un livello alla voltaSì, solo questo
test_centrale.pyI test, con una rete di prova (così non ti dicono le cifre)No

In rete.py ci sono i due dizionari, stazioni e treni, e gli stampi. Una stazione ha un id, un nome e aperta (False: chiusa al pubblico). Un treno ha id, codice, tipo (metro, tram, servizio), vagoni, stazione_id (dov'è fermo) e guasto (None: sta bene). Gli oggetti si leggono con il punto: treni[5].codice.

Come si gioca

Un livello alla volta, sempre così:

  1. In centrale.py, leggi il commento del livello: la richiesta, la risposta, la cosa nuova.
  2. Scrivi la rotta al posto della riga «ancora da fare» (dal livello 3, anche decoratore e def: il commento te li dà).
  3. pytest storia -v -k livello_1 (poi livello_2, …) finché è verde.
  4. In un secondo terminale: fastapi dev storia/centrale.py, poi http://127.0.0.1:8000/docs. Prova la rotta con Try it out ed Execute, sulla rete vera.

Nel primo terminale i test, nel secondo il server (con il venv acceso, entrambi). Un livello non provato è un livello da rifare: i test usano una rete di prova, la rete vera la vedi solo da /docs.

Con lo scheletro ancora com'è, ogni test è rosso con il 501:

Terminale
pytest storia -v -k livello_1
collecting ... collected 21 items / 19 deselected / 2 selected

storia/test_centrale.py::test_livello_1_solo_le_stazioni_aperte FAILED                       [ 50%]
storia/test_centrale.py::test_livello_1_nessuna_stazione_aperta FAILED                       [100%]

============================================= FAILURES =============================================
______________________________ test_livello_1_solo_le_stazioni_aperte ______________________________

    def test_livello_1_solo_le_stazioni_aperte():
        risposta = client.get("/stazioni")
>       assert risposta.status_code == 200, "GET /stazioni deve rispondere 200. C'è ancora la riga del 501?"
E       AssertionError: GET /stazioni deve rispondere 200. C'è ancora la riga del 501?
E       assert 501 == 200
E        +  where 501 = <Response [501 Not Implemented]>.status_code

storia/test_centrale.py:48: AssertionError
…
================================= 2 failed, 19 deselected in 0.17s =================================

Livello 1 · Le stazioni aperte

«Quante stazioni sono aperte, stanotte?»

GET /stazioni: la lista delle stazioni aperte, nell'ordine del dizionario. Le chiuse non ci sono.

La cosa nuova: un if dentro il for: il setaccio. È l'esempio A degli esercizi spiegati.

Aiutino 1
Lista vuota, for sulle stazioni (stazioni.values()), if sul campo aperta, append. Il return va fuori dal for.
Aiutino 2
aperta è già un vero o falso: l'if può essere solo if stazione.aperta:, senza confronti.

Quando funziona, da /docs fai Try it out e Execute su GET /stazioni: conta le stazioni che tornano. È la prima cifra.


Livello 2 · Una stazione

«Qual è l'id di Vecchia Fiera?»

GET /stazioni/{stazione_id}: la stazione, anche se è chiusa. Se l'id non c'è, 404 con il detail Stazione non trovata.

La cosa nuova: il 404 lo scrivi tu. In cima al file c'è trova_treno, già pronta: lo schema è lo stesso. È l'esempio B.

Aiutino 1
Copia lo schema di trova_treno: get sul dizionario stazioni, if … is None, raise HTTPException(status_code=404, detail="Stazione non trovata"), return. Occhio al detail: «non trovata», al femminile.

Vecchia Fiera nella lista del livello 1 non c'è: è chiusa. Come trovi il suo id? Prova un id alla volta, da /docs, finché la stazione che torna è quella giusta (e quando ti dice 404, hai superato l'ultimo). È la seconda cifra.


Livello 3 · I treni, con un filtro

«Quanti tram ci sono in rete?»

GET /treni: tutti i treni. GET /treni?tipo=tram: solo i tram. GET /treni?tipo=funivia: una lista vuota (e 200).

La cosa nuova: un filtro facoltativo, nella query. Dal livello 3 scrivi tu anche il decoratore e la riga del def: te li dà il commento. È la teoria, sezione 1: prima il caso «nessun filtro».

Aiutino 1
Il def ha un argomento, tipo: str | None = None. Se tipo è None: return list(treni.values()).
Aiutino 2
Altrimenti, il setaccio: lista vuota, for sui treni, if treno.tipo == tipo, append.

Da /docs: tipo = tram, Execute. Conta i tram: è la terza cifra.


Livello 4 · I treni di una stazione

«Quanti treni sono fermi a Vecchia Fiera?»

GET /stazioni/{stazione_id}/treni: i treni fermi in quella stazione (nessuno? lista vuota). Se la stazione non c'è, 404 con il detail Stazione non trovata.

La cosa nuova: niente. Sono due cose che sai già, in un ordine solo: il 404 del livello 2 e il setaccio del livello 3, uno dopo l'altro. Prima il 404, poi il lavoro.

Aiutino 1
La stazione la hai già: la rotta del livello 2 si chiama leggi_stazione, e puoi chiamarla come una funzione normale. Se la stazione non c'è, lancia lei il 404.
Aiutino 2
Dopo, il setaccio sui treni: l'if guarda treno.stazione_id == stazione_id.

Da /docs, con l'id di Vecchia Fiera. Conta i treni: è la quarta cifra. Scrivile tutte e quattro in ordine, su un foglio.


Livello 5 · L'M30 entra in rete

«L'M30 è arrivato dalla fabbrica. Mettetelo a Vecchia Fiera.»

POST /treni, con il corpo {"codice": "M30", "tipo": "metro", "vagoni": 6, "stazione_id": 6}: 201 e il treno nuovo, con l'id scelto dal server. Se nel corpo manca un campo, 422 (ci pensa FastAPI). guasto si può non mandare: vale None.

La cosa nuova: il corpo, il 201 e l'id scelto dal server. È l'esempio C, e l'esercizio 3 della palestra.

Aiutino 1
Il def riceve dati: TrenoNuovo e restituisce un Treno. Il 201 sta nel decoratore: status_code=status.HTTP_201_CREATED.
Aiutino 2
L'id con prossimo_id(treni): non len(treni) + 1. In rete i treni hanno dei buchi negli id (il 7 è stato rottamato l'anno scorso, e il suo numero non si riusa).
Aiutino 3
Treno(id=…, codice=dati.codice, tipo=dati.tipo, vagoni=dati.vagoni, stazione_id=dati.stazione_id, guasto=dati.guasto), poi treni[treno.id] = treno, poi return treno.

Da /docs, Try it out sul POST /treni con il corpo di sopra. Controlla che la risposta sia 201 e che il treno compaia in GET /treni.


Livello 6 · I treni guasti vanno al Deposito

«I due treni guasti non possono stare in linea. Portateli al Deposito.»

PUT /treni/{treno_id}, con il corpo di un TrenoNuovo: tutti i campi, anche quelli che non cambiano. Risposta: 200 e il treno com'è adesso, con l'id dal percorso. Se l'id non c'è: 404 con il detail Treno non trovato, e il treno non va creato.

La cosa nuova: percorso e corpo nella stessa richiesta. Stessa chiave, scatola nuova. È l'esempio D e l'esercizio 4 della palestra.

Il piano: i due treni guasti (guarda GET /treni: hanno un guasto che non è null) vanno alla stazione 7, il Deposito. Un treno guasto resta guasto: nella PUT mandi di nuovo il suo guasto, e tutto il resto com'era, tranne stazione_id.

Aiutino 1
trova_treno è già pronta: la prima riga della funzione è trova_treno(treno_id), per il 404. Non serve nemmeno guardare cosa restituisce.
Aiutino 2
Costruisci un Treno(id=treno_id, …) con tutti i campi presi da dati, e mettilo in treni[treno_id].
Aiutino 3
Per fare il piano da /docs: leggi il treno con GET /treni/{treno_id}, copia i suoi campi nel corpo della PUT (senza l'id), cambia solo stazione_id in 7. Se dimentichi guasto, vale null: il treno «guarisce», e la sala controllo se ne accorge.

Livello 7 · Via il treno di servizio

«Sul binario di Vecchia Fiera c'è ancora un treno di servizio. Deve uscire di rete.»

DELETE /treni/{treno_id}: 204, senza corpo. Se l'id non c'è (anche la seconda volta): 404 con il detail Treno non trovato.

La cosa nuova: il 204 e del. È l'esempio D e l'esercizio 5 della palestra.

Aiutino 1
Il decoratore ha due cose: il percorso e status_code=status.HTTP_204_NO_CONTENT. La funzione è -> None e non ha nessun return.
Aiutino 2
Prima il 404 (trova_treno), poi del treni[treno_id].

Il treno da togliere è quello di tipo servizio che è fermo a Vecchia Fiera: lo trovi con il livello 4.


Il finale

Il piano, tutto di fila, da /docs, senza salvare centrale.py in mezzo (a ogni salvataggio il server riparte e la rete torna com'era alle 4:30):

  1. Le quattro cifre, con i livelli 1–4. Scrivile su un foglio.
  2. Il piano, con i livelli 5, 6 e 7. Gli id dei treni giusti li trovi con GET /treni e GET /stazioni/{stazione_id}/treni.
  3. POST /sala-controllo/via-libera, con il corpo {"cifre": "…"}: le tue quattro cifre, attaccate, tra virgolette. Per esempio, se fossero 1, 2, 3 e 4: {"cifre": "1234"}.

La sala controllo, prima di guardare le cifre, controlla il piano: legge i dizionari di rete.py. Se manca qualcosa, risponde 403 e dice cosa. Per esempio, con il piano ancora da fare (risposta vera, con le cifre che vuoi):

JSON
{"detail": "Il piano non è fatto: il treno M30 non è in rete (livello 5); il treno T09 (id 5) è guasto e non è ancora al Deposito (livello 6); il treno M18 (id 8) è guasto e non è ancora al Deposito (livello 6); il treno di servizio S01 (id 6) occupa ancora il binario di Vecchia Fiera (livello 7)."}

Se il piano è fatto ma le cifre sono sbagliate, 403 anche lì:

JSON
{"detail": "Il piano è fatto, ma le cifre non tornano. Si leggono con la rete com'era alle 4:30, prima del livello 5. Se salvi centrale.py la rete torna com'era: poi va rifatto anche il piano."}

Se risponde 200, alle 6:00 si parte.

Per chi finisce prima, un extra senza test: il 409. Se qualcuno prova a mettere in rete un treno con un codice già usato da un altro, la POST (e la PUT, tranne per sé stessa) deve rifiutare, con detail="Codice già usato da un altro treno". Lo schema è quello dell'esercizio 6 della palestra.

Le soluzioni e le trappole sono qui. Quando il server si spegne, la rete torna com'era: nel prossimo libro, Il database nell'API, i dati smettono di sparire.