Vai al contenuto
code-to-code

Apro l'indice…

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

Errori e debugger6. Il debugger su FastAPI e nei testp. 134

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:

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ì:

Terminale
python -m uvicorn main:app --app-dir servizi/stazioni

Questo è 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».

JSON
{
    "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
        }
    ]
}
RigaVuol 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": trueLo 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'app

Dalla cartella linea-menta, uvicorn cerca un main.py e non lo trova:

Terminale
python -m uvicorn main:app
ERROR:    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ì.

  1. In main.py metti un breakpoint: il pallino rosso, accanto al numero di una riga dentro la rotta.
  2. 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.
  3. 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       1032

In 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:

VoceCosa fa
Run TestLo lancia, come pytest. Verde o rosso, e basta
Debug TestLo 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 debuggerDebug Test
Chi fa la richiestaTu, da /docsIl test, con il TestClient
Serve launch.jsonSì, con --app-dirNo
Il browserAspetta, finché non premi ContinueNon c'è
Dopo una modifica↻ RestartRilanci il test: riparte da zero ogni volta
QuandoVuoi vedere cosa succede con una richiesta tuaHai un test rosso, e il valore è sbagliato

Se il pannello Testing è vuoto, o il test non si ferma, passa dal Pronto soccorso.

Ricorda

  • fastapi dev accende uvicorn con il reload. Con il debugger lo accende VS Code, con una configurazione in launch.json: "module": "uvicorn" e gli args a pezzi.
  • "--app-dir", "cartella" dice dove sta main.py. Senza, uvicorn non lo trova.
  • Niente --reload con il debugger. Dopo ogni modifica: ↻ Restart.
  • /docs che 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.