Depends, da zero, esercizi spiegati
Cinque esempi nella lavanderia del deposito
- 30 minuti di lettura
Cinque esempi, dal più semplice, tutti nella lavanderia dei treni del deposito di Ernesto Pozzi. Un robot di lavaggio e un programma di contabilità leggono i dati della lavanderia, e ognuno ha la sua chiave. Ogni esempio ha lo stesso ritmo:
- Prevedi: leggi il codice e scrivi su un foglio cosa risponde (e, quando c'è, cosa stampa il server). Prima di aprire la risposta.
- In italiano: cosa fa il programma, a parole.
- Passo per passo: cosa succede a ogni richiesta.
- Cosa portiamo a casa: la cosa da ricordare.
Per provarli: scarica lo zip della palestra (il README.md dice come prepararlo), salva il codice in un file dentro palestra/, per esempio palestra/lavanderia_a.py, e dalla cartella dello zip, con il venv acceso, accendi il server con fastapi dev palestra/lavanderia_a.py. Le richieste si lanciano da un secondo terminale, sempre con il venv acceso. Le chiavi qui sono finte e scritte nel codice solo per imparare: quelle vere stanno nel .env, come nel capitolo 2.
A · Cosa fa FastAPI, e in che ordine
Per vedere con i tuoi occhi che il controllore parte prima della rotta, mettiamo una scritta in tutte e due. Il robot di lavaggio legge i lavaggi.
from fastapi import Depends, FastAPI, Header, HTTPException
app = FastAPI(title="La lavanderia del deposito")
CHIAVE_LAVANDERIA = "5d1e8b3a7c2f4096" # di prova: quella vera sta nel .env
LAVAGGI = [{"treno": "M12", "programma": "completo"}, {"treno": "M14", "programma": "rapido"}]
DETERSIVI = {"schiuma": 8, "sgrassante": 3}
def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
print(" 1. parte controlla_chiave")
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
if chiave != CHIAVE_LAVANDERIA:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return "robot di lavaggio"
@app.get("/lavaggi")
def leggi_lavaggi(programma: str = Depends(controlla_chiave)) -> dict:
print(" 2. parte la rotta")
return {"lavaggi": LAVAGGI}
@app.get("/detersivi")
def leggi_detersivi(programma: str = Depends(controlla_chiave)) -> dict:
print(" 2. parte la rotta")
return {"detersivi": DETERSIVI}Tre richieste a /lavaggi: senza chiave, con la chiave sbagliata, con quella giusta.
curl -s http://127.0.0.1:8000/lavaggi
curl -s http://127.0.0.1:8000/lavaggi -H "X-API-Key: abc123"
curl -s http://127.0.0.1:8000/lavaggi -H "X-API-Key: 5d1e8b3a7c2f4096"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Le risposte:
{"detail":"Manca la chiave"}
{"detail":"Chiave sbagliata"}
{"lavaggi":[{"treno":"M12","programma":"completo"},{"treno":"M14","programma":"rapido"}]}E nel terminale del server, le scritte con il registro delle richieste:
1. parte controlla_chiave
INFO: 127.0.0.1:63272 - "GET /lavaggi HTTP/1.1" 401 Unauthorized
1. parte controlla_chiave
INFO: 127.0.0.1:63273 - "GET /lavaggi HTTP/1.1" 401 Unauthorized
1. parte controlla_chiave
2. parte la rotta
INFO: 127.0.0.1:63274 - "GET /lavaggi HTTP/1.1" 200 OKIl numero di porta nel registro sarà diverso. Guarda le prime due richieste: la scritta 2 non compare. Quando il controllore fa raise, la rotta non parte nemmeno.
In italiano. Per ogni richiesta FastAPI chiama prima controlla_chiave. Se questa fa raise, la risposta è il 401 e basta. Se fa return, il valore va nel parametro programma e parte la rotta.
Passo per passo.
| Richiesta | Scritta 1 | controlla_chiave | Scritta 2 | Risposta |
|---|---|---|---|---|
| nessun header | sì | raise: «Manca la chiave» | no | 401 |
X-API-Key: abc123 | sì | raise: «Chiave sbagliata» | no | 401 |
| la chiave giusta | sì | return "robot di lavaggio" | sì | 200 |
Cosa portiamo a casa. Il controllore parte sempre; la rotta solo se il controllore non ha fatto raise. Tutte e due le rotte usano la stessa funzione: il controllo è scritto una volta.
B · Il parametro vale il return
Adesso la lavanderia ha due programmi, ognuno con la sua chiave: un dizionario chiave → chi è. La rotta scrive nella risposta chi ha bussato.
from fastapi import Depends, FastAPI, Header, HTTPException
app = FastAPI(title="La lavanderia del deposito")
CHIAVI = {
"5d1e8b3a7c2f4096": "robot di lavaggio",
"c07a92e41b5d38f6": "contabilità",
}
DETERSIVI = {"schiuma": 8, "sgrassante": 3}
def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
programma = CHIAVI.get(chiave) # None se la chiave non c'è
if programma is None:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return programma
@app.get("/detersivi")
def leggi_detersivi(programma: str = Depends(controlla_chiave)) -> dict:
return {"programma": programma, "detersivi": DETERSIVI}Quattro richieste: senza chiave, con una sbagliata, con la chiave del robot, con quella della contabilità.
curl -s http://127.0.0.1:8000/detersivi
curl -s http://127.0.0.1:8000/detersivi -H "X-API-Key: abc123"
curl -s http://127.0.0.1:8000/detersivi -H "X-API-Key: 5d1e8b3a7c2f4096"
curl -s http://127.0.0.1:8000/detersivi -H "X-API-Key: c07a92e41b5d38f6"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"detail":"Manca la chiave"}
{"detail":"Chiave sbagliata"}
{"programma":"robot di lavaggio","detersivi":{"schiuma":8,"sgrassante":3}}
{"programma":"contabilità","detersivi":{"schiuma":8,"sgrassante":3}}Le ultime due risposte hanno gli stessi detersivi, ma un programma diverso: il parametro vale quello che il controllore ha restituito, e ogni chiave porta un nome diverso.
In italiano. Il controllore cerca la chiave nel dizionario: se manca l'header, 401; se la chiave non c'è, 401; se c'è, restituisce il nome del programma. La rotta riceve quel nome e lo scrive nella risposta.
Passo per passo.
| Richiesta | chiave | CHIAVI.get(chiave) | Il controllore | programma nella rotta |
|---|---|---|---|---|
| nessun header | None | non si arriva | raise 401 | la rotta non parte |
abc123 | "abc123" | None | raise 401 | la rotta non parte |
5d1e… | "5d1e8b3a7c2f4096" | "robot di lavaggio" | return | "robot di lavaggio" |
c07a… | "c07a92e41b5d38f6" | "contabilità" | return | "contabilità" |
E se il controllore dimentica il return? Prova a toglierlo, l'ultima riga di controlla_chiave. Con la chiave del robot:
{"programma":null,"detersivi":{"schiuma":8,"sgrassante":3}}La risposta è 200 e programma è null: la funzione è finita senza restituire niente, quindi None. Nessun errore: è l'errore più silenzioso della pagina.
Cosa portiamo a casa. Il parametro della rotta è il return del controllore. Senza return, è None, e nessuno ti avvisa.
C · Le parentesi
Il guaio che fanno tutti. Il controllore è quello dell'esempio A, la rotta ha una coppia di parentesi in più:
@app.get("/detersivi")
def leggi_detersivi(programma: str = Depends(controlla_chiave())) -> dict:
return {"programma": programma, "detersivi": DETERSIVI}Salvi il file, accendi il server con fastapi dev. Cosa succede?
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Il server non parte. Nel terminale, dentro il messaggio lungo, le righe che contano (qui senza la cornice e i colori) (il percorso del file sarà il tuo):
…/palestra/lavanderia_c.py:18 in <module>
18 def leggi_detersivi(programma: str = Depends(controlla_chiave())) -> dict:
…/palestra/lavanderia_c.py:13 in controlla_chiave
13 raise HTTPException(status_code=401, detail="Chiave sbagliata")
HTTPException: 401: Chiave sbagliataIl 401 non l'ha mandato nessun client: è il raise del controllore, scattato mentre Python leggeva il file.
In italiano. Python, leggendo la riga del def, trova controlla_chiave() con le parentesi e la chiama subito. Nessuna richiesta, nessun header: il parametro chiave non vale None, vale il suo valore predefinito (l'oggetto Header(…)). Non è None, e non è la chiave giusta: quindi il secondo if fa raise con «Chiave sbagliata». E lo fa prima ancora che il server sia acceso.
Il secondo errore. Se invece togli del tutto = Depends(…):
def leggi_detersivi(programma: str) -> dict:il server parte, ma per FastAPI programma è un parametro della query, che nessuno ha mandato. Con la chiave giusta nell'header:
{"detail":[{"type":"missing","loc":["query","programma"],"msg":"Field required","input":null}]}loc dice dove cercava (query), msg dice cosa mancava. Un 422, e il controllore non è mai partito. Peggio: chiamando /detersivi?programma=io la rotta risponde 200 con "programma":"io", senza nessuna chiave. La protezione era in quel = Depends(…).
Cosa portiamo a casa. Depends(controlla_chiave): la funzione, senza parentesi, e con = Depends. Con le parentesi il server non parte; senza Depends la rotta non è protetta.
D · Una dipendenza dentro l'altra
Il lavoro del controllore si può dividere: una funzione legge l'header, un'altra decide chi è. È la forma del controllore dei biglietti, che scrivi nel capitolo 6. Mettiamo tre scritte, una per anello.
from fastapi import Depends, FastAPI, Header, HTTPException
app = FastAPI(title="La lavanderia del deposito")
CHIAVI = {
"5d1e8b3a7c2f4096": "robot di lavaggio",
"c07a92e41b5d38f6": "contabilità",
}
DETERSIVI = {"schiuma": 8, "sgrassante": 3}
def leggi_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str | None:
print(" 1. leggi_chiave: legge l'header")
return chiave
def programma_corrente(chiave: str | None = Depends(leggi_chiave)) -> str:
print(" 2. programma_corrente: decide chi è")
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
programma = CHIAVI.get(chiave)
if programma is None:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return programma
@app.get("/detersivi")
def leggi_detersivi(programma: str = Depends(programma_corrente)) -> dict:
print(" 3. la rotta parte")
return {"programma": programma, "detersivi": DETERSIVI}Tre richieste: senza chiave, con la chiave sbagliata, con quella giusta.
curl -s http://127.0.0.1:8000/detersivi
curl -s http://127.0.0.1:8000/detersivi -H "X-API-Key: abc123"
curl -s http://127.0.0.1:8000/detersivi -H "X-API-Key: 5d1e8b3a7c2f4096"Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"detail":"Manca la chiave"}
{"detail":"Chiave sbagliata"}
{"programma":"robot di lavaggio","detersivi":{"schiuma":8,"sgrassante":3}}E nel terminale del server:
1. leggi_chiave: legge l'header
2. programma_corrente: decide chi è
INFO: 127.0.0.1:63284 - "GET /detersivi HTTP/1.1" 401 Unauthorized
1. leggi_chiave: legge l'header
2. programma_corrente: decide chi è
INFO: 127.0.0.1:63285 - "GET /detersivi HTTP/1.1" 401 Unauthorized
1. leggi_chiave: legge l'header
2. programma_corrente: decide chi è
3. la rotta parte
INFO: 127.0.0.1:63286 - "GET /detersivi HTTP/1.1" 200 OKL'ordine è sempre 1, 2, 3: prima parte l'anello più in basso della catena, quello da cui dipendono gli altri. Nelle prime due richieste la catena si ferma al 2 (il raise): la scritta 3 non esce.
In italiano. La rotta dipende da programma_corrente, che dipende da leggi_chiave. FastAPI parte dal fondo: chiama leggi_chiave (legge l'header, nessuna decisione), mette il suo return nel parametro chiave di programma_corrente, chiama questa, e se va bene ne mette il return nel parametro della rotta.
Passo per passo.
| Anello | Riceve | Fa | Restituisce |
|---|---|---|---|
leggi_chiave | l'header X-API-Key | niente, lo passa | la chiave, o None |
programma_corrente | la chiave | la cerca nel dizionario: se manca, raise | il nome del programma |
leggi_detersivi | il nome | lo scrive nella risposta | la risposta |
Cosa portiamo a casa. Una dipendenza può avere un parametro che è un altro Depends. FastAPI risolve la catena da solo, dal basso. In utente_corrente l'anello in basso sarà controllore, che legge Authorization: Bearer ….
E · Quando il valore non serve
La lavanderia ha una sirena, per le emergenze. Chi la suona non è interessante: basta che abbia la chiave. E ha una famiglia di rotte, i detersivi, che devono essere tutte chiuse. GET /stato resta aperta a tutti.
from fastapi import APIRouter, Depends, FastAPI, Header, HTTPException
app = FastAPI(title="La lavanderia del deposito")
CHIAVE_LAVANDERIA = "5d1e8b3a7c2f4096" # di prova: quella vera sta nel .env
DETERSIVI = {"schiuma": 8, "sgrassante": 3}
def controlla_chiave(chiave: str | None = Header(default=None, alias="X-API-Key")) -> str:
if chiave is None:
raise HTTPException(status_code=401, detail="Manca la chiave")
if chiave != CHIAVE_LAVANDERIA:
raise HTTPException(status_code=401, detail="Chiave sbagliata")
return "robot di lavaggio"
@app.get("/stato")
def leggi_stato() -> dict:
return {"stato": "la lavanderia funziona"}
@app.post("/sirena", dependencies=[Depends(controlla_chiave)])
def suona_la_sirena() -> dict:
return {"sirena": "suonata"}
router = APIRouter(prefix="/detersivi", dependencies=[Depends(controlla_chiave)])
@router.get("")
def leggi_detersivi() -> dict:
return DETERSIVI
@router.get("/{nome}")
def leggi_detersivo(nome: str) -> dict:
if nome not in DETERSIVI:
raise HTTPException(status_code=404, detail="Detersivo non trovato")
return {nome: DETERSIVI[nome]}
app.include_router(router)Sette richieste. H sta per -H "X-API-Key: 5d1e8b3a7c2f4096", la chiave giusta.
curl -s http://127.0.0.1:8000/stato
curl -s -X POST http://127.0.0.1:8000/sirena
curl -s -X POST http://127.0.0.1:8000/sirena H
curl -s http://127.0.0.1:8000/detersivi
curl -s http://127.0.0.1:8000/detersivi/acido
curl -s http://127.0.0.1:8000/detersivi/acido H
curl -s http://127.0.0.1:8000/detersivi/schiuma HPrevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"stato":"la lavanderia funziona"}
{"detail":"Manca la chiave"}
{"sirena":"suonata"}
{"detail":"Manca la chiave"}
{"detail":"Manca la chiave"}
{"detail":"Detersivo non trovato"}
{"schiuma":8}Guarda la quinta e la sesta: /detersivi/acido non esiste. Senza chiave la risposta è 401, non 404: il controllore parte prima della rotta, e a chi non ha la chiave non si dice nemmeno cosa c'è e cosa no. Con la chiave, il 404 arriva.
In italiano. /stato non ha nessuna dipendenza: è aperta. /sirena ha il controllore nel decoratore. Il router ha il controllore nella sua riga, e lo passa a tutte le sue rotte, comprese leggi_detersivi e leggi_detersivo, che nel def non hanno nessun parametro per la chiave.
Passo per passo.
| Richiesta | Chi la protegge | Risposta |
|---|---|---|
GET /stato | nessuno | 200 |
POST /sirena, senza chiave | dependencies del decoratore | 401 |
POST /sirena, con la chiave | dependencies del decoratore | 200 |
GET /detersivi/acido, senza chiave | dependencies del router | 401 |
GET /detersivi/acido, con la chiave | il router lascia passare, la rotta cerca | 404 |
GET /detersivi/schiuma, con la chiave | il router lascia passare | 200 |
Cosa portiamo a casa. dependencies=[Depends(…)] esegue il controllo senza consegnare il valore. Sul router protegge tutte le sue rotte con una riga, e quelle fuori restano com'erano.