Python course · Module 6: Async and FastAPI

Pydantic - data validation powered by Rust

6 min read ·
In this lesson5

Welcome! Darwin here. A park ranger typed the population as "one hundred twenty" instead of 120, and a date into the species field. Without checks, such an entry lands in the database and ruins the statistics of the whole reserve. Pydantic is a library for data validation and serialization built on type hints: you describe the shape of the data with type annotations, and it checks every value.

Pydantic is the core of FastAPI - the framework uses it to validate request parameters and bodies and to shape responses. In version 2 the validation logic moved to the pydantic-core package written in Rust, and according to its authors a typical model validates about 17x faster than in version 1.

Safari Analogy: Pydantic is like a quality control system for observations - it checks whether each observation has correct data (species exists, population is a number, date is valid). If something is wrong, it reports an error immediately!

Pydantic Basics

BaseModel - the base class

A model is a class that inherits from BaseModel. Each field is a name with a type annotation, and the value after = becomes the default:

from pydantic import BaseModel

class Species(BaseModel):
    id: int
    name: str
    population: int
    endangered: bool = False  # Default value

# Creating an instance
lion = Species(id=1, name="Lion", population=120, endangered=True)

print(lion.name)               # Lion
print(lion.model_dump())       # {'id': 1, 'name': 'Lion', 'population': 120, 'endangered': True}
print(lion.model_dump_json())  # {"id":1,"name":"Lion","population":120,"endangered":true}

model_dump() turns the model into a dictionary, and model_dump_json() into JSON text. Older tutorials use .dict() and .json() - they still work in Pydantic 2, but emit a deprecation warning and will disappear in version 3.

Optional fields

Not every observation has a description. A field that may stay empty gets the type Optional[str] and the default value None:

from typing import Optional
from pydantic import BaseModel

class Sighting(BaseModel):
    species: str
    count: int
    description: Optional[str] = None

print(Sighting(species="Lion", count=3))  # species='Lion' count=3 description=None

Optional[str] alone lets you pass None, but only = None lets you skip the field. Since Python 3.10 you can write the same as str | None = None.

Automatic type conversion

Data from forms and URLs arrives as text. Pydantic tries to convert it to the declared type:

# Pydantic automatically converts types!
species = Species(id="1", name="Lion", population="120", endangered="yes")

print(type(species.id))         # <class 'int'>  (conversion str→int)
print(type(species.population)) # <class 'int'>
print(species.endangered)       # True  (conversion "yes"→True)

Conversion happens only when no information is lost: "120" becomes a number, but "abc" or 1.5 won't pass into an int field. Pydantic doesn't insert None then, it raises an error.

Validation errors

When a conversion fails, Pydantic raises a ValidationError listing every problem. We catch it like any other exception:

from pydantic import ValidationError

try:
    # Invalid data
    species = Species(id="abc", name="Lion", population=-50)
except ValidationError as e:
    print(e.error_count())  # 1
    print(e.json())         # Detailed validation errors (JSON)

There is one error, because -50 is a valid int - the model knows no rule that a population can't be negative. Field adds such rules.

Field - advanced validation

Field attaches constraints to a field: number ranges, text length, a pattern. Three dots ... mark a required field:

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")

# Validation works!
lion = Species(
    id=1,
    name="Lion",
    scientific_name="Panthera leo",  # Must match the regex
    population=120
)

Now population=-50 would be rejected by ge=0. Field(gt=0) without a default also means a required field - it's shorter, so I recommend it.

Field validators:

  • gt, ge - greater than, greater or equal
  • lt, le - less than, less or equal
  • min_length, max_length - string length
  • pattern - regex validation
  • description - description for documentation

Custom validators

You write an unusual rule as a function with the @field_validator decorator. It returns the value or raises a 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('Name must start with an uppercase letter')
        return v

    @field_validator('population')
    @classmethod
    def population_realistic(cls, v):
        if v > 1_000_000:
            raise ValueError('Population exceeds realistic range')
        return v

# Validation works
lion = Species(name="Lion", population=120)  # OK

try:
    lion = Species(name="lion", population=120)
except ValidationError as e:
    print(e.errors()[0]["msg"])  # Value error, Name must start with an uppercase letter

Pydantic wraps your ValueError in a ValidationError with the "Value error" prefix. The documentation adds @classmethod, because the validator runs before the object exists.

Safari API with Pydantic

Finally the model goes into FastAPI. Shared fields live in SpeciesBase, and separate classes describe input and response:

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('Scientific name must have the 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 validates the data automatically!
    new_species = Species(id=1, **species.model_dump())
    return new_species

When a client sends "habitat": "ocean", FastAPI answers with status 422 and create_species never runs. The old nested class Config gave way to model_config in Pydantic 2, and from_attributes=True will help with the database.

Summary

  • BaseModel - the base class, model_dump() and model_dump_json()
  • Optional fields: Optional[str] = None
  • Automatic type conversion
  • Field validators (gt, ge, pattern, etc.)
  • Custom validators (@field_validator)
  • Safari API with Pydantic

Next lesson: Async databases with SQLAlchemy!

Remember: a Pydantic model is the ranger at the park gate - it lets in only data of the right shape.

Docs entries used in this lesson

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. What is Pydantic?

  2. 2. Which class does a Pydantic model inherit from?

These are 2 of 3 questions for this lesson. Solve the rest in the game.

Hands-on tasks in the game

  • Vertical ordering

    Arrange the Pydantic model definition for a Safari species:

  • Horizontal ordering

    How do you define an optional field in Pydantic?

  • Click in order

    Arrange a field with a Field validator:

  • Code editor

    Write a Species model with fields: name (str), population (int > 0), habitat (str), endangered (bool, default False).

  1. QuestionWhat is Pydantic?
  2. QuestionBaseModel
  3. QuestionType validation
  4. Put in orderPydantic model
  5. Put in orderOptional field
  6. Click in orderField with validator
  7. Coding taskSpecies model

Useful articles