La forma della chiamata, le soluzioni
Il ragionamento, il codice, le trappole
Per ogni rotta, sempre lo stesso ordine: in italiano → il codice → le trappole. Per le più difficili, anche il passo per passo.
La tua soluzione è diversa ma i test sono verdi? Probabilmente va bene: il nome della funzione e quello del parametro tra graffe li sceglie chi scrive. Confronta il ragionamento, non le singole parole. E leggi comunque le trappole: alcune passano un test e si rompono sull'altro.
Le soluzioni complete
La stessa cartella, con il codice al posto di pass. Aprila dopo averci provato: i test sono gli stessi.
Prima di scrivere una rotta: tre domande
Dalla rotta 3 in poi il decoratore e il def li scrivi tu. Prima del codice, leggi la richiesta del commento e rispondi a tre domande:
- Che verbo?
GET,POST,PUT: è la prima parola della richiesta, e diventa@app.get,@app.post,@app.put. - Cosa c'è prima del
?Il percorso. I pezzi fissi vanno nel decoratore così come sono; quelli che cambiano vanno tra graffe, e il loro nome torna neldef. - Cosa c'è dopo il
?, e cosa nel corpo? Ogni nome dopo il?è un argomento deldefcon un tipo semplice. Il corpo è un argomento solo, che ha per tipo uno stampo.
Poi, dopo la freccia, -> dict: tutte le rotte di questo esercizio rispondono con un dizionario.
1 · Il saluto
In italiano. Il nome arriva dal percorso, già pronto in nome. Lo metto dentro il testo del saluto.
@app.get("/saluto/{nome}")
def saluto(nome: str) -> dict:
return {"messaggio": f"Buon viaggio, {nome}!"}Le trappole.
| Il codice sbagliato | Cosa succede | Il test rosso |
|---|---|---|
return {"messaggio": "Buon viaggio, {nome}!"}, senza la f | Il testo esce così com'è, graffe comprese: 'Buon viaggio, {nome}!'. Senza la f davanti, Python non sostituisce niente | test_rotta_1_un_nome_nel_percorso, test_rotta_1_ogni_nome_il_suo |
2 · I minuti
In italiano. fermate arriva dal percorso, e grazie a int è già un numero. Rispondo con le fermate e con le fermate per tre.
@app.get("/minuti/{fermate}")
def minuti(fermate: int) -> dict:
return {"fermate": fermate, "minuti": fermate * MINUTI_PER_FERMATA}Il secondo test della rotta, quello con /minuti/quattro, era verde da subito: il 422 lo dà FastAPI, leggendo fermate: int, prima di chiamare la funzione.
Le trappole.
| Il codice sbagliato | Cosa succede | Il test rosso |
|---|---|---|
print({"fermate": fermate, "minuti": …}) al posto del return | Il dizionario finisce nel terminale del server, e la funzione restituisce None. Ma con -> dict hai promesso un dizionario: FastAPI controlla anche la risposta e si ferma con ResponseValidationError, Input should be a valid dictionary, 'input': None. Dal vivo è un 500 | test_rotta_2_un_numero_nel_percorso |
3 · Il giornaliero
In italiano. Le tre domande. Il verbo: GET. Prima del ?: /giornaliero, niente che cambia. Dopo il ?: persone, obbligatorio. Nessun corpo. Quindi un argomento solo, una query senza default, int per poterlo moltiplicare.
@app.get("/giornaliero")
def giornaliero(persone: int) -> dict:
return {"persone": persone, "euro": persone * EURO_GIORNALIERO}Passo per passo, con GET /giornaliero?persone=3:
| Pezzo | Dove va | Nel codice | Nella funzione vale |
|---|---|---|---|
GET | nel decoratore | @app.get | — |
/giornaliero | nel decoratore, fisso | "/giornaliero" | — |
?persone=3 | nel def, senza graffe | persone: int | 3 |
Le trappole.
| Il codice sbagliato | Cosa succede | Il test rosso |
|---|---|---|
@app.get("/giornaliero/{persone}") | Le persone finiscono nel percorso: la rotta risponde a /giornaliero/3, e la richiesta vera, /giornaliero?persone=3, trova un 404 Not Found. Anche quella senza persone dà 404, non 422 | test_rotta_3_le_persone_nella_query, test_rotta_3_senza_persone |
def giornaliero(persone) -> dict:, senza int | Nessun errore: persone resta il testo "3", e "3" * 7 ripete il testo sette volte. La risposta è {'persone': '3', 'euro': '3333333'} | test_rotta_3_le_persone_nella_query |
La seconda è un errore che non dà errori: il server risponde 200, con un numero assurdo. Il tipo nel def non è un abbellimento: è l'ordine a FastAPI di convertire.
4 · Il cartello
In italiano. Il gruppo arriva dalla query, ma può mancare. Se manca, il cartello ha solo il nome dell'agenzia; se c'è, anche il gruppo.
@app.get("/cartello")
def cartello(gruppo: str | None = None) -> dict:
if gruppo is None:
return {"cartello": "Agenzia Bellini"}
return {"cartello": f"Agenzia Bellini - {gruppo}"}= None nel def, is None dentro: si scrivono insieme.
Le trappole.
| Il codice sbagliato | Cosa succede | Il test rosso |
|---|---|---|
def cartello(gruppo: str) -> dict:, senza = None | Il gruppo diventa obbligatorio: /cartello da solo risponde 422, con "loc":["query","gruppo"] | test_rotta_4_senza_gruppo |
Solo return {"cartello": f"Agenzia Bellini - {gruppo}"}, senza l'if | Nessun errore: senza gruppo, l'f-string scrive quello che trova. Il cartello dice 'Agenzia Bellini - None' | test_rotta_4_senza_gruppo |
5 · Il tragitto
In italiano. Due query obbligatorie, da e a, tutte e due numeri. Le fermate sono la loro distanza, sempre positiva; i minuti, tre a fermata.
@app.get("/tragitto")
def tragitto(da: int, a: int) -> dict:
fermate = abs(a - da)
return {"fermate": fermate, "minuti": fermate * MINUTI_PER_FERMATA}L'ordine degli argomenti nel def e quello nella query non devono coincidere: FastAPI li abbina per nome. Anche /tragitto?a=5&da=1 funziona.
Le trappole.
| Il codice sbagliato | Cosa succede | Il test rosso |
|---|---|---|
fermate = a - da, senza abs | All'andata va bene. Al ritorno, da Piazza Query (5) a Via Variabile (2): {'fermate': -3, 'minuti': -9} | test_rotta_5_all_indietro |
6 · L'annuncio
In italiano. Il codice del treno cambia, e sta in mezzo al percorso: va tra graffe. Il binario sta dopo il ?: è una query, obbligatoria.
@app.get("/treni/{codice}/annuncio")
def annuncio(codice: str, binario: int) -> dict:
return {"annuncio": f"Il treno {codice} arriva al binario {binario}"}Passo per passo, con GET /treni/M12/annuncio?binario=2:
| Pezzo | Fisso o cambia? | Nel decoratore | Nel def | Nella funzione vale |
|---|---|---|---|---|
/treni/ | fisso | /treni/ | — | — |
M12 | cambia | {codice} | codice: str | "M12" |
/annuncio | fisso | /annuncio | — | — |
?binario=2 | cambia | niente | binario: int | 2 |
Le trappole.
| Il codice sbagliato | Cosa succede | Il test rosso |
|---|---|---|
{codice} nel decoratore, ma def annuncio(treno: str, binario: int) | Il server parte senza errori. Ma treno non è tra graffe: per FastAPI è una query, la cerca dopo il ?, non la trova. 422 con "loc":["query","treno"], anche alla richiesta giusta | test_rotta_6_percorso_e_query, test_rotta_6_senza_binario |
Ecco cosa dice pytest con questa trappola. Il messaggio riporta la risposta dell'API, e lì c'è il loc:
E AssertionError: GET /treni/M12/annuncio?binario=2 deve rispondere 200. Ha risposto 422 {"detail":[{"type":"missing","loc":["query","treno"],"msg":"Field required","input":null}]}. 422 con 'query' nel loc? Il nome tra graffe e quello nel def devono essere uguali
E assert 422 == 200
E + where 422 = <Response [422 Unprocessable Content]>.status_codeNel test leggi 422 Unprocessable Content, nel terminale del server 422 Unprocessable Entity: è lo stesso codice, con il nome nuovo e quello vecchio.
7 · Il preventivo
In italiano. Il verbo è POST, il percorso fisso. Il gruppo arriva intero, nel corpo: nel def è un argomento solo, che ha per tipo lo stampo Gruppo. Dentro, i campi si leggono con il punto.
@app.post("/preventivo")
def preventivo(dati: Gruppo) -> dict:
return {"nome": dati.nome, "persone": dati.persone, "euro": dati.persone * EURO_GIORNALIERO}Passo per passo. Cosa fa FastAPI con {"nome": "Classe 3B", "persone": 20}, prima di chiamare preventivo:
| Passo | Cosa fa |
|---|---|
| 1 | Legge il def: dati ha per tipo Gruppo, uno stampo. Guarda nel corpo |
| 2 | Legge il JSON: nome è un testo, persone un numero. I campi ci sono tutti |
| 3 | Crea l'oggetto Gruppo(nome="Classe 3B", persone=20) |
| 4 | Chiama preventivo(dati=…) con quell'oggetto. dati.persone vale 20, e 20 * 7 fa 140 |
Con il corpo {"nome": "Classe 3B"} si ferma al passo 2: manca persone, 422 con "loc":["body","persone"], e la funzione non parte.
Le trappole.
| Il codice sbagliato | Cosa succede | Il test rosso |
|---|---|---|
def preventivo(nome: str, persone: int) -> dict:, i campi come argomenti sciolti | Due nomi con un tipo semplice: per FastAPI sono due query. Il JSON non lo guarda nessuno, e la risposta è 422 con "loc":["query","nome"] e ["query","persone"] | test_rotta_7_il_corpo, test_rotta_7_manca_un_campo |
8 · Il gruppo cambia
In italiano. Due posti. L'id del gruppo cambia e sta nel percorso: tra graffe, e int. Il gruppo arriva nel corpo: lo stampo Gruppo. La risposta mette insieme i due: l'id dal percorso, il resto dal corpo.
@app.put("/gruppi/{gruppo_id}")
def sostituisci_gruppo(gruppo_id: int, dati: Gruppo) -> dict:
return {
"id": gruppo_id,
"nome": dati.nome,
"persone": dati.persone,
"euro": dati.persone * EURO_GIORNALIERO,
}Passo per passo, con PUT /gruppi/3 e il corpo {"nome": "Classe 3B", "persone": 22}:
| Argomento | Da dove | Vale |
|---|---|---|
gruppo_id: int | percorso: è tra graffe | 3 |
dati: Gruppo | corpo: è uno stampo | Gruppo(nome="Classe 3B", persone=22) |
È la forma di ogni PUT: nel capitolo CRUD su un dizionario la stessa riga del def salverà il gruppo nel dizionario, alla chiave gruppo_id.
Le trappole.
| Il codice sbagliato | Cosa succede | Il test rosso |
|---|---|---|
@app.post("/gruppi/{gruppo_id}"), copiato dalla rotta 7 | La rotta c'è, ma con un altro verbo: 405 Method Not Allowed, e l'header allow: POST ti dice quale verbo accetta | test_rotta_8_percorso_e_corpo, test_rotta_8_l_id_e_un_numero |
def sostituisci_gruppo(gruppo_id, dati: Gruppo), senza int | L'id resta un testo: {'id': '3'} invece di {'id': 3}. E /gruppi/tre risponde 200, con "id":"tre", invece di 422 | test_rotta_8_percorso_e_corpo, test_rotta_8_l_id_e_un_numero |
Il file intero
Nella soluzione, in cima, l'import è diventato from fastapi import FastAPI: HTTPException serviva solo per la riga del 501, e non c'è più. Lasciarlo non rompe niente, ma un import che non si usa è rumore per chi legge.
Accendi la soluzione con fastapi dev palestra/sportello.py e apri /docs: otto rotte, e per ognuna, sotto Parameters, i dati con (path) o (query); nelle rotte 7 e 8, il riquadro Request body. È la forma della chiamata, disegnata da FastAPI.