Pydantic 是 Python 中一个用于数据验证和设置管理的库，主要通过 Python 类型注解（Type Hints）来定义数据结构，并自动验证输入数据的合法性。它广泛应用于 API 开发（如 FastAPI）、配置管理、数据序列化等场景。
核心功能
- 数据验证
自动检查输入数据是否符合类型和约束条件（如字符串长度、数字范围等）。 - 类型转换
将原始数据（如 JSON、字典）转换为 Python 类型（如datetime、Enum）。 - 序列化
轻松将模型转换为字典或 JSON。 - IDE 友好
配合类型提示，提供代码补全和错误检查。
基础用法示例
1. 定义一个数据模型
from pydantic import BaseModel, Field, EmailStr
from datetime import datetimeclass User(BaseModel):id: intname: str = Field(min_length=2, max_length=10) # 约束字符串长度email: EmailStr # 自动验证邮箱格式signup_time: datetime | None = None # 可选字段# 使用示例
user_data = {"id": 123,"name": "Alice","email": "alice@example.com","signup_time": "2024-01-01T12:00:00"
}user = User(**user_data) # 自动验证和转换
print(user)
# 输出：id=123 name='Alice' email='alice@example.com' signup_time=datetime.datetime(2024, 1, 1, 12, 0)
2. 验证失败时的错误处理
try:User(id=1, name="A", email="invalid-email")
except Exception as e:print(e)
# 输出：
# 1 validation error for User
# email
# value is not a valid email address (type=value_error.email)
3. 序列化为字典或 JSON
user_dict = user.model_dump() # 转为字典
user_json = user.model_dump_json() # 转为 JSON 字符串
高级特性
1. 自定义验证器
from pydantic import validatorclass Product(BaseModel):price: float@validator("price")def price_must_be_positive(cls, v):if v <= 0:raise ValueError("价格必须为正数")return vProduct(price=10.5) # 正常
Product(price=-1) # 抛出 ValueError
2. 嵌套模型
class Address(BaseModel):city: strstreet: strclass Company(BaseModel):name: straddress: Address # 嵌套模型company = Company(name="DeepSeek", address={"city": "Hangzhou", "street": "Xihu"})
3. 动态模型（Settings 配置）
from pydantic_settings import BaseSettingsclass AppSettings(BaseSettings):api_key: strdebug: bool = Falseclass Config:env_file = ".env" # 从 .env 文件加载配置settings = AppSettings() # 自动读取环境变量
Pydantic 版本注意
- Pydantic V1：旧版（如
pydantic<2.0），语法略有不同（如.dict()而非.model_dump()）。 - Pydantic V2：新版（推荐），性能更好，功能更丰富。
安装最新版：
pip install pydantic pydantic-settings
常见应用场景
- API 请求/响应验证（如 FastAPI）
from fastapi import FastAPI app = FastAPI()@app.post("/users") def create_user(user: User): # 自动验证请求体return {"message": f"User {user.name} created"} - 配置文件管理
通过环境变量或文件加载配置。 - 数据管道
确保输入数据符合预期格式。
与其他工具对比
| 工具 | 特点 |
|---|---|
| Pydantic | 基于类型注解，强调验证和序列化 |
| Dataclasses | 仅提供数据容器，无验证功能 |
| Marshmallow | 需显式定义 Schema，灵活性高但更冗长 |
Pydantic 的简洁性和强大功能使其成为 Python 生态中数据处理的标杆工具。
)
-01)
