Pydantic
Lo stampo che controlla i dati
- 15 minuti di lettura
Ivo Brambati, il manutentore del deposito, riceve dai capotreno le segnalazioni dei guasti. Arrivano dall'app di bordo, in JSON. Una segnalazione fatta bene è così:
{"treno": "M12", "guasto": "porte", "gravita": 3, "nota": "la porta 2 non si chiude"}Il codice del treno, il tipo di guasto, la gravità da 1 a 5 e, se serve, una nota. Ma dal client può arrivare di tutto:
| Arriva | Cosa non va |
|---|---|
{} | Manca tutto |
{"treno": "M12", "guasto": "porte", "gravita": 9} | La gravità va da 1 a 5 |
{"treno": "M12", "guasto": "porte", "gravita": "tanti"} | «tanti» non è un numero |
{"treno": "M12", "guasto": "ruote", "gravita": 2} | Le ruote non sono tra i guasti previsti |
Senza Pydantic: un if per ogni regola
Ogni controllo, a mano:
def controlla(dati):
if "treno" not in dati:
return "manca il treno"
if "gravita" not in dati:
return "manca la gravità"
if not isinstance(dati["gravita"], int): # è un numero intero?
return "la gravità non è un numero"
if dati["gravita"] < 1 or dati["gravita"] > 5:
return "la gravità va da 1 a 5"
# …e così per il guasto, per la nota, per ogni regola nuova
return "va bene"
print(controlla({}))
print(controlla({"treno": "M12", "guasto": "porte", "gravita": 9}))
print(controlla({"treno": "M12", "guasto": "porte", "gravita": "3"}))
print(controlla({"treno": "M12", "guasto": "ruote", "gravita": 2}))manca il treno
la gravità va da 1 a 5
la gravità non è un numero
va beneOtto righe per due campi, e due buchi. Il testo "3", che dal client arriva spesso, viene rifiutato anche se è un numero scritto come testo. E le ruote passano, perché il guasto nessuno lo controlla: servirebbe un altro if. E poi un altro.
Pydantic fa questi controlli al posto tuo. Tu scrivi i campi e i loro tipi; lui li legge e controlla tutto.
BaseModel: lo stampo che controlla
from pydantic import BaseModel
class Segnalazione(BaseModel):
treno: str
gravita: int
segnalazione = Segnalazione(treno="M12", gravita=3)
print(segnalazione)
print(segnalazione.gravita + 1)treno='M12' gravita=3
4Il disegno.
Riga per riga:
from pydantic import BaseModel: Pydantic è una libreria, ed è arrivata insieme afastapi[standard]. Non serve installarla.class Segnalazione(BaseModel):è uno stampo, come quelli di Classi e oggetti. Tra le parentesi c'èBaseModel: il tuo stampo prende da lì tutto il lavoro di controllo. È l'ereditarietà, e per ora basta questo; la storia intera è in L'ereditarietà.treno: strè un campo: il nome, i due punti, il tipo. Un campo per riga.- Niente
__init__: lo scriveBaseModelper te, leggendo i campi. - L'oggetto si crea con i nomi dei campi,
Segnalazione(treno="M12", gravita=3), e si legge con il punto:segnalazione.gravitaè il numero 3, e+ 1fa 4.
Il disegno
Lo stampo sta in mezzo. A sinistra arriva quello che manda il client, un dizionario. A destra esce un oggetto in ordine, oppure un errore che dice cosa non va.
DAL CLIENT LO STAMPO NE ESCE
(un dizionario) (la classe) (un oggetto)
{"treno": "M12", ┌─ Segnalazione ──┐ ┌─ Segnalazione ──┐
"gravita": "3", ─────▶ │ treno str │ ──sì──▶ │ treno "M12" │
"colore": "rosso"} │ gravita int │ │ gravita 3 │
└────────┬────────┘ └─────────────────┘
│ "3" è diventato 3,
no "colore" è sparito
▼
ValidationError:
quale campo, perché,
che cosa è arrivatoNon c'è una via di mezzo: se anche un solo campo è sbagliato, l'oggetto non nasce.
Cosa succede ai dati
Sei casi da conoscere, con lo stampo Segnalazione di prima:
| Arriva | Succede | Perché |
|---|---|---|
gravita="3" | diventa 3 | Pydantic converte, quando può |
gravita="tanti" | ValidationError | Non si legge come un numero |
gravita=3.5 | ValidationError | Un numero intero non ha la virgola |
manca treno | ValidationError | Un campo senza valore di partenza è obbligatorio |
treno=12 | ValidationError | Un numero non diventa testo da solo |
colore="rosso" | sparisce | Non è nello stampo: si butta via, senza errori |
print(Segnalazione(treno="M12", gravita="3"))
print(Segnalazione(treno="M12", gravita=3, colore="rosso"))treno='M12' gravita=3
treno='M12' gravita=3Il testo "3" è diventato il numero 3, e il colore non c'è più.
Il ValidationError, letto bene
Segnalazione(treno="M12", gravita="tanti")Traceback (most recent call last):
…
pydantic_core._pydantic_core.ValidationError: 1 validation error for Segnalazione
gravita
Input should be a valid integer, unable to parse string as an integer [type=int_parsing, input_value='tanti', input_type=str]
For further information visit https://errors.pydantic.dev/2.14/v/int_parsingIl traceback si legge dal basso, come sempre (Leggere un traceback). Qui conta il blocco finale, e ha quattro pezzi:
| La riga | Cosa dice |
|---|---|
1 validation error for Segnalazione | quanti errori, e in quale stampo |
gravita | il campo che non va |
Input should be a valid integer, … | perché, in inglese: «doveva essere un numero intero» |
[type=int_parsing, input_value='tanti', …] | il nome dell'errore (type) e il valore che è arrivato (input_value) |
L'ultima riga, For further information…, è un link alla documentazione: puoi saltarla. Se gli errori sono tre, i blocchi «campo e perché» sono tre, uno sotto l'altro: Pydantic non si ferma al primo.
Obbligatorio o facoltativo
class Segnalazione(BaseModel):
treno: str
gravita: int
nota: str | None = NoneLa riga della nota si legge in due pezzi:
str | None: un testo oppureNone. La barra verticale vuol dire «oppure», come nei type hints di Le funzioni.= None: il valore di partenza. Se la nota non arriva, valeNone.
Servono tutti e due. Ecco cosa succede con le quattro versioni possibili, ognuna provata davvero:
| Scrivi | La nota non arriva | Arriva null (in Python, None) |
|---|---|---|
nota: str | errore: Field required | errore: Input should be a valid string |
nota: str | None | errore: Field required | va bene |
nota: str = None | va bene | errore: Input should be a valid string |
nota: str | None = None | va bene, vale None | va bene, vale None |
La regola: un campo è facoltativo solo se ha il suo =. Il tipo dice cosa può arrivare; il = dice cosa vale quando non arriva niente.
Field: le regole in più
Il tipo dice che cosa è un campo. Field aggiunge i limiti.
from pydantic import BaseModel, Field
class Segnalazione(BaseModel):
treno: str = Field(min_length=3, max_length=3)
gravita: int = Field(ge=1, le=5)Field si importa insieme a BaseModel, e si scrive dopo il tipo, con l'uguale. Le regole sono sei:
In Field | Vuol dire | Per esempio | Passa | Non passa |
|---|---|---|---|---|
ge=1 | maggiore o uguale (greater or equal) | gravita: int = Field(ge=1) | 1 | 0 |
le=5 | minore o uguale (less or equal) | gravita: int = Field(le=5) | 5 | 6 |
gt=0 | maggiore, lo zero escluso (greater than) | prezzo: float = Field(gt=0) | 0.5 | 0 |
lt=100 | minore, il 100 escluso (less than) | prezzo: float = Field(lt=100) | 99.9 | 100 |
min_length=3 | un testo di almeno 3 caratteri | treno: str = Field(min_length=3) | "M12" | "M1" |
max_length=3 | un testo di al massimo 3 caratteri | treno: str = Field(max_length=3) | "M12" | "M120" |
Si mettono insieme con una virgola: Field(ge=1, le=5) vuol dire «da 1 a 5, tutti e due compresi».
Literal: solo questi valori
Il guasto è un testo, ma non uno qualsiasi: solo uno dei quattro previsti.
from typing import Literal
class Segnalazione(BaseModel):
guasto: Literal["porte", "freni", "luci", "clima"]Literal arriva da typing, un modulo di Python, e vuole le quadre, con i valori tra virgolette e separati da virgole. Le maiuscole contano: "Porte" non è "porte".
Lo stampo completo, e il 422
Tutto insieme:
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="M12", guasto="ruote", gravita=9)Traceback (most recent call last):
…
pydantic_core._pydantic_core.ValidationError: 2 validation errors for SegnalazioneNuova
guasto
Input should be 'porte', 'freni', 'luci' or 'clima' [type=literal_error, input_value='ruote', input_type=str]
For further information visit https://errors.pydantic.dev/2.14/v/literal_error
gravita
Input should be less than or equal to 5 [type=less_than_equal, input_value=9, input_type=int]
For further information visit https://errors.pydantic.dev/2.14/v/less_than_equalDue errori, tutti e due nel messaggio. Adesso lo stesso stampo in un'API. In FastAPI si mette nella riga del def di una rotta:
@app.post("/segnalazioni")
def nuova_segnalazione(dati: SegnalazioneNuova) -> SegnalazioneNuova:
return datiUno stampo nel def vuol dire: il corpo della richiesta deve avere questa forma (come FastAPI capisce che è proprio il corpo, lo racconta La forma della chiamata). FastAPI passa il JSON allo stampo prima di chiamare la tua funzione. Se i dati non vanno bene, la funzione non parte: FastAPI risponde da solo 422 e mette gli stessi errori nel corpo della risposta, in JSON. La stessa richiesta di prima, con curl (l'API intera, da accendere con fastapi dev, è nell'esempio D degli esercizi spiegati):
curl -s -X POST http://127.0.0.1:8000/segnalazioni \
-H "Content-Type: application/json" \
-d '{"treno": "M12", "guasto": "ruote", "gravita": 9}' | python3 -m json.tool{
"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
}
}
]
}detail è una lista, con un elemento per errore. Ogni elemento è il blocco del ValidationError, scritto in JSON:
Nel ValidationError | Nel 422 | Cosa dice |
|---|---|---|
2 validation errors | due elementi in detail | quanti errori |
gravita | "loc": ["body", "gravita"] | dove: nel corpo (body), il campo gravita |
Input should be less than or equal to 5 | "msg" | perché, in inglese |
type=less_than_equal | "type" | il nome dell'errore |
input_value=9 | "input" | il valore arrivato |
| — | "ctx": {"le": 5} | il limite della regola (solo per alcune regole) |
model_dump: dall'oggetto al dizionario
Ogni stampo sa trasformarsi in un dizionario, campo per campo:
dati = SegnalazioneNuova(treno="M12", guasto="porte", gravita=3)
print(dati.model_dump()){'treno': 'M12', 'guasto': 'porte', 'gravita': 3, 'nota': None}Il disegno.
model_dump() è un metodo, con le parentesi. Restituisce un dizionario nuovo. Anche la nota che non è arrivata c'è, con il suo None.
Le due stelle
Prima con una funzione qualsiasi. ** davanti a un dizionario, dentro una chiamata, lo apre: ogni chiave diventa un argomento con il nome.
def annuncio(treno, binario):
return f"Il treno {treno} parte dal binario {binario}"
dati = {"treno": "M12", "binario": 2}
print(annuncio(**dati))
print(annuncio(treno="M12", binario=2))Il treno M12 parte dal binario 2
Il treno M12 parte dal binario 2Le due chiamate sono la stessa chiamata. Adesso con gli stampi. Al deposito ogni segnalazione ha anche un numero, l'id, che il client non manda:
class Segnalazione(SegnalazioneNuova):
id: int
segnalazione = Segnalazione(id=7, **dati.model_dump())
print(segnalazione)treno='M12' guasto='porte' gravita=3 nota=None id=7Python la fa in tre passi, dall'interno verso l'esterno:
dati ──────▶ ┌─ SegnalazioneNuova ─┐
│ treno "M12" │
│ guasto "porte" │
│ gravita 3 │
│ nota None │
└─────────┬───────────┘
│ .model_dump()
▼
{"treno": "M12", "guasto": "porte", "gravita": 3, "nota": None}
│ ** apre il dizionario: ogni chiave diventa nome=valore
▼
Segnalazione(id=7, treno="M12", guasto="porte", gravita=3, nota=None)La versione lunga fa la stessa cosa, e va benissimo:
segnalazione = Segnalazione(id=7, treno=dati.treno, guasto=dati.guasto, gravita=dati.gravita, nota=dati.nota)Le stelle sono una scorciatoia: scrivono per te tutti i nome=valore, e non se ne dimenticano nessuno.
Due stampi: quello che arriva e quello che esce
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
class Segnalazione(SegnalazioneNuova):
id: intIl client non sceglie l'id: lo sceglie il server. Per questo gli stampi sono due. class Segnalazione(SegnalazioneNuova) vuol dire «tutti i campi di SegnalazioneNuova, più l'id».
| Stampo | Chi lo manda | Ha l'id? | Dove lo trovi |
|---|---|---|---|
SegnalazioneNuova | il client | no | nel def della rotta: dati: SegnalazioneNuova |
Segnalazione | il server | sì | dopo la freccia ->, e nel dizionario dei dati |
Il ponte
Nel capitolo CRUD su un dizionario la rotta POST mette insieme tutto quello che c'è in questa pagina: lo stampo nel def, l'id scelto dal server e le due stelle.
segnalazione = Segnalazione(id=prossimo_id(segnalazioni), **dati.model_dump())prossimo_id è una piccola funzione che sceglie il primo numero libero: la incontri lì, e lì vedrai tutta la rotta riga per riga. Se questa riga adesso ti torna, la POST è già mezza fatta.
Ricorda
- Uno stampo
BaseModelè una classe con i campi e i loro tipi:__init__lo scrive lui, e i dati li controlla. - Pydantic converte quando può (
"3"diventa3), butta via i campi in più, e per tutto il resto si ferma con unValidationError. - Facoltativo vuol dire con il suo
=:nota: str | None = None. Field(ge=…, le=…, gt=…, lt=…, min_length=…, max_length=…)mette i limiti;Literal[…]ammette solo quei valori.- In FastAPI lo stesso errore è il 422:
locdice dove,typeemsgdicono cosa. La tua funzione non parte. Segnalazione(id=7, **dati.model_dump()): dall'oggetto al dizionario, dal dizionario agli argomenti con il nome. La versione lunga va benissimo.