Kurs Python · Moduł 6: Async i FastAPI

Pydantic - walidacja danych z Rust

5 min czytania ·
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=None

Samo 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 equal
  • lt, le - less than, less or equal
  • min_length, max_length - długość string
  • pattern - regex validation
  • description - 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_species

Gdy 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() i model_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. 1. Czym jest Pydantic?

  2. 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).

  1. PytanieCzym jest Pydantic?
  2. PytanieBaseModel
  3. PytanieWalidacja typu
  4. Ułóż w kolejnościModel Pydantic
  5. Ułóż w kolejnościPole opcjonalne
  6. Kliknij w kolejnościField z walidatorem
  7. Zadanie z kodemModel gatunku

Przydatne artykuły