Vai al contenuto
code-to-code

Apro l'indice…

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

HTTP e API6. Pydanticp. 141

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

JSON
{"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:

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

Python
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 bene

Otto 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

Python
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
4

Il disegno.

segnalazione = Segnalazione(treno="M12", gravita=3)segnalazioneSegnalazionetreno"M12"gravita3
L'oggetto creato

Riga per riga:

  1. from pydantic import BaseModel: Pydantic è una libreria, ed è arrivata insieme a fastapi[standard]. Non serve installarla.
  2. 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à.
  3. treno: str è un campo: il nome, i due punti, il tipo. Un campo per riga.
  4. Niente __init__: lo scrive BaseModel per te, leggendo i campi.
  5. 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 + 1 fa 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 è arrivato

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

ArrivaSuccedePerché
gravita="3"diventa 3Pydantic converte, quando può
gravita="tanti"ValidationErrorNon si legge come un numero
gravita=3.5ValidationErrorUn numero intero non ha la virgola
manca trenoValidationErrorUn campo senza valore di partenza è obbligatorio
treno=12ValidationErrorUn numero non diventa testo da solo
colore="rosso"sparisceNon è nello stampo: si butta via, senza errori
Python
print(Segnalazione(treno="M12", gravita="3"))
print(Segnalazione(treno="M12", gravita=3, colore="rosso"))
treno='M12' gravita=3
treno='M12' gravita=3

Il testo "3" è diventato il numero 3, e il colore non c'è più.

Il ValidationError, letto bene

Python
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_parsing

Il traceback si legge dal basso, come sempre (Leggere un traceback). Qui conta il blocco finale, e ha quattro pezzi:

La rigaCosa dice
1 validation error for Segnalazionequanti errori, e in quale stampo
gravitail 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

Python
class Segnalazione(BaseModel):
    treno: str
    gravita: int
    nota: str | None = None

La riga della nota si legge in due pezzi:

  • str | None: un testo oppure None. La barra verticale vuol dire «oppure», come nei type hints di Le funzioni.
  • = None: il valore di partenza. Se la nota non arriva, vale None.

Servono tutti e due. Ecco cosa succede con le quattro versioni possibili, ognuna provata davvero:

ScriviLa nota non arrivaArriva null (in Python, None)
nota: strerrore: Field requirederrore: Input should be a valid string
nota: str | Noneerrore: Field requiredva bene
nota: str = Noneva beneerrore: Input should be a valid string
nota: str | None = Noneva bene, vale Noneva 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.

Python
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 FieldVuol direPer esempioPassaNon passa
ge=1maggiore o uguale (greater or equal)gravita: int = Field(ge=1)10
le=5minore o uguale (less or equal)gravita: int = Field(le=5)56
gt=0maggiore, lo zero escluso (greater than)prezzo: float = Field(gt=0)0.50
lt=100minore, il 100 escluso (less than)prezzo: float = Field(lt=100)99.9100
min_length=3un testo di almeno 3 caratteritreno: str = Field(min_length=3)"M12""M1"
max_length=3un testo di al massimo 3 caratteritreno: 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.

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

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="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_equal

Due errori, tutti e due nel messaggio. Adesso lo stesso stampo in un'API. In FastAPI si mette nella riga del def di una rotta:

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

Uno 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):

Terminale
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 ValidationErrorNel 422Cosa dice
2 validation errorsdue elementi in detailquanti 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:

Python
dati = SegnalazioneNuova(treno="M12", guasto="porte", gravita=3)
print(dati.model_dump())
{'treno': 'M12', 'guasto': 'porte', 'gravita': 3, 'nota': None}

Il disegno.

dati = SegnalazioneNuova(treno="M12", guasto="porte", gravita=3) _risultato = {"treno": "M12", "guasto": "porte", "gravita": 3, "nota": None}datiSegnalazioneNuovatreno"M12"guasto"porte"gravita3
Prima e dopo dati.model_dump()

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.

Python
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 2

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

Python
class Segnalazione(SegnalazioneNuova):
    id: int


segnalazione = Segnalazione(id=7, **dati.model_dump())
print(segnalazione)
treno='M12' guasto='porte' gravita=3 nota=None id=7

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

Python
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

Python
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: int

Il 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».

StampoChi lo mandaHa l'id?Dove lo trovi
SegnalazioneNuovail clientnonel def della rotta: dati: SegnalazioneNuova
Segnalazioneil serversì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.

Python
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" diventa 3), butta via i campi in più, e per tutto il resto si ferma con un ValidationError.
  • 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: loc dice dove, type e msg dicono 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.