pydantic

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pydantic v2

Pydantic v2 is the standard library for data validation, serialization, and settings management in Python. It uses type annotations to define data schemas and validates data at runtime with a high-performance Rust core.

Pydantic v2是Python中用于数据验证、序列化和配置管理的标准库。它使用类型注解定义数据模式，并通过高性能的Rust内核在运行时验证数据。

Model Basics

模型基础

Define models by subclassing

BaseModel

. Use standard type annotations for fields and

Field()

for metadata and constraints.

python

from datetime import datetime
from typing import Optional
from pydantic import BaseModel, Field


class User(BaseModel):
    id: int
    name: str = Field(min_length=1, max_length=100, description="Full name")
    email: str
    age: Optional[int] = Field(default=None, ge=0, le=150)
    is_active: bool = True
    created_at: datetime = Field(default_factory=datetime.utcnow)

通过继承

BaseModel

来定义模型。为字段使用标准类型注解，使用

Field()

添加元数据和约束。

python

from datetime import datetime
from typing import Optional
from pydantic import BaseModel, Field


class User(BaseModel):
    id: int
    name: str = Field(min_length=1, max_length=100, description="Full name")
    email: str
    age: Optional[int] = Field(default=None, ge=0, le=150)
    is_active: bool = True
    created_at: datetime = Field(default_factory=datetime.utcnow)

Field Basics

Field基础

Required fields: declare with a type annotation and no default.
Optional fields: use
```
Optional[T]
```
(or
```
T | None
```
) with a default of
```
None
```
.
Default values: assign a literal or use
```
Field(default=...)
```
.
Default factories: use
```
Field(default_factory=callable)
```
for mutable defaults.

必填字段：仅声明类型注解，不设置默认值。
可选字段：使用
```
Optional[T]
```
（或
```
T | None
```
）并将默认值设为
```
None
```
。
默认值：直接赋值字面量或使用
```
Field(default=...)
```
。
默认工厂函数：使用
```
Field(default_factory=callable)
```
为可变类型设置默认值。

Common

Field()

Parameters

常用

Field()

参数

Parameter	Purpose
`default`	Static default value
`default_factory`	Callable producing a default
`alias`	Alternative name for parsing input
`title`	Human-readable title for JSON Schema
`description`	Field description for JSON Schema
`ge` , `gt` , `le` , `lt`	Numeric constraints
`min_length` , `max_length`	String/collection length
`pattern`	Regex pattern for strings
`exclude`	Exclude from serialization
`frozen`	Make individual field immutable

参数名称	用途
`default`	静态默认值
`default_factory`	生成默认值的可调用函数
`alias`	解析输入时使用的替代名称
`title`	JSON Schema中的人类可读标题
`description`	JSON Schema中的字段描述
`ge` , `gt` , `le` , `lt`	数值约束
`min_length` , `max_length`	字符串/集合长度约束
`pattern`	字符串匹配的正则表达式
`exclude`	序列化时排除该字段
`frozen`	将单个字段设为不可变

Common Field Types and Constraints

常见字段类型与约束

Pydantic ships constrained types and special types for common patterns.

python

from pydantic import (
    BaseModel,
    EmailStr,
    HttpUrl,
    Field,
    constr,
    conint,
    confloat,
    conlist,
)


class Profile(BaseModel):
    username: constr(min_length=3, max_length=30, pattern=r"^[a-zA-Z0-9_]+$")
    email: EmailStr
    website: HttpUrl | None = None
    score: conint(ge=0, le=100) = 0
    rating: confloat(ge=0.0, le=5.0) = 0.0
    tags: conlist(str, min_length=1, max_length=10) = ["general"]

Install
pydantic[email]
to use
EmailStr
.

Pydantic内置了约束类型和用于常见场景的特殊类型。

python

from pydantic import (
    BaseModel,
    EmailStr,
    HttpUrl,
    Field,
    constr,
    conint,
    confloat,
    conlist,
)


class Profile(BaseModel):
    username: constr(min_length=3, max_length=30, pattern=r"^[a-zA-Z0-9_]+$")
    email: EmailStr
    website: HttpUrl | None = None
    score: conint(ge=0, le=100) = 0
    rating: confloat(ge=0.0, le=5.0) = 0.0
    tags: conlist(str, min_length=1, max_length=10) = ["general"]

安装
pydantic[email]
以使用
EmailStr
。

Frequently Used Types

常用类型

```
EmailStr
```
-- validated email address.
```
HttpUrl
```
,
```
AnyUrl
```
-- validated URLs.
```
IPvAnyAddress
```
-- IPv4 or IPv6 address.
```
SecretStr
```
-- string hidden in repr and serialization.
```
FilePath
```
,
```
DirectoryPath
```
-- validated filesystem paths.
```
PastDatetime
```
,
```
FutureDatetime
```
-- temporal constraints.
```
PositiveInt
```
,
```
NegativeInt
```
,
```
NonNegativeInt
```
-- numeric shortcuts.
```
UUID4
```
-- UUID version 4.
```
Json[T]
```
-- parse a JSON string into type
```
T
```
.

```
EmailStr
```
-- 经过验证的电子邮箱地址。
```
HttpUrl
```
,
```
AnyUrl
```
-- 经过验证的URL。
```
IPvAnyAddress
```
-- IPv4或IPv6地址。
```
SecretStr
```
-- 在repr和序列化中隐藏的字符串。
```
FilePath
```
,
```
DirectoryPath
```
-- 经过验证的文件系统路径。
```
PastDatetime
```
,
```
FutureDatetime
```
-- 时间约束。
```
PositiveInt
```
,
```
NegativeInt
```
,
```
NonNegativeInt
```
-- 数值快捷类型。
```
UUID4
```
-- 版本4的UUID。
```
Json[T]
```
-- 将JSON字符串解析为
```
T
```
类型。

Model Configuration

模型配置

Control model behavior with

model_config

using

ConfigDict

python

from pydantic import BaseModel, ConfigDict


class Item(BaseModel):
    model_config = ConfigDict(
        str_strip_whitespace=True,
        frozen=False,
        from_attributes=True,
        populate_by_name=True,
        use_enum_values=True,
        validate_default=True,
        strict=False,
        json_schema_extra={"examples": [{"item_name": "Widget", "price": 9.99}]},
    )

    item_name: str = Field(alias="itemName")
    price: float

使用

ConfigDict

通过

model_config

控制模型行为。

python

from pydantic import BaseModel, ConfigDict


class Item(BaseModel):
    model_config = ConfigDict(
        str_strip_whitespace=True,
        frozen=False,
        from_attributes=True,
        populate_by_name=True,
        use_enum_values=True,
        validate_default=True,
        strict=False,
        json_schema_extra={"examples": [{"item_name": "Widget", "price": 9.99}]},
    )

    item_name: str = Field(alias="itemName")
    price: float

Key Configuration Options

关键配置选项

Option	Effect
`str_strip_whitespace`	Strip leading/trailing whitespace from strings
`frozen`	Make all fields immutable (model becomes hashable)
`from_attributes`	Allow initialization from ORM objects via attribute access
`populate_by_name`	Accept both field name and alias during parsing
`use_enum_values`	Store enum values instead of enum members
`validate_default`	Run validators on default values
`strict`	Disable type coercion globally
`extra`	`"forbid"` , `"allow"` , or `"ignore"` extra fields
`json_schema_extra`	Extend generated JSON Schema

选项	效果
`str_strip_whitespace`	去除字符串首尾的空白字符
`frozen`	将所有字段设为不可变（模型变为可哈希）
`from_attributes`	允许通过属性访问从ORM对象初始化模型
`populate_by_name`	解析时同时接受字段名和别名
`use_enum_values`	存储枚举值而非枚举成员
`validate_default`	对默认值运行验证器
`strict`	全局禁用类型转换
`extra`	处理额外字段的方式： `"forbid"` （禁止）、 `"allow"` （允许）或 `"ignore"` （忽略）
`json_schema_extra`	扩展生成的JSON Schema

Validators

验证器

Field Validators

字段验证器

Apply validation logic to individual fields with

@field_validator

python

from pydantic import BaseModel, field_validator


class Signup(BaseModel):
    username: str
    password: str

    @field_validator("username")
    @classmethod
    def username_must_be_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError("must be alphanumeric")
        return v.lower()

    @field_validator("password", mode="after")
    @classmethod
    def password_strength(cls, v: str) -> str:
        if len(v) < 8:
            raise ValueError("must be at least 8 characters")
        return v

```
mode="before"
```
-- run before Pydantic's own parsing (receives raw input).
```
mode="after"
```
(default) -- run after Pydantic parses and coerces the value.
Apply to multiple fields:
```
@field_validator("field_a", "field_b")
```
.

使用

@field_validator

为单个字段应用验证逻辑。

python

from pydantic import BaseModel, field_validator


class Signup(BaseModel):
    username: str
    password: str

    @field_validator("username")
    @classmethod
    def username_must_be_alphanumeric(cls, v: str) -> str:
        if not v.isalnum():
            raise ValueError("must be alphanumeric")
        return v.lower()

    @field_validator("password", mode="after")
    @classmethod
    def password_strength(cls, v: str) -> str:
        if len(v) < 8:
            raise ValueError("must be at least 8 characters")
        return v

```
mode="before"
```
-- 在Pydantic自身解析之前运行（接收原始输入）。
```
mode="after"
```
（默认） -- 在Pydantic解析并转换值之后运行。
应用于多个字段：
```
@field_validator("field_a", "field_b")
```
。

Model Validators

模型验证器

Validate the entire model for cross-field logic with

@model_validator

python

from pydantic import BaseModel, model_validator


class DateRange(BaseModel):
    start: datetime
    end: datetime

    @model_validator(mode="after")
    def check_date_order(self) -> "DateRange":
        if self.start >= self.end:
            raise ValueError("start must be before end")
        return self

```
mode="before"
```
-- receives raw input dict; useful for restructuring data.
```
mode="after"
```
-- receives the fully constructed model instance.

For advanced validator patterns including

BeforeValidator

AfterValidator

WrapValidator

, custom types, and discriminated unions, consult the validators reference.

使用

@model_validator

验证整个模型的跨字段逻辑。

python

from pydantic import BaseModel, model_validator


class DateRange(BaseModel):
    start: datetime
    end: datetime

    @model_validator(mode="after")
    def check_date_order(self) -> "DateRange":
        if self.start >= self.end:
            raise ValueError("start must be before end")
        return self

```
mode="before"
```
-- 接收原始输入字典；适用于重构数据。
```
mode="after"
```
-- 接收完全构造的模型实例。

有关包括

BeforeValidator

、

AfterValidator

、

WrapValidator

、自定义类型和鉴别联合在内的高级验证器模式，请参考验证器参考文档。

Computed Fields

计算字段

Derive fields from other values without storing them. Computed fields appear in serialization and JSON Schema.

python

from pydantic import BaseModel, computed_field


class Rectangle(BaseModel):
    width: float
    height: float

    @computed_field
    @property
    def area(self) -> float:
        return self.width * self.height

从其他值派生字段而不存储它们。计算字段会出现在序列化结果和JSON Schema中。

python

from pydantic import BaseModel, computed_field


class Rectangle(BaseModel):
    width: float
    height: float

    @computed_field
    @property
    def area(self) -> float:
        return self.width * self.height

Serialization

序列化

model_dump()

model_dump()

Convert a model instance to a dictionary.

python

user = User(id=1, name="Ada", email="ada@example.com")
data = user.model_dump()                        # full dict
data = user.model_dump(exclude_none=True)        # drop None values
data = user.model_dump(include={"id", "name"})   # only selected fields
data = user.model_dump(exclude={"created_at"})   # exclude fields
data = user.model_dump(by_alias=True)            # use alias names as keys
data = user.model_dump(mode="json")              # JSON-compatible types

将模型实例转换为字典。

python

user = User(id=1, name="Ada", email="ada@example.com")
data = user.model_dump()                        # 完整字典
data = user.model_dump(exclude_none=True)        # 移除None值
data = user.model_dump(include={"id", "name"})   # 仅包含指定字段
data = user.model_dump(exclude={"created_at"})   # 排除指定字段
data = user.model_dump(by_alias=True)            # 使用别名作为键
data = user.model_dump(mode="json")              # 转换为JSON兼容类型

model_dump_json()

model_dump_json()

Serialize directly to a JSON string (faster than

json.dumps(model.model_dump())

python

json_str = user.model_dump_json(indent=2, exclude_none=True)

直接序列化为JSON字符串（比

json.dumps(model.model_dump())

更快）。

python

json_str = user.model_dump_json(indent=2, exclude_none=True)

Serialization Aliases

序列化别名

Use

serialization_alias

to control output key names independently from parsing aliases.

python

class ApiResponse(BaseModel):
    internal_id: int = Field(serialization_alias="id")
    status_code: int = Field(serialization_alias="status")

使用

serialization_alias

独立于解析别名控制输出键名。

python

class ApiResponse(BaseModel):
    internal_id: int = Field(serialization_alias="id")
    status_code: int = Field(serialization_alias="status")

Custom Serializers

自定义序列化器

python

from pydantic import field_serializer

class Event(BaseModel):
    timestamp: datetime

    @field_serializer("timestamp")
    def serialize_ts(self, v: datetime, _info) -> str:
        return v.isoformat()

python

from pydantic import field_serializer

class Event(BaseModel):
    timestamp: datetime

    @field_serializer("timestamp")
    def serialize_ts(self, v: datetime, _info) -> str:
        return v.isoformat()

Deserialization

反序列化

From a Dictionary

从字典初始化

python

user = User.model_validate({"id": 1, "name": "Ada", "email": "ada@example.com"})

python

user = User.model_validate({"id": 1, "name": "Ada", "email": "ada@example.com"})

From a JSON String

从JSON字符串初始化

python

user = User.model_validate_json('{"id": 1, "name": "Ada", "email": "ada@example.com"}')

python

user = User.model_validate_json('{"id": 1, "name": "Ada", "email": "ada@example.com"}')

From ORM / Arbitrary Objects

从ORM/任意对象初始化

With

from_attributes=True

model_config

, initialize from objects with matching attributes.

python

class UserRead(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    name: str

在

model_config

中设置

from_attributes=True

后，可以从具有匹配属性的对象初始化模型。

python

class UserRead(BaseModel):
    model_config = ConfigDict(from_attributes=True)
    id: int
    name: str

sqlalchemy_user is an ORM instance

sqlalchemy_user是一个ORM实例

user_read = UserRead.model_validate(sqlalchemy_user)

undefined

user_read = UserRead.model_validate(sqlalchemy_user)

undefined

Settings Management

配置管理

Use

BaseSettings

to load configuration from environment variables,

.env

files, and other sources.

bash

pip install pydantic-settings

python

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        env_prefix="APP_",
        env_nested_delimiter="__",
        case_sensitive=False,
    )

    app_name: str = "My App"
    debug: bool = False
    database_url: str
    redis_url: str = "redis://localhost:6379"
    allowed_origins: list[str] = ["http://localhost:3000"]


settings = Settings()

使用

BaseSettings

从环境变量、

.env

文件和其他来源加载配置。

bash

pip install pydantic-settings

python

from pydantic import Field
from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        env_prefix="APP_",
        env_nested_delimiter="__",
        case_sensitive=False,
    )

    app_name: str = "My App"
    debug: bool = False
    database_url: str
    redis_url: str = "redis://localhost:6379"
    allowed_origins: list[str] = ["http://localhost:3000"]


settings = Settings()

Environment Variable Mapping

环境变量映射

With

env_prefix="APP_"

, the field

database_url

maps to

APP_DATABASE_URL

设置

env_prefix="APP_"

后，字段

database_url

会映射到环境变量

APP_DATABASE_URL

。

Nested Settings

嵌套配置

Use

env_nested_delimiter

to map nested models from flat environment variables.

python

class DatabaseSettings(BaseModel):
    host: str = "localhost"
    port: int = 5432
    name: str = "mydb"


class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_nested_delimiter="__")

    db: DatabaseSettings = DatabaseSettings()

Set

DB__HOST=prod-db

and

DB__PORT=5433

in the environment to override nested values.

使用

env_nested_delimiter

从扁平的环境变量映射嵌套模型。

python

class DatabaseSettings(BaseModel):
    host: str = "localhost"
    port: int = 5432
    name: str = "mydb"


class Settings(BaseSettings):
    model_config = SettingsConfigDict(env_nested_delimiter="__")

    db: DatabaseSettings = DatabaseSettings()

在环境中设置

DB__HOST=prod-db

和

DB__PORT=5433

即可覆盖嵌套值。

Secrets Directory

密钥目录

Load secrets from files (e.g., Docker secrets):

python

class Settings(BaseSettings):
    model_config = SettingsConfigDict(secrets_dir="/run/secrets")

    db_password: str

从文件加载密钥（例如Docker密钥）：

python

class Settings(BaseSettings):
    model_config = SettingsConfigDict(secrets_dir="/run/secrets")

    db_password: str

Model Inheritance and Composition

模型继承与组合

Inheritance

继承

Share common fields across models with standard class inheritance.

python

class TimestampMixin(BaseModel):
    created_at: datetime = Field(default_factory=datetime.utcnow)
    updated_at: datetime | None = None


class UserCreate(TimestampMixin):
    name: str
    email: str


class UserUpdate(BaseModel):
    name: str | None = None
    email: str | None = None

使用标准类继承在模型之间共享公共字段。

python

class TimestampMixin(BaseModel):
    created_at: datetime = Field(default_factory=datetime.utcnow)
    updated_at: datetime | None = None


class UserCreate(TimestampMixin):
    name: str
    email: str


class UserUpdate(BaseModel):
    name: str | None = None
    email: str | None = None

Composition (Nested Models)

组合（嵌套模型）

Nest models for structured data. Pydantic validates nested objects recursively.

python

class Address(BaseModel):
    street: str
    city: str
    country: str = "US"


class Company(BaseModel):
    name: str
    address: Address
    employees: list["Employee"] = []


class Employee(BaseModel):
    name: str
    role: str

Company.model_rebuild()  # resolve forward references

使用嵌套模型处理结构化数据。Pydantic会递归验证嵌套对象。

python

class Address(BaseModel):
    street: str
    city: str
    country: str = "US"


class Company(BaseModel):
    name: str
    address: Address
    employees: list["Employee"] = []


class Employee(BaseModel):
    name: str
    role: str

Company.model_rebuild()  # 解析前向引用

Generic Models

泛型模型

Create reusable, type-parameterized models with

Generic[T]

python

from typing import Generic, TypeVar
from pydantic import BaseModel

T = TypeVar("T")


class PaginatedResponse(BaseModel, Generic[T]):
    items: list[T]
    total: int
    page: int
    per_page: int
    has_next: bool

    @computed_field
    @property
    def total_pages(self) -> int:
        return (self.total + self.per_page - 1) // self.per_page

使用

Generic[T]

创建可复用的类型参数化模型。

python

from typing import Generic, TypeVar
from pydantic import BaseModel

T = TypeVar("T")


class PaginatedResponse(BaseModel, Generic[T]):
    items: list[T]
    total: int
    page: int
    per_page: int
    has_next: bool

    @computed_field
    @property
    def total_pages(self) -> int:
        return (self.total + self.per_page - 1) // self.per_page

Concrete usage

具体使用

class UserList(PaginatedResponse[User]): pass

Or inline

或内联使用

response = PaginatedResponse[User].model_validate(data)


Generic models generate accurate JSON Schemas per specialization, making them ideal for API response wrappers.

response = PaginatedResponse[User].model_validate(data)


泛型模型会为每个特化生成准确的JSON Schema，非常适合作为API响应包装器。

JSON Schema Generation

JSON Schema生成

Generate JSON Schema from any model for documentation, API specs, or frontend validation.

python

schema = User.model_json_schema()

Customize with

json_schema_extra

model_config

Field()

python

class Product(BaseModel):
    model_config = ConfigDict(
        json_schema_extra={
            "examples": [{"name": "Widget", "price": 9.99}]
        }
    )
    name: str
    price: float = Field(json_schema_extra={"examples": [9.99, 19.99]})

For FastAPI request/response models, consult the

fastapi

skill.

For advanced validator patterns, discriminated unions, recursive models, and custom types, consult the validators reference.

从任意模型生成JSON Schema，用于文档、API规范或前端验证。

python

schema = User.model_json_schema()

可以在

model_config

的

json_schema_extra

或

Field()

中自定义生成的Schema：

python

class Product(BaseModel):
    model_config = ConfigDict(
        json_schema_extra={
            "examples": [{"name": "Widget", "price": 9.99}]
        }
    )
    name: str
    price: float = Field(json_schema_extra={"examples": [9.99, 19.99]})

有关FastAPI请求/响应模型的内容，请参考

fastapi

技能文档。

有关高级验证器模式、鉴别联合、递归模型和自定义类型的内容，请参考验证器参考文档。

pydantic

Original

Translation

Pydantic v2

Pydantic v2

Model Basics

模型基础

Field Basics

Field基础

Common Field() Parameters

常用Field()参数

Common Field Types and Constraints

常见字段类型与约束

Frequently Used Types

常用类型

Model Configuration

模型配置

Key Configuration Options

关键配置选项

Validators

验证器

Field Validators

字段验证器

Model Validators

模型验证器

Computed Fields

计算字段

Serialization

序列化

model_dump()

model_dump()

model_dump_json()

model_dump_json()

Serialization Aliases

序列化别名

Custom Serializers

自定义序列化器

Deserialization

反序列化

From a Dictionary

从字典初始化

From a JSON String

从JSON字符串初始化

From ORM / Arbitrary Objects

从ORM/任意对象初始化

sqlalchemy_user is an ORM instance

sqlalchemy_user是一个ORM实例

Settings Management

配置管理

Environment Variable Mapping

环境变量映射

Nested Settings

嵌套配置

Secrets Directory

密钥目录

Model Inheritance and Composition

模型继承与组合

Inheritance

继承

Composition (Nested Models)

组合（嵌套模型）

Generic Models

泛型模型

Concrete usage

具体使用

Or inline

或内联使用

JSON Schema Generation

JSON Schema生成

Common
`Field()`
Parameters

常用
`Field()`
参数

`model_dump()`

`model_dump()`

`model_dump_json()`

`model_dump_json()`