Il debugger su FastAPI e nei test
Fermare un server acceso, e fermare un test
- 12 minuti di lettura
Nel capitolo Il debugger hai fermato un programma che parte, gira e finisce. Un'API è un'altra bestia: un server, che resta acceso e aspetta le richieste. Non c'è un «file da lanciare con F5» che comincia in alto e arriva in fondo.
Il debugger sa fermare anche lui. Ma bisogna dirgli come si accende il server, e poi cambia il modo di lavorare: il breakpoint scatta dentro una richiesta, e mentre il server è fermo, chi ha fatto la richiesta aspetta.
Qui servono FastAPI e /docs: se non ti tornano, ripassa Il primo server e La forma della chiamata.
Cosa fa davvero fastapi dev
Finora il server lo hai acceso così, dal terminale:
fastapi dev servizi/stazioni/main.py ⚡️ Starting FastAPI in development mode
🐍 Using import string: main:app
🌐 Server started at http://127.0.0.1:8000
Documentation at http://127.0.0.1:8000/docs
Logs:
INFO: Will watch for changes in these directories: ['/home/lucia/linea-menta']
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process [87942] using WatchFiles
INFO: Started server process [87945]
INFO: Waiting for application startup.
INFO: Application startup complete.Leggi tre righe. Using import string: main:app vuol dire «il file main.py, dentro la variabile app». Uvicorn running vuol dire che chi fa il lavoro è uvicorn: fastapi dev è solo un comodo accendino. E Started reloader process vuol dire che uvicorn tiene d'occhio i file e riavvia il server ogni volta che salvi (si chiama reload).
Per il debugger ci serve il comando che sta sotto. Lo stesso server si accende anche così:
python -m uvicorn main:app --app-dir servizi/stazioniQuesto è il comando che dovrà scrivere VS Code al posto tuo.
La configurazione per il debugger
Con il debugger il server non lo accendi tu dal terminale: lo accende VS Code, e deve sapere cosa lanciare. Lo dici in .vscode/launch.json, che già conosci: aggiungi una configurazione nuova, accanto a «Il file aperto».
{
"version": "0.2.0",
"configurations": [
{
"name": "Il file aperto",
"type": "debugpy",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal"
},
{
"name": "Le stazioni",
"type": "debugpy",
"request": "launch",
"module": "uvicorn",
"args": ["main:app", "--app-dir", "servizi/stazioni"],
"jinja": true
}
]
}| Riga | Vuol dire |
|---|---|
"name": "Le stazioni" | Il nome che vedi nel menu di Run and Debug. Lo scegli tu |
"module": "uvicorn" | Come python -m uvicorn: «lancia il modulo uvicorn» invece di un file. Al posto di "program" |
"args": [...] | La riga di comando a pezzi: un pezzo per ogni parola. Quello che nel terminale scriveresti dopo uvicorn |
"main:app" | Dove sta l'app: il file main.py, la variabile app |
"--app-dir", "servizi/stazioni" | In quale cartella cercare main.py. Due pezzi, uno per la parola e uno per il suo valore. Ci torniamo subito |
"jinja": true | Lo scrive VS Code da solo nel suo modello FastAPI. Serve per le pagine HTML: a noi non serve, e puoi lasciarlo |
Perché --app-dir
VS Code è aperto sulla cartella dello zip (linea-menta), e da lì parte il comando. Ma main.py non sta lì: sta più in basso.
linea-menta/ ← VS Code è aperto qui, e uvicorn parte da qui
├── .vscode/
│ └── launch.json
└── servizi/
└── stazioni/
└── main.py ← qui c'è l'appDalla cartella linea-menta, uvicorn cerca un main.py e non lo trova:
python -m uvicorn main:appERROR: Error loading ASGI app. Could not import module "main".--app-dir servizi/stazioni gli dice dove guardare. Con il percorso scritto a partire dalla cartella aperta in VS Code, con le barre / (anche su Windows). Vanno bene tutti e tre i modi: servizi/stazioni, ./servizi/stazioni, ${workspaceFolder}/servizi/stazioni.
Niente --reload
Quando uvicorn parte con --reload lo hai visto sopra: ci sono due processi. Uno guarda i file (reloader process), l'altro è il server vero (server process), e ogni volta che salvi un file il secondo viene buttato e rifatto. Il debugger si attacca a quello che ha lanciato lui, e i breakpoint rischiano di scattare male, o mai.
Con il debugger quindi niente --reload: un processo solo. Il prezzo lo paghi tu: dopo ogni modifica il server va riavviato a mano (tra poco).
Il triangolo verde, e il browser che aspetta
Si lavora così.
- In
main.pymetti un breakpoint: il pallino rosso, accanto al numero di una riga dentro la rotta. - Run and Debug → scegli Le stazioni → il triangolo verde. Nel TERMINAL compaiono le stesse righe che già conosci:
Uvicorn running on http://127.0.0.1:8000. - Nel browser:
http://127.0.0.1:8000/docs. Prendi la rotta, Try it out, scrivi il parametro, Execute.
E qui succede la cosa che sorprende. Il browser fa girare la rotellina e non risponde. Il server ha cominciato a eseguire la rotta, è arrivato al pallino, e si è fermato.
BROWSER /docs VS CODE
GET /stazioni/{nome}/affollamento 21 presenti = stazione["presenti"]
nome: Largo Lista 22 capienza = stazione["capienza"]
●▶ 23 piena = percentuale(presenti, capienza) ← la riga gialla
[ Execute ] ◌ ... in attesa... 24 return {"stazione": nome, ...}
VARIABLES
nome = 'Largo Lista'
presenti = 90
capienza = 120/docs che gira all'infinito vuol dire una cosa sola: sei fermo su un breakpoint. Non è rotto. Guarda VS Code, guarda VARIABLES, e poi usa i pulsanti di sempre: ↷ Step Over · F10 (su Mac fn+F10), ↓ Step Into · F11, ▶ Continue · F5. Appena il server finisce la rotta, il browser riceve la risposta.
La riga gialla, come sempre, non è ancora stata eseguita: qui piena non esiste ancora.
Un breakpoint scatta solo se la richiesta passa da quella riga. Se chiedi Piazza Luna, che non c'è, la rotta si ferma alla riga 20 con il 404, e un pallino sulla riga 23 non scatta mai: /docs risponde subito. Se non scatta, la prima domanda è: la mia richiesta passa davvero di lì?
Il CALL STACK: chi ha chiamato la tua rotta
Il pannello CALL STACK dice come sei arrivato fin lì: in cima la riga dove sei fermo, sotto chi ti ha chiamato, e così via, fino alla partenza. In una richiesta a FastAPI, con il breakpoint dentro la funzione percentuale chiamata dalla rotta, sono questi:
CALL STACK
percentuale main.py 13
affollamento main.py 23
_run_sync_endpoint fastapi/telemetry/_api.py 244
run anyio/_backends/_asyncio.py 1124
_bootstrap_inner threading.py 1075
_bootstrap threading.py 1032In cima ci sono i tuoi blocchi (main.py). Sotto, FastAPI e Python: non sono tuoi, non ci metti le mani, e i nomi cambiano con la versione. È lo stesso ragionamento del traceback, letto al contrario: lì cercavi il tuo blocco più in basso, qui il tuo blocco sta in cima. Un clic su una riga del CALL STACK ti porta a quel punto del codice, e VARIABLES mostra le variabili di quel blocco.
Dopo ogni modifica: ↻ Restart
Senza --reload il server non si accorge che hai cambiato main.py. Salvi, ricarichi /docs, e risponde come prima: è ancora il codice vecchio, in memoria. Dopo ogni modifica, il pulsante ↻ Restart · Cmd+Shift+F5 (Windows: Ctrl+Shift+F5) nella barra del debugger: spegne il server e lo riaccende con il codice nuovo. I breakpoint restano dove li hai messi.
Address already in use
Una porta può averla un server solo. Se ne hai già uno acceso, per esempio un fastapi dev dimenticato in un terminale, o la sessione di debug di prima non spenta, il secondo non parte:
INFO: Started server process [88039]
INFO: Waiting for application startup.
INFO: Application startup complete.
ERROR: [Errno 48] error while attempting to bind on address ('127.0.0.1', 8000): address already in use
INFO: Waiting for application shutdown.
INFO: Application shutdown complete.L'ultima parola è quella che conta: address already in use, indirizzo già occupato. Spegni l'altro (Ctrl+C nel terminale dove gira, oppure ■ Stop · Shift+F5 nel debugger) e riprova. Il numero tra parentesi cambia: Errno 48 su Mac, Errno 98 su Ubuntu.
Il debugger dentro un test: Debug Test
C'è un secondo modo per fermare un'API, e non accende nessun server. I test di FastAPI usano il TestClient: un finto client che chiama l'app direttamente, dentro lo stesso programma, senza rete e senza /docs. Lo hai visto in Scrivere un test.
Il pannello Testing di VS Code (la provetta, nella barra a sinistra) elenca i test. Su ognuno, tasto destro:
| Voce | Cosa fa |
|---|---|
| Run Test | Lo lancia, come pytest. Verde o rosso, e basta |
| Debug Test | Lo lancia con il debugger: si ferma sui breakpoint, anche dentro il codice che il test chiama, come main.py |
Si usa così: il breakpoint in main.py (non nel test!), poi tasto destro sul test rosso → Debug Test. Il test parte, chiama la rotta, la rotta arriva al pallino, e ti ritrovi fermo con la riga gialla e VARIABLES come sempre.
Quando conviene? Quando hai un test rosso senza traceback: il programma non si è rotto, il valore è sbagliato (assert 0 == 75). Non c'è nessuna riga di errore da leggere, quindi si va a guardare dentro. Il metodo per trovare il bug è il capitolo I bug silenziosi; qui impari lo strumento.
| Server acceso dal debugger | Debug Test | |
|---|---|---|
| Chi fa la richiesta | Tu, da /docs | Il test, con il TestClient |
Serve launch.json | Sì, con --app-dir | No |
| Il browser | Aspetta, finché non premi Continue | Non c'è |
| Dopo una modifica | ↻ Restart | Rilanci il test: riparte da zero ogni volta |
| Quando | Vuoi vedere cosa succede con una richiesta tua | Hai un test rosso, e il valore è sbagliato |
Se il pannello Testing è vuoto, o il test non si ferma, passa dal Pronto soccorso.
Ricorda
fastapi devaccende uvicorn con il reload. Con il debugger lo accende VS Code, con una configurazione inlaunch.json:"module": "uvicorn"e gliargsa pezzi."--app-dir", "cartella"dice dove stamain.py. Senza, uvicorn non lo trova.- Niente
--reloadcon il debugger. Dopo ogni modifica: ↻ Restart. /docsche gira all'infinito vuol dire che sei fermo su un breakpoint.- Il breakpoint scatta solo se la richiesta passa da quella riga. Il valore giusto lo leggi in VARIABLES, non nella risposta di
/docs. - Nel CALL STACK, in cima c'è il tuo codice; sotto, FastAPI.
Address already in use: c'è già un server su quella porta. Spegnilo.- Debug Test: tasto destro sul test, nel pannello Testing. Il breakpoint va dove vuoi guardare, di solito in
main.py.