pydantic

pydantic Best Practices

Pydantic v2 is the standard for data validation in modern Python. Follow these rules to build type-safe, efficient, and maintainable data models.

1. Model Naming and Organization

Always use clear, singular nouns for models and group them in a dedicated models/ package. This improves discoverability and maintains a consistent project structure.

❌ BAD:

# In user_operations.py
class UserData(BaseModel):
    name: str
    email: EmailStr

# In users_api.py
class UserRequest(BaseModel):
    name: str
    email: EmailStr

✅ GOOD:

# In models/user.py
from pydantic import BaseModel, EmailStr

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

2. Strict Typing and Immutability

Prefer concrete types over Any. Use Strict* types when no coercion is acceptable. Enable validate_assignment=True for mutable models, or frozen=True for immutable models. Immutability is generally preferred for data models to prevent unexpected state changes.

❌ BAD:

from pydantic import BaseModel
from typing import Any

class Item(BaseModel):
    quantity: Any # Allows "5" or 5
    price: float # Allows "10.5" or 10.5

✅ GOOD:

from pydantic import BaseModel, StrictInt, StrictFloat, ConfigDict

class ImmutableItem(BaseModel):
    model_config = ConfigDict(frozen=True) # Makes instances immutable
    id: int
    name: str
    quantity: StrictInt # Only accepts int, "5" will fail
    price: StrictFloat # Only accepts float, "10.5" will fail

class MutableUser(BaseModel):
    model_config = ConfigDict(validate_assignment=True) # Validates on update
    name: str
    age: int

user = MutableUser(name="Alice", age=30)
user.age = "31" # This will raise a ValidationError

3. Safe Default Values

Never use mutable objects (lists, dicts, sets) as direct default values. This leads to shared state across instances. Always use default_factory or Field(default_factory=...).