Kurs Python · Moduł 6: Async i FastAPI
Pydantic - walidacja danych z Rust
W tej lekcji5
Witaj! Darwin tutaj. Strażnik parku wpisał w formularzu populację "sto dwadzieścia" zamiast 120, a datę w polu gatunku. Bez kontroli taki wpis trafi do bazy i zepsuje statystyki całego rezerwatu. Pydantic to biblioteka do walidacji i serializacji danych oparta na type hints: opisujesz kształt danych adnotacjami typów, a ona sprawdza każdą wartość.
Pydantic to rdzeń FastAPI - framework waliduje nim parametry i ciała żądań oraz kształtuje odpowiedzi. W wersji 2 logikę walidacji przeniesiono do pakietu pydantic-core napisanego w Rust, a według autorów typowy model sprawdza się około 17× szybciej niż w wersji 1.
Analogia Safari: Pydantic to jak system kontroli jakości obserwacji - sprawdza, czy każda obserwacja ma poprawne dane (gatunek istnieje, populacja to liczba, data jest prawidłowa). Jeśli coś jest nie tak, od razu zgłasza błąd!
Podstawy Pydantic
BaseModel - klasa bazowa
Model to klasa dziedzicząca po BaseModel. Każde pole to nazwa z adnotacją typu, a wartość po znaku = staje się domyślną:
from pydantic import BaseModel
class Species(BaseModel):
id: int
name: str
population: int
endangered: bool = False # Domyślna wartość
# Tworzenie instancji
lion = Species(id=1, name="Lew", population=120, endangered=True)
print(lion.name) # Lew
print(lion.model_dump()) # {'id': 1, 'name': 'Lew', 'population': 120, 'endangered': True}
print(lion.model_dump_json()) # {"id":1,"name":"Lew","population":120,"endangered":true}model_dump() zamienia model na słownik, a model_dump_json() na tekst JSON. Starsze tutoriale używają .dict() i .json() - w Pydantic 2 wciąż działają, ale zgłaszają ostrzeżenie i znikną w wersji 3.
Pola opcjonalne
Nie każda obserwacja ma opis. Pole, które może zostać puste, oznaczamy typem Optional[str] i wartością domyślną None:
from typing import Optional
from pydantic import BaseModel
class Sighting(BaseModel):
species: str
count: int
description: Optional[str] = None
print(Sighting(species="Lew", count=3)) # species='Lew' count=3 description=NoneSamo Optional[str] pozwala przekazać None, ale dopiero = None pozwala pole pominąć. Od Pythona 3.10 to samo zapiszesz jako str | None = None.
Automatyczna konwersja typów
Dane z formularzy i adresów URL przychodzą jako tekst. Pydantic próbuje je przekonwertować na zadeklarowany typ:
# Pydantic automatycznie konwertuje typy!
species = Species(id="1", name="Lew", population="120", endangered="yes")
print(type(species.id)) # <class 'int'> (konwersja str→int)
print(type(species.population)) # <class 'int'>
print(species.endangered) # True (konwersja "yes"→True)Konwersja zachodzi tylko bez utraty informacji: "120" staje się liczbą, ale "abc" czy 1.5 do pola int nie przejdą. Pydantic nie wstawia wtedy None, tylko zgłasza błąd.
Walidacja błędów
Gdy konwersja się nie uda, Pydantic zgłasza ValidationError z listą wszystkich problemów. Łapiemy go jak każdy wyjątek:
from pydantic import ValidationError
try:
# Błędne dane
species = Species(id="abc", name="Lew", population=-50)
except ValidationError as e:
print(e.error_count()) # 1
print(e.json()) # Szczegółowe błędy walidacji (JSON)Błąd jest jeden, bo -50 to poprawny int - model nie zna reguły, że populacja nie może być ujemna. Takie reguły dodaje Field.
Field - zaawansowana walidacja
Field dopisuje do pola ograniczenia: zakresy liczb, długość tekstu, wzorzec. Trzy kropki ... oznaczają pole wymagane:
from pydantic import BaseModel, Field
class Species(BaseModel):
id: int = Field(..., gt=0, description="Unique species ID")
name: str = Field(..., min_length=2, max_length=100)
scientific_name: str = Field(..., pattern=r'^[A-Z][a-z]+ [a-z]+$') # Regex
population: int = Field(..., ge=0, le=1_000_000) # >= 0, <= 1M
habitat: str = Field(default="unknown")
# Walidacja działa!
lion = Species(
id=1,
name="Lew",
scientific_name="Panthera leo", # Musi pasować do regex
population=120
)Teraz population=-50 zostałoby odrzucone przez ge=0. Zapis Field(gt=0) bez wartości domyślnej też oznacza pole wymagane - krótszy, więc go polecam.
Field validators:
gt,ge- greater than, greater or equallt,le- less than, less or equalmin_length,max_length- długość stringpattern- regex validationdescription- opis dla dokumentacji
Custom validators
Nietypową regułę zapisujesz jako funkcję z dekoratorem @field_validator. Zwraca ona wartość albo zgłasza ValueError:
from pydantic import BaseModel, ValidationError, field_validator
class Species(BaseModel):
name: str
population: int
@field_validator('name')
@classmethod
def name_must_be_capitalized(cls, v):
if not v[0].isupper():
raise ValueError('Nazwa musi zaczynać się wielką literą')
return v
@field_validator('population')
@classmethod
def population_realistic(cls, v):
if v > 1_000_000:
raise ValueError('Populacja przekracza realistyczny zakres')
return v
# Walidacja działa
lion = Species(name="Lew", population=120) # OK
try:
lion = Species(name="lew", population=120)
except ValidationError as e:
print(e.errors()[0]["msg"]) # Value error, Nazwa musi zaczynać się wielką literąTwój ValueError Pydantic opakowuje w ValidationError z przedrostkiem "Value error". Dokumentacja dopisuje @classmethod, bo walidator działa, zanim powstanie obiekt.
Safari API z Pydantic
Na koniec model trafia do FastAPI. Wspólne pola zbieramy w SpeciesBase, a osobne klasy opisują wejście i odpowiedź:
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, ConfigDict, Field, field_validator
from typing import Literal
from datetime import datetime
app = FastAPI()
class SpeciesBase(BaseModel):
name: str = Field(..., min_length=2, max_length=100)
scientific_name: str = Field(..., pattern=r'^[A-Z][a-z]+ [a-z]+$')
population: int = Field(..., ge=0, le=1_000_000)
habitat: Literal["savanna", "forest", "desert", "wetland"]
@field_validator('scientific_name')
@classmethod
def validate_scientific_name(cls, v):
parts = v.split()
if len(parts) != 2:
raise ValueError('Nazwa naukowa musi mieć format: Genus species')
return v
class SpeciesCreate(SpeciesBase):
pass
class Species(SpeciesBase):
id: int
created_at: datetime = Field(default_factory=datetime.now)
model_config = ConfigDict(from_attributes=True)
@app.post("/species", response_model=Species)
async def create_species(species: SpeciesCreate):
# Pydantic automatycznie waliduje dane!
new_species = Species(id=1, **species.model_dump())
return new_speciesGdy klient wyśle "habitat": "ocean", FastAPI odpowie kodem 422, a create_species w ogóle się nie wykona. Starsza zagnieżdżona class Config ustąpiła w Pydantic 2 miejsca model_config, a from_attributes=True przyda się przy bazie danych.
Podsumowanie
- BaseModel - klasa bazowa,
model_dump()imodel_dump_json() - Pola opcjonalne:
Optional[str] = None - Automatyczna konwersja typów
- Field validators (gt, ge, pattern, etc.)
- Custom validators (@field_validator)
- Safari API z Pydantic
Następna lekcja: Async databases z SQLAlchemy!
Pamiętaj: model Pydantic to strażnik przy bramie parku - wpuszcza tylko dane o właściwym kształcie.
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Czym jest Pydantic?
2. Po jakiej klasie dziedziczy model Pydantic?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Układanie w pionie
Ułóż definicję modelu Pydantic dla gatunku Safari:
- Układanie w poziomie
Jak zdefiniować opcjonalne pole w Pydantic?
- Klikanie w kolejności
Ułóż pole z walidatorem Field:
- Edytor kodu
Napisz model Species z polami: name (str), population (int > 0), habitat (str), endangered (bool, domyślnie False).