当前位置：首页 > article >正文

[Python] Pydantic从基础到高级用法示例

article 2025/2/21 23:30:51

Pydantic 是一个用于数据验证和设置管理的 Python 库，广泛应用于数据模型的构建、数据解析和验证。以下是 Pydantic 的基础用法到高级用法的代码示例与解析。

1. 基础用法：定义数据模型

Pydantic 的核心功能是通过定义数据模型来验证和解析数据。

示例代码：

from pydantic import BaseModel

# 定义一个数据模型
class User(BaseModel):
    id: int
    name: str
    age: int

# 使用模型验证数据
user_data = {"id": 1, "name": "Alice", "age": 25}
user = User(**user_data)

print(user)
print(user.name)  # 访问字段

解析：

BaseModel 是 Pydantic 的核心类，用于定义数据模型。
模型中的字段类型（如 int, str）用于数据验证。
通过 User(**user_data) 可以将字典数据解析为模型实例。
模型实例的字段可以直接访问，如 user.name。

2. 默认值与可选字段

可以为字段设置默认值，或将其标记为可选字段。

示例代码：

from typing import Optional
from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str
    age: Optional[int] = None  # 可选字段，默认值为 None
    is_active: bool = True  # 默认值为 True

# 使用模型验证数据
user_data = {"id": 1, "name": "Bob"}
user = User(**user_data)

print(user)

解析：

Optional[int] 表示字段是可选的，可以为 None。
默认值可以直接在字段定义中设置，如 is_active: bool = True。

3. 数据验证

Pydantic 提供了强大的数据验证功能，可以通过字段类型和自定义验证器实现。

示例代码：

from pydantic import BaseModel, ValidationError, validator

class User(BaseModel):
    id: int
    name: str
    age: int

    # 自定义验证器
    @validator("age")
    def check_age(cls, value):
        if value < 0:
            raise ValueError("Age must be a positive number")
        return value

# 验证数据
try:
    user = User(id=1, name="Alice", age=-10)
except ValidationError as e:
    print(e)

解析：

@validator 装饰器用于定义自定义验证器。
验证器会在数据解析时自动调用，如果验证失败会抛出 ValidationError。

4. 嵌套模型

Pydantic 支持嵌套模型，可以处理复杂的数据结构。

示例代码：

from pydantic import BaseModel

class Address(BaseModel):
    city: str
    country: str

class User(BaseModel):
    id: int
    name: str
    address: Address  # 嵌套模型

# 使用嵌套模型
user_data = {
    "id": 1,
    "name": "Alice",
    "address": {"city": "New York", "country": "USA"},
}
user = User(**user_data)

print(user)
print(user.address.city)  # 访问嵌套字段

解析：

嵌套模型通过将另一个 BaseModel 类作为字段类型实现。
嵌套模型的字段可以通过点号访问，如 user.address.city。

5. 动态模型创建

Pydantic 支持动态创建模型，适用于需要根据运行时条件生成模型的场景。

示例代码：

from pydantic import BaseModel, create_model

# 动态创建模型
DynamicUser = create_model(
    "DynamicUser",
    id=(int, ...),  # 必填字段
    name=(str, "Anonymous"),  # 默认值为 "Anonymous"
    age=(int, 18),  # 默认值为 18
)

# 使用动态模型
user = DynamicUser(id=1)
print(user)

解析：

create_model 函数用于动态创建模型。
字段类型和默认值可以通过元组指定。

6. JSON 序列化与反序列化

Pydantic 提供了便捷的 JSON 序列化与反序列化功能。

示例代码：

from pydantic import BaseModel

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

# 序列化为 JSON
user = User(id=1, name="Alice")
user_json = user.json()
print(user_json)

# 从 JSON 反序列化
user_data = '{"id": 2, "name": "Bob"}'
user = User.parse_raw(user_data)
print(user)

解析：

user.json() 将模型实例序列化为 JSON 字符串。
User.parse_raw() 将 JSON 字符串反序列化为模型实例。

7. 高级用法：自定义根类型

Pydantic 支持自定义根类型，适用于处理非标准数据结构。

示例代码：

from typing import List
from pydantic import BaseModel

class UserList(BaseModel):
    __root__: List[str]  # 自定义根类型

# 使用自定义根类型
user_list = UserList(__root__=["Alice", "Bob", "Charlie"])
print(user_list)
print(user_list.__root__)  # 访问根数据

解析：

__root__ 字段用于定义自定义根类型。
适用于处理列表、字典等非标准数据结构。

8. 高级用法：配置模型行为

Pydantic 允许通过 Config 类配置模型的行为。

示例代码：

from pydantic import BaseModel

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

    class Config:
        allow_mutation = False  # 禁止修改模型实例
        anystr_lower = True  # 自动将字符串字段转换为小写

# 使用配置
user = User(id=1, name="Alice")
print(user.name)  # 输出: alice

# 尝试修改字段会报错
try:
    user.name = "Bob"
except TypeError as e:
    print(e)

解析：

Config 类用于配置模型的行为。
例如，allow_mutation 控制是否允许修改模型实例，anystr_lower 控制是否自动将字符串字段转换为小写。

9. 高级用法：与 FastAPI 集成

Pydantic 是 FastAPI 的核心依赖，用于定义请求和响应的数据结构。

示例代码：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

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

@app.post("/users")
def create_user(user: User):
    return {"message": f"User {user.name} created"}

# 运行 FastAPI 应用
# uvicorn main:app --reload