Il contratto, la palestra
Tre servizi, tre contratti, con i test
- 60–90 minuti di lavoro
Tre servizi nuovi della Linea Menta, dal ★ al ★★★. Ognuno ha il suo canvas già riempito, in un commento in cima al file, e gli stampi già scritti: il contratto lo scrivi tu. Prima la tabella delle rotte, poi le rotte in FastAPI, con il 501 dentro. I test leggono il contratto: quando è tutto verde, hai finito.
Gli esercizi da scaricare
Una cartella con i file da completare e i test già pronti. Come si usa: la guida in cinque passi.
Prima di iniziare
Scompatta lo zip e segui il README.md che c'è dentro: venv, pip install -r requirements.txt, code .. Se è la prima volta, la pagina Come si usa un esercizio lo fa con te, un comando alla volta.
Ogni esercizio, sempre gli stessi cinque passi:
- Apri il file in
palestra/. In alto: la storia, cosa fai, come provi. Sotto: gli stampi e il canvas. - Riempi la sua tabella in
ROTTE.md, nella cartella dello zip: una riga per azione. Su carta va bene uguale. I test non la guardano, ma è lì che si pensa. - Sotto il canvas, una rotta per azione: il decoratore, la riga del
def, e dentro solo la riga del contratto,raise HTTPException(status_code=501, …). pytest palestra/test_<nome>.py -v. Rosso? L'ultima riga del messaggio dice quale rotta manca o cosa non torna.- Tutto verde?
fastapi dev palestra/<nome>.pye aprihttp://127.0.0.1:8000/docs: è il tuo contratto, come lo vedrà chi usa l'API.
| # | Esercizio | Cosa c'è di nuovo | Difficoltà |
|---|---|---|---|
| 1 | Gli estintori delle stazioni | una risorsa, i quattro verbi | ★ |
| 2 | Gli interventi dell'officina | un filtro e una sotto-risorsa | ★★ |
| 3 | Le visite guidate a Vecchia Fiera | due risorse collegate, e il 409 nel contratto | ★★★ |
In ogni file di test, l'ultimo test è quello delle cinque regole dei percorsi: controlla tutte le rotte del file insieme. Se diventa rosso, il messaggio dice quale rotta e quale pezzo del percorso.
1 · Gli estintori delle stazioni ★
palestra/estintori.py
Nadia Russo, la guardia giurata, ogni mese controlla gli estintori di tutte le stazioni e li segna su un quaderno. Vuole un'API. Una cosa sola, cinque azioni, e la prima è già scritta: è l'esempio.
Riquadro 6 · le cose: gli estintori → /estintori
Riquadro 7 · le azioni:
1. vedo tutti gli estintori (già fatta: l'esempio)
2. vedo un estintore
3. registro un estintore nuovo
4. segno un controllo: cambia la data dell'ultimo controllo
5. tolgo un estintore (è scaduto e l'hanno portato via)Gli stampi: EstintoreNuovo (stazione, posizione, data dell'ultimo controllo: quello che manda il client, senza id) ed Estintore (gli stessi campi più l'id: quello che torna indietro).
Come provi: pytest palestra/test_estintori.py -v
Lanciato subito, prima di scrivere niente:
palestra/test_estintori.py::test_1_vedo_tutti_gli_estintori PASSED [ 16%]
palestra/test_estintori.py::test_2_un_estintore_con_l_id_nel_percorso FAILED [ 33%]
palestra/test_estintori.py::test_3_registrare_e_una_post_con_il_corpo_e_il_201 FAILED [ 50%]
palestra/test_estintori.py::test_4_il_controllo_e_una_put_con_l_id_e_il_corpo FAILED [ 66%]
palestra/test_estintori.py::test_5_togliere_e_una_delete_con_il_204 FAILED [ 83%]
palestra/test_estintori.py::test_6_le_cinque_regole_dei_percorsi PASSED [100%]
…
=================================== 4 failed, 2 passed in 0.15s ====================================I due verdi sono l'esempio e le regole: con la sola rotta dell'esempio, le regole sono rispettate. Il test delle regole resta verde solo se anche le tue rotte le rispettano.
Aiutino 1
Aiutino 2
PUT su /estintori/{estintore_id}, con tutti i campi nel corpo. Niente /controllo nel percorso.Aiutino 3
POST: status_code=status.HTTP_201_CREATED nel decoratore e dati: EstintoreNuovo nel def. Nella DELETE: status_code=status.HTTP_204_NO_CONTENT e -> None.2 · Gli interventi dell'officina ★★
palestra/interventi.py
Al deposito, Ivo Brambati segna su una lavagna i lavori da fare sui treni: le porte del T09, i freni dell'M14. Vuole un'API anche per questo. Nel canvas ci sono due cose, ma una sola si crea e si cancella: i treni ci sono già, qui si guardano soltanto.
Riquadro 6 · le cose: gli interventi → /interventi
i treni → /treni (ci sono già: si guardano soltanto)
Riquadro 7 · le azioni:
1. vedo gli interventi, anche solo quelli in uno stato (solo gli aperti, o solo i chiusi)
2. apro la scheda di un treno e vedo i suoi interventi (se il treno non c'è: 404)
3. apro un intervento nuovo
4. chiudo un intervento: il lavoro è fatto, lo stato diventa "chiuso"
5. cancello un intervento aperto per sbaglioGli stampi: InterventoNuovo (il treno, il lavoro, lo stato) e Intervento (con l'id).
Come provi: pytest palestra/test_interventi.py -v
Aiutino 1
stato: str | None = None.Aiutino 2
/treni. Rileggi «Filtro o sotto-risorsa?» nella teoria.Aiutino 3
PUT /interventi/{intervento_id}, con tutto l'intervento nel corpo e lo stato nuovo. Non /chiudi.3 · Le visite guidate a Vecchia Fiera ★★★
palestra/visite.py
Vecchia Fiera è chiusa al pubblico da vent'anni, ma tutti la vogliono vedere. Marta Villa organizza le visite guidate: pochi posti, e si prenota. Rosa Bellini, per esempio, prenota per tutto il gruppo della sua agenzia. Due cose, collegate: ogni prenotazione è per una visita.
Riquadro 6 · le cose: le visite → /visite
le prenotazioni → /prenotazioni (ognuna è per una visita)
Riquadro 7 · le azioni:
1. vedo le visite in programma
2. vedo una visita
3. aggiungo una visita al programma
4. vedo chi ha prenotato una visita (se la visita non c'è: 404)
5. prenoto dei posti per una visita (se i posti liberi non bastano: 409, posti esauriti)
6. disdico una prenotazioneGli stampi: VisitaNuova e Visita, PrenotazioneNuova e Prenotazione. Dentro PrenotazioneNuova c'è già visita_id: la visita da prenotare arriva nel corpo.
Questa volta nel file non ci sono i commenti per ogni rotta: le scrivi tutte tu, nell'ordine del canvas.
Come provi: pytest palestra/test_visite.py -v
Aiutino 1
/visite e /prenotazioni. Per ogni azione chiediti prima di quale delle due parla, poi legge o scrive, poi una o tante.Aiutino 2
/visite/{visita_id}/prenotazioni. «Prenoto» invece crea una prenotazione, e la visita è già nel corpo: POST /prenotazioni.Aiutino 3
responses={409: {"description": "Posti esauriti"}} nel decoratore, accanto a status_code. Se la riga diventa lunga, vai a capo dopo la parentesi, un pezzo per riga, come la POST /permessi della teoria.Finito? Accendi ognuno dei tre e apri /docs: è quello che vedrà chi userà le tue API. Poi confronta con le soluzioni, che mostrano anche le tre tabelle delle rotte.
E poi tocca al tuo progetto: prendi il tuo canvas, riquadri 6, 7 e 8, e scrivi la tua tabella delle rotte. Da 5 a 10 righe, in un ROTTE.md nel repository del progetto.