Notion Vault Portal Backup & Automation Hub

Pydantic v2 Cheatsheet

Pydantic is the most widely used data validation and settings management library for Python. It enforces type hints at runtime, providing friendly error messages and seamless integration with standard Python types.


1. Defining Models and Fields

Inherit from BaseModel to define structured data objects. Fields can have default values, constraints, and custom metadata.

from typing import List, Optional
from pydantic import BaseModel, Field, EmailStr

class InventoryItem(BaseModel):
    id: int
    name: str = Field(..., min_length=2, max_length=100)
    price: float = Field(..., gt=0.0, description="The price of the item must be positive")
    tags: List[str] = Field(default_factory=list)
    sku: Optional[str] = None

Essential Field Arguments

| Argument | Description | |———-|————-| | ... (Ellipsis) | Marks the field as strictly required (no default value) | | default | Set a static default value (e.g., default="pending") | | default_factory | Call a zero-argument function to create dynamic defaults (e.g., default_factory=list, default_factory=datetime.utcnow) | | gt / ge | Greater Than (>) / Greater Than or Equal (>=) | | lt / le | Less Than (<) / Less Than or Equal (<=) | | min_length / max_length | Constraint for string lengths | | pattern | Apply regular expression pattern validation (replaces regex in v1) |


2. Basic Model Operations

Pydantic models are simple to initialize, serialize, and validate:

# Initialization (Throws ValidationError if arguments are invalid)
item = InventoryItem(id=42, name="Wireless Mouse", price=29.99, tags=["tech", "office"])

# Accessing fields
print(item.name)  # "Wireless Mouse"

# Convert to Dictionary (replaces .dict() in v1)
item_dict = item.model_dump()
# {'id': 42, 'name': 'Wireless Mouse', 'price': 29.99, 'tags': ['tech', 'office'], 'sku': None}

# Convert to JSON String (replaces .json() in v1)
item_json = item.model_dump_json()
# '{"id":42,"name":"Wireless Mouse","price":29.99,"tags":["tech","office"],"sku":null}'

# Instantiate from Python Dictionary
new_item = InventoryItem.model_validate(item_dict)

# Instantiate from JSON String
new_item = InventoryItem.model_validate_json(item_json)

3. Pydantic v2 Validators

Validators are custom validation functions run before or after standard parsing steps. Pydantic v2 uses @field_validator and @model_validator.

Field Validators (@field_validator)

Used to validate a single field or multiple specific fields:

from pydantic import BaseModel, field_validator

class UserProfile(BaseModel):
    username: str
    phone_number: str

    @field_validator("username")
    @classmethod
    def validate_username(cls, value: str) -> str:
        if " " in value:
            raise ValueError("Username cannot contain spaces")
        return value.lower()

Model Validators (@model_validator)

Used to validate combinations of multiple fields or the model structure as a whole:

from typing_extensions import Self
from pydantic import BaseModel, model_validator

class Promotion(BaseModel):
    discount_rate: float
    is_active: bool

    @model_validator(mode="after")
    def check_active_discount(self) -> Self:
        if self.is_active and self.discount_rate <= 0.0:
            raise ValueError("Active promotions must have a discount rate greater than 0")
        return self
  • mode="after" (default): Runs after all fields are validated. Fields can be accessed directly as attributes (e.g. self.discount_rate).
  • mode="before": Runs before any field validation is performed. The input is a raw dictionary or object.

4. Handling Validation Errors

When validation fails, Pydantic raises a ValidationError containing precise information about what went wrong:

from pydantic import BaseModel, ValidationError

class Account(BaseModel):
    id: int
    balance: float

try:
    Account(id="not-an-int", balance=-10.0)
except ValidationError as e:
    # Print readable error text
    print(e)

    # Extract structural error details as list of dicts
    errors = e.errors()
    print(errors[0])
    # {'type': 'int_parsing', 'loc': ('id',), 'msg': 'Input should be a valid integer', 'input': 'not-an-int'}

5. TypeAdapter (Validating Non-Model Types)

Use TypeAdapter to validate standard Python lists, dicts, or other types directly without wrapping them in a BaseModel:

from typing import List
from pydantic import TypeAdapter, EmailStr

# Setup TypeAdapter for List of Emails
email_list_adapter = TypeAdapter(List[EmailStr])

raw_emails = ["alice@test.com", "bob@example.org"]

# Validates and parses the list
validated_emails = email_list_adapter.validate_python(raw_emails)

# Convert to JSON
json_data = email_list_adapter.dump_json(validated_emails)

6. BaseSettings (Settings Management)

To read configuration settings from environment variables or .env files, use the separate pydantic-settings package (v2 standard).

pip install pydantic-settings
from pydantic import RedisDsn
from pydantic_settings import BaseSettings, SettingsConfigDict

class AppSettings(BaseSettings):
    # Field type and default values (overridden by env variables if present)
    api_key: str
    redis_url: RedisDsn = "redis://localhost:6379/0"
    debug: bool = False

    # Configuration for environment variable prefixing and .env files
    model_config = SettingsConfigDict(
        env_prefix="APP_",          # Looks for APP_API_KEY, APP_DEBUG, etc.
        env_file=".env",            # Reads from .env file
        env_file_encoding="utf-8"
    )

settings = AppSettings()

7. Model Configurations (model_config)

Pydantic v2 configures models using a class-level variable model_config with ConfigDict:

from pydantic import BaseModel, ConfigDict

class SecureUser(BaseModel):
    model_config = ConfigDict(
        extra="forbid",             # Throws error if unexpected extra fields are provided
        str_strip_whitespace=True,  # Automatically strip whitespaces from all strings
        validate_assignment=True,   # Re-validate fields when they are assigned new values
        frozen=False                # If True, model becomes immutable
    )

    username: str
    email: str