Pydantic

pydantic

Type-driven validation and serialization using Pydantic models.

Overview

Pydantic validates data using Python type hints and provides rich serialization via model_dump() and JSON schema output.

When to Use

• Validating request/response payloads
• Normalizing untrusted input
• Generating JSON schema for docs

Quick Start

uv pip install pydantic

from pydantic import BaseModel

class User(BaseModel):
    id: int
    email: str

user = User(id=1, email="a@example.com")

Core Patterns

1. Typed fields: strict schema definitions. 2. Field validators: custom validation logic. 3. Model validators: cross-field checks. 4. Serialization: model_dump() and model_dump_json(). 5. Settings: environment-driven config via BaseSettings.

Example: field_validator

from pydantic import BaseModel, field_validator

class Model(BaseModel):
    name: str

    @field_validator("name")
    @classmethod
    def ensure_not_empty(cls, v: str):
        if not v:
            raise ValueError("name required")
        return v

Example: model_validate + model_dump

from pydantic import BaseModel

class Model(BaseModel):
    foo: int

model = Model.model_validate({"foo": 1})
print(model.model_dump())

Troubleshooting

• Coercion surprises: use strict types if needed
• Slow validators: keep them minimal
• Mutable defaults: use default_factory

References

• https://docs.pydantic.dev/

Pydantic Pitfalls

Common Issues

• Silent coercion: unexpected type casting
• Slow validators: heavy logic in validation
• Mutable defaults: shared state

Fix Patterns

• Use strict types where needed
• Keep validators fast and simple
• Use Field(default_factory=...)

Example: default_factory

from pydantic import BaseModel, Field

class Model(BaseModel):
    tags: list[str] = Field(default_factory=list)

Pydantic Quickstart

Install

uv pip install pydantic

Minimal Model

from pydantic import BaseModel, EmailStr

class User(BaseModel):
    email: EmailStr
    age: int

user = User(email="a@example.com", age=30)

Serialization

user.model_dump()
user.model_dump_json()

Validators

from pydantic import field_validator

class User(BaseModel):
    age: int

    @field_validator("age")
    @classmethod
    def validate_age(cls, v: int):
        if v < 0:
            raise ValueError("age must be >= 0")
        return v