Pydantic, esercizi spiegati
Cinque esempi, un campo alla volta
- 25 minuti di lettura
Cinque esempi, dal più semplice. Ognuno ha lo stesso ritmo:
- Prevedi: leggi il codice e scrivi su un foglio cosa succede. Prima di aprire la risposta.
- In italiano: cosa fa il programma, a parole.
- Passo per passo: cosa arriva, cosa fa lo stampo, cosa esce.
- 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.
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:
addettanon è 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.
| Riga | Arriva | Cosa fa lo stampo | Esce |
|---|---|---|---|
| 1 | vagoni="6" | legge il testo come numero | vagoni=6 |
| 2 | addetta="Elena Marchi" | non è un campo: lo butta via | come la riga 1 |
| 3 | vagoni=3 | niente: è già un numero | pulizia.vagoni * 2 fa 6 |
| 4 | vagoni="tre" | non riesce a leggerlo come numero | ValidationError |
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.
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 nota | Sostituzione(treno="T09") | …, nota=None) | …, nota="porte bloccate") |
|---|---|---|---|
nota: str | errore: Field required | errore: Input should be a valid string | nota='porte bloccate' |
nota: str | None | errore: Field required | nota=None | nota='porte bloccate' |
nota: str = None | nota=None | errore: Input should be a valid string | nota='porte bloccate' |
nota: str | None = None | nota=None | nota=None | nota='porte bloccate' |
Solo l'ultima riga va bene in tutti e tre i casi.
In italiano. Due domande diverse, due pezzi diversi della riga.
- Cosa può arrivare? Lo dice il tipo.
str | None: un testo oppureNone(in JSON,null). - E se non arriva niente? Lo dice il
=.= None: valeNone. 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.
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_equalTre 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.
Passo per passo.
| Campo | Arrivato | La regola | L'errore (type) | In italiano |
|---|---|---|---|---|
treno | "M1" | Field(min_length=3, max_length=3) | string_too_short | il codice ha almeno 3 caratteri |
guasto | "Porte" | Literal["porte", "freni", "luci", "clima"] | literal_error | la maiuscola: "Porte" non è "porte" |
gravita | 0 | Field(ge=1, le=5) | greater_than_equal | almeno 1 |
nota | niente | str | 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.
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 datiSalvalo come officina.py nella cartella dello zip. Nel primo terminale (il server, venv acceso):
fastapi dev officina.pyNel secondo terminale (venv acceso), una segnalazione giusta, con la gravità scritta come testo e un campo in più:
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:
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:
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:
loc | type | msg in italiano | input | |
|---|---|---|---|---|
| 1 | ["body", "treno"] | missing | il campo manca | tutto il corpo: il treno non c'è, quindi Pydantic mostra cosa c'era |
| 2 | ["body", "gravita"] | int_parsing | non 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 EntityTre richieste, ma Arrivata: una volta sola. Con i dati sbagliati la funzione nuova_segnalazione non è mai partita: FastAPI ha risposto 422 prima.
Il disegno.
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.
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 bloccateIl disegno.
In italiano.
datiè un oggettoSegnalazioneNuova: quello che ha mandato il client.dati.model_dump()lo trasforma in un dizionario.**apre il dizionario dentro la chiamata: ogni chiave diventa un argomento con il nome.- Con l'
id=8davanti, la chiamata ha tutti i campi diSegnalazione.
Passo per passo. Un pezzo della riga alla volta, dall'interno verso l'esterno:
| Il pezzo | Che cos'è |
|---|---|
dati | un 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:
segnalazione = Segnalazione(id=8, treno=dati.treno, guasto=dati.guasto, gravita=dati.gravita)
print(segnalazione)treno='T09' guasto='porte' gravita=4 nota=None id=8Nessun 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.