python中的数据模型-pydantic浅讲

news2025/4/15 15:57:59

数据模型-pydantic

1. 基本用法

通过继承 BaseModel，你可以定义一个数据模型类。类的属性使用类型注解来声明字段的类型

from pydantic import BaseModel

class User(BaseModel):
    name: str
    age: int
    is_active: bool = True  # 默认值

字段类型：每个字段需要指定类型（如 str, int, bool 等）。
默认值：可以给字段设置默认值（如 is_active: bool = True）

2. 数据验证

当用数据初始化模型时，pydantic 会自动验证数据的类型和约束。如果数据不合法，会抛出 ValidationError

# 合法数据
user1 = User(name="Alice", age=30)
print(user1)  # name='Alice' age=30 is_active=True

# 非法数据（类型错误）
try:
    user2 = User(name="Bob", age="thirty")
except ValidationError as e:
    print(e)  # 输出错误详情：age 不是整数

3. 模型实例的属性

模型实例的字段可以直接通过属性访问：

print(user1.name)       # Alice
print(user1.age)        # 30
print(user1.is_active)  # True

4. 字段类型与自动转换

pydantic 会尝试将输入数据转换为声明的类型。例如，字符串 “30” 会被转换为整数 30

user3 = User(name="Charlie", age="30", is_active="no")
print(user3)  # name='Charlie' age=30 is_active=False

5. 可选字段与必需字段

默认情况下，所有没有默认值的字段都是必填字段。
如果某个字段可以是 None 或可选，需要用 Optional 或 Union

from typing import Optional

class User(BaseModel):
    name: str
    age: Optional[int] = None  # 可选字段

6. 嵌套模型

BaseModel 可以嵌套其他 BaseModel

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

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

user = User(name="Alice", address={"street": "Main St", "city": "New York"})
print(user.address.city)  # New York

7. 自定义验证器

使用 @validator 装饰器添加自定义验证逻辑

from pydantic import validator

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

    @validator("age")
    def age_must_be_positive(cls, v):
        if v < 0:
            raise ValueError("年龄不能为负数")
        return v

try:
    user = User(name="Bob", age=-10)
except ValidationError as e:
    print(e)  # 年龄不能为负数

8. 模型配置

通过内部的 Config 类可以配置模型行为：

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

    class Config:
        allow_mutation = False  # 禁止修改实例
        extra = "forbid"        # 禁止额外字段

user = User(name="Alice", age=30)
user.age = 31  # 抛出错误：实例不可变

常用配置选项：

allow_mutation: 是否允许修改实例
extra: 控制额外字段的行为（allow、ignore、forbid）。
json_encoders: 自定义 JSON 编码方式

9. 数据解析与导出

解析数据：用 parse_obj 或 parse_raw 解析字典或 JSON 字符串。
导出数据：用 dict() 或 json() 导出为字典或 JSON

user_data = {"name": "Alice", "age": 30}
user = User.parse_obj(user_data)  # 从字典解析

print(user.dict())  # {'name': 'Alice', 'age': 30, 'is_active': True}
print(user.json())  # {"name": "Alice", "age": 30, "is_active": true}

10. 动态默认值

如果默认值需要动态生成（例如列表），使用 default_factory：

from typing import List
from pydantic import Field

class Model(BaseModel):
    items: List[str] = Field(default_factory=list)

model = Model()
print(model.items)  # []

11. 字段别名

可以通过 alias 设置字段的别名（用于解析数据）

class User(BaseModel):
    name: str
    age: int = Field(..., alias="user_age")

user = User.parse_obj({"name": "Alice", "user_age": 30})
print(user.age)  # 30