pydantic

Pydantic Rules

Model Design

• Never use @dataclass decorator from dataclasses module.

• Use Pydantic BaseModel for all class definitions that hold data.

• Do not use NamedTuple for application or script data models; use an explicit BaseModel subclass instead.

• Pydantic provides validation, serialization, and type coercion out of the box.

• Expose zero-argument boolean accessors as @property instead of methods when they describe model state or capability.

• Prefer property names such as can_access_xyz over can_access_xyz().

class AccessPolicy(BaseModel):
    role: str

    @property
    def can_access_admin(self) -> bool:
        return self.role == "admin"


policy = AccessPolicy(role="member")

if not policy.can_access_admin:
    raise PermissionError("Admin access required")

• Never use Protocol for data models that hold data.

• Use Protocol only for structural typing of interfaces (callbacks, duck typing).

• Use Self return type for class methods.

Validation and Configuration

• Use model_config = ConfigDict(...) for model configuration.
• Use model_dump() instead of deprecated dict().
• Use model_validator decorator for custom validation.
• Do not add field_validator or model_validator just to coerce enum strings that should be represented by the enum itself; update the enum values to match the real contract instead.
• Do not define __init__ on BaseModel subclasses; use fields, validators, model_post_init, or factory/class methods instead.
• Never use pydantic.create_model; define an explicit BaseModel subclass instead. If create_model feels necessary, the design is probably too dynamic or too clever; refactor toward a named model class.

from enum import StrEnum

from pydantic import BaseModel, field_validator


class ShirtSize(StrEnum):
    SMALL = "small"
    LARGE = "large"

# Bad: validator added only to paper over the wrong enum values
class TShirtOrderBad(BaseModel):
    size: ShirtSize

    @field_validator("size", mode="before")
    @classmethod
    def validate_size(cls, value: str) -> str:
        return value.upper()