Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API6. Pydanticp. 149

Pydantic, esercizi spiegati

Cinque esempi, un campo alla volta

  • 25 minuti di lettura

Cinque esempi, dal più semplice. Ognuno ha lo stesso ritmo:

  1. Prevedi: leggi il codice e scrivi su un foglio cosa succede. Prima di aprire la risposta.
  2. In italiano: cosa fa il programma, a parole.
  3. Passo per passo: cosa arriva, cosa fa lo stampo, cosa esce.
  4. Cosa portiamo a casa: la cosa da ricordare.

Per provarli: scompatta lo zip della palestra, accendi il venv, e incolla l'esempio in un file prova.py nella cartella dello zip. Poi python3 prova.py. Pydantic c'è già: è arrivato con FastAPI.


A · Le pulizie dei vagoni

Elena Marchi, l'addetta alle pulizie, segna dall'app i treni che ha pulito. L'app manda tutto come capita: a volte un numero, a volte un testo.

Python
from pydantic import BaseModel


class Pulizia(BaseModel):
    treno: str
    vagoni: int
    finita: bool


print(Pulizia(treno="M16", vagoni="6", finita=True))
print(Pulizia(treno="M16", vagoni=6, finita=True, addetta="Elena Marchi"))
pulizia = Pulizia(treno="M14", vagoni=3, finita=False)
print(pulizia.vagoni * 2)
print(Pulizia(treno="M14", vagoni="tre", finita=False))
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
treno='M16' vagoni=6 finita=True
treno='M16' vagoni=6 finita=True
6
Traceback (most recent call last):
…
pydantic_core._pydantic_core.ValidationError: 1 validation error for Pulizia
vagoni
  Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='tre', input_type=str]
    For further information visit https://errors.pydantic.dev/2.14/v/int_parsing
  • Riga 1: "6" è un testo, ma si legge come un numero. Pydantic lo converte: vagoni=6, senza virgolette.
  • Riga 2: addetta non è un campo dello stampo. Nessun errore: sparisce.
  • Riga 3: pulizia.vagoni è un numero vero, e per 2 fa 6.
  • Riga 4: "tre" scritto a lettere non si legge come un numero. Il programma si ferma, e il messaggio dice il campo (vagoni) e cosa è arrivato ('tre').

In italiano. Lo stampo guarda ogni campo e si chiede: quello che è arrivato si può leggere con il tipo che mi hanno dato? Se sì, lo converte. Se no, si ferma e dice perché.

Passo per passo.

RigaArrivaCosa fa lo stampoEsce
1vagoni="6"legge il testo come numerovagoni=6
2addetta="Elena Marchi"non è un campo: lo butta viacome la riga 1
3vagoni=3niente: è già un numeropulizia.vagoni * 2 fa 6
4vagoni="tre"non riesce a leggerlo come numeroValidationError

Cosa portiamo a casa. Pydantic non indovina: converte solo quello che si legge senza dubbi. Tutto il resto è un errore, con il nome del campo.


B · La nota che a volte non c'è

Lucia Ferri, capotreno, chiede di sostituire un treno guasto. Il codice del treno c'è sempre; la nota a volte la scrive, a volte no, a volte l'app manda null.

Python
from pydantic import BaseModel


class Sostituzione(BaseModel):
    treno: str
    nota: str | None          # la riga da cambiare


print(Sostituzione(treno="T09"))
print(Sostituzione(treno="T09", nota=None))
print(Sostituzione(treno="T09", nota="porte bloccate"))

Prova la riga della nota in quattro modi: nota: str, nota: str | None, nota: str = None, nota: str | None = None. Per ognuno, quali delle tre chiamate passano? Una alla volta: il primo errore ferma il programma.

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
La riga della notaSostituzione(treno="T09")…, nota=None)…, nota="porte bloccate")
nota: strerrore: Field requirederrore: Input should be a valid stringnota='porte bloccate'
nota: str | Noneerrore: Field requirednota=Nonenota='porte bloccate'
nota: str = Nonenota=Noneerrore: Input should be a valid stringnota='porte bloccate'
nota: str | None = Nonenota=Nonenota=Nonenota='porte bloccate'

Solo l'ultima riga va bene in tutti e tre i casi.

In italiano. Due domande diverse, due pezzi diversi della riga.

  1. Cosa può arrivare? Lo dice il tipo. str | None: un testo oppure None (in JSON, null).
  2. E se non arriva niente? Lo dice il =. = None: vale None. Senza =, il campo è obbligatorio.

Passo per passo, la seconda riga, nota: str | None senza =. Sembra facoltativa, perché c'è None. Ma None sta nel tipo: dice che null è ammesso, non che la nota si può non mandare. Il valore di partenza non c'è, quindi il campo è obbligatorio: Field required.

E la terza, nota: str = None: se la nota non arriva, Pydantic mette il valore di partenza, None, senza controllarlo. Ma se arriva null, lo controlla con il tipo, str, e None non è un testo.

Cosa portiamo a casa. Un campo facoltativo ha sempre tutti e due i pezzi: str | None = None.


C · Tre errori in una volta

Ivo Brambati ha lo stampo completo delle segnalazioni. Dal tablet di un macchinista arriva una segnalazione scritta di fretta.

Python
from typing import Literal

from pydantic import BaseModel, Field


class SegnalazioneNuova(BaseModel):
    treno: str = Field(min_length=3, max_length=3)
    guasto: Literal["porte", "freni", "luci", "clima"]
    gravita: int = Field(ge=1, le=5)
    nota: str | None = None


SegnalazioneNuova(treno="M1", guasto="Porte", gravita=0)

Quanti errori? Su quali campi?

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
Traceback (most recent call last):
…
pydantic_core._pydantic_core.ValidationError: 3 validation errors for SegnalazioneNuova
treno
  String should have at least 3 characters [type=string_too_short, input_value='M1', input_type=str]
    For further information visit https://errors.pydantic.dev/2.14/v/string_too_short
guasto
  Input should be 'porte', 'freni', 'luci' or 'clima' [type=literal_error, input_value='Porte', input_type=str]
    For further information visit https://errors.pydantic.dev/2.14/v/literal_error
gravita
  Input should be greater than or equal to 1 [type=greater_than_equal, input_value=0, input_type=int]
    For further information visit https://errors.pydantic.dev/2.14/v/greater_than_equal

Tre errori, uno per campo. La nota no: non è arrivata, e vale None.

In italiano. Pydantic non si ferma al primo campo sbagliato: li controlla tutti e ti dà l'elenco completo. Leggilo come una lista della spesa, un blocco alla volta.

Il disegno.

inizio SegnalazioneNuova(...) per ogni campo dello stampo se il campo non va bene sì: passo aggiungi l'errore all'elenco se l'elenco ha degli errori sì: errore ValidationError con tutti gli errori restituisci l'oggettoSegnalazioneNuova(...)per ogni campo dello stampoil campo non va beneaggiungi l'errore all'elencol'elenco ha deglierroriValidationError con tuttigli errorirestituisci l'oggettonosìfinitinosì
Lo stampo controlla tutti i campi

Passo per passo.

CampoArrivatoLa regolaL'errore (type)In italiano
treno"M1"Field(min_length=3, max_length=3)string_too_shortil codice ha almeno 3 caratteri
guasto"Porte"Literal["porte", "freni", "luci", "clima"]literal_errorla maiuscola: "Porte" non è "porte"
gravita0Field(ge=1, le=5)greater_than_equalalmeno 1
notanientestr | None = None—vale None

I type hanno nomi che si leggono: string too short è «testo troppo corto», greater than equal è «maggiore o uguale». Li ritrovi tutti nella pagina Se qualcosa va storto.

Cosa portiamo a casa. Conta i blocchi, poi correggi dall'alto, un campo alla volta. Il numero in prima riga (3 validation errors) ti dice quando hai finito.


D · Il 422 dal vivo

Ivo mette lo stampo in un'API: l'officina riceve le segnalazioni con una POST. La rotta stampa nel terminale del server quello che le arriva, e lo restituisce.

Python
from typing import Literal

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI(title="L'officina del deposito")


class SegnalazioneNuova(BaseModel):
    treno: str = Field(min_length=3, max_length=3)
    guasto: Literal["porte", "freni", "luci", "clima"]
    gravita: int = Field(ge=1, le=5)
    nota: str | None = None


@app.post("/segnalazioni")
def nuova_segnalazione(dati: SegnalazioneNuova) -> SegnalazioneNuova:
    print("Arrivata:", dati)
    return dati

Salvalo come officina.py nella cartella dello zip. Nel primo terminale (il server, venv acceso):

Terminale
fastapi dev officina.py

Nel secondo terminale (venv acceso), una segnalazione giusta, con la gravità scritta come testo e un campo in più:

Terminale
curl -s -X POST http://127.0.0.1:8000/segnalazioni \
  -H "Content-Type: application/json" \
  -d '{"treno": "M12", "guasto": "porte", "gravita": "3", "colore": "rosso"}'

Cosa risponde il server? Che fine fanno "3" e "colore"?

Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{"treno":"M12","guasto":"porte","gravita":3,"nota":null}

La risposta è lo stampo, non quello che hai mandato: la gravità è il numero 3, il colore non c'è, e la nota che non hai mandato c'è, con null (il None di Python, in JSON).

Adesso una segnalazione sbagliata, con -i per vedere anche il codice:

Terminale
curl -i -X POST http://127.0.0.1:8000/segnalazioni \
  -H "Content-Type: application/json" \
  -d '{"treno": "M12", "guasto": "ruote", "gravita": 9}'
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
HTTP/1.1 422 Unprocessable Entity
date: Thu, 19 Nov 2026 16:09:17 GMT
server: uvicorn
content-length: 319
content-type: application/json

{"detail":[{"type":"literal_error","loc":["body","guasto"],"msg":"Input should be 'porte', 'freni', 'luci' or 'clima'","input":"ruote","ctx":{"expected":"'porte', 'freni', 'luci' or 'clima'"}},{"type":"less_than_equal","loc":["body","gravita"],"msg":"Input should be less than or equal to 5","input":9,"ctx":{"le":5}}]}

Il 422, e nel corpo i due errori: il guasto (literal_error) e la gravità (less_than_equal). Tutto su una riga: per leggerlo meglio, -s al posto di -i e | python3 -m json.tool in fondo, come nella teoria.

Un'altra, senza treno e con la gravità a parole. Questa volta già in colonna:

Terminale
curl -s -X POST http://127.0.0.1:8000/segnalazioni \
  -H "Content-Type: application/json" \
  -d '{"guasto": "luci", "gravita": "tanti"}' | python3 -m json.tool
{
    "detail": [
        {
            "type": "missing",
            "loc": [
                "body",
                "treno"
            ],
            "msg": "Field required",
            "input": {
                "guasto": "luci",
                "gravita": "tanti"
            }
        },
        {
            "type": "int_parsing",
            "loc": [
                "body",
                "gravita"
            ],
            "msg": "Input should be a valid integer, unable to parse string as an integer",
            "input": "tanti"
        }
    ]
}

Passo per passo, un elemento di detail alla volta:

loctypemsg in italianoinput
1["body", "treno"]missingil campo mancatutto il corpo: il treno non c'è, quindi Pydantic mostra cosa c'era
2["body", "gravita"]int_parsingnon si legge come un numero intero"tanti"

loc si legge da sinistra: "body" è il corpo della richiesta, poi il nome del campo. È l'indirizzo dell'errore.

Adesso guarda il primo terminale. Nel terminale del server compare:

Arrivata: treno='M12' guasto='porte' gravita=3 nota=None
INFO:     127.0.0.1:60482 - "POST /segnalazioni HTTP/1.1" 200 OK
INFO:     127.0.0.1:60483 - "POST /segnalazioni HTTP/1.1" 422 Unprocessable Entity
INFO:     127.0.0.1:60484 - "POST /segnalazioni HTTP/1.1" 422 Unprocessable Entity

Tre richieste, ma Arrivata: una volta sola. Con i dati sbagliati la funzione nuova_segnalazione non è mai partita: FastAPI ha risposto 422 prima.

Il disegno.

inizio POST /segnalazioni se i dati non passano lo stampo sì: errore 422 La funzione non parte mostra print("Arrivata:", dati) restituisci datiPOST /segnalazionii dati non passanolo stampo422 La funzione non partemostra print("Arrivata:",dati)restituisci datinosì
La rotta con lo stampo

Cosa portiamo a casa. Il 422 è il ValidationError arrivato fino al client. loc dice dove, type e msg dicono perché, input dice cosa è arrivato. E il tuo codice, con i dati sbagliati, non parte mai: dentro la funzione i dati sono già in ordine.


E · Le due stelle, passo per passo

Ogni segnalazione dell'officina riceve un numero, l'id, che sceglie il deposito. Ivo ha i due stampi: SegnalazioneNuova, quella dell'esempio C, e Segnalazione, che ha in più l'id. Per provarlo, sopra questo codice incolla gli import e lo stampo dell'esempio C.

Python
class Segnalazione(SegnalazioneNuova):
    id: int


dati = SegnalazioneNuova(treno="T09", guasto="porte", gravita=4, nota="porte bloccate")
print(dati.model_dump())
segnalazione = Segnalazione(id=8, **dati.model_dump())
print(segnalazione)
print(segnalazione.id, segnalazione.nota)
Prevedi Scrivi su un foglio cosa ti aspetti, poi apri.
{'treno': 'T09', 'guasto': 'porte', 'gravita': 4, 'nota': 'porte bloccate'}
treno='T09' guasto='porte' gravita=4 nota='porte bloccate' id=8
8 porte bloccate

Il disegno.

dati = SegnalazioneNuova(treno="T09", guasto="porte", gravita=4, nota="porte bloccate") segnalazione = Segnalazione(id=8, treno="T09", guasto="porte", gravita=4, nota="porte bloccate")datisegnalazioneSegnalazioneNuovatreno"T09"guasto"porte"gravita4nota"porte bloccate"Segnalazioneid8treno"T09"guasto"porte"gravita4nota"porte bloccate"
Alla fine

In italiano.

  1. dati è un oggetto SegnalazioneNuova: quello che ha mandato il client.
  2. dati.model_dump() lo trasforma in un dizionario.
  3. ** apre il dizionario dentro la chiamata: ogni chiave diventa un argomento con il nome.
  4. Con l'id=8 davanti, la chiamata ha tutti i campi di Segnalazione.

Passo per passo. Un pezzo della riga alla volta, dall'interno verso l'esterno:

Il pezzoChe cos'è
datiun oggetto SegnalazioneNuova, con quattro campi
dati.model_dump(){"treno": "T09", "guasto": "porte", "gravita": 4, "nota": "porte bloccate"}
**dati.model_dump()treno="T09", guasto="porte", gravita=4, nota="porte bloccate"
Segnalazione(id=8, **dati.model_dump())Segnalazione(id=8, treno="T09", guasto="porte", gravita=4, nota="porte bloccate")

La versione lunga scrive la quarta riga della tabella a mano, ed è giusta. Ma attento a non dimenticare un campo:

Python
segnalazione = Segnalazione(id=8, treno=dati.treno, guasto=dati.guasto, gravita=dati.gravita)
print(segnalazione)
treno='T09' guasto='porte' gravita=4 nota=None id=8

Nessun errore: la nota è facoltativa, quindi Pydantic mette None. Ma «porte bloccate» si è perso per strada. Con le due stelle non succede: il dizionario ha sempre tutti i campi.

Cosa portiamo a casa. **dati.model_dump() vuol dire «tutti i campi di dati, con il loro nome». Davanti ci metti quello che manca, l'id. Se le stelle ti confondono, la versione lunga va benissimo: basta contare i campi.


Pronto? Gli stessi stampi ti aspettano nella palestra: sei esercizi da scaricare, con i test.