跳转至

Pydantic

1. 什么是 Pydantic？

Pydantic 是一个数据验证和数据模型管理的库，利用 Python 的类型注解来定义结构化数据模型，并自动进行数据验证和转换。它的主要特点是：

  • 基于 Python 类型提示：模型字段类型通过类型提示定义。
  • 自动数据验证和转换：传入的数据会被自动验证并转换为正确的类型。
  • 简洁易用：比手动编写验证逻辑更加简洁且灵活。
  • 广泛应用：特别适用于构建 API、处理配置、解析复杂数据结构等场景。

2. 安装 Pydantic

你可以通过 pip 安装 Pydantic：

pip install pydantic

3. 基本概念与入门

Pydantic 的核心是 BaseModel，它允许定义数据模型，自动验证和处理传入数据。

3.1 定义数据模型

首先，通过继承 BaseModel 来定义数据模型：

from pydantic import BaseModel

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

3.2 创建模型实例

创建模型实例时，可以传入数据：

user = User(id=1, name="Alice")
print(user)

输出：

id=1 name='Alice' is_active=True
  • id 是 int 类型。
  • name 是 str 类型。
  • is_active 是布尔类型，有默认值 True。

3.3 数据验证和自动转换

Pydantic 会自动验证传入数据的类型，甚至可以进行类型转换。例如：

user = User(id="1", name="Alice", is_active="false")
print(user)

输出：

id=1 name='Alice' is_active=False
  • id 字段自动从字符串 "1" 转换为整数 1。
  • is_active 字段从字符串 "false" 转换为布尔值 False。

4. 数据验证与类型转换

4.1 验证错误处理

如果传入无效数据，Pydantic 会抛出异常：

from pydantic import ValidationError

try:
    user = User(id="abc", name="Alice")
except ValidationError as e:
    print(e)

输出：

1 validation error for User
id
  value is not a valid integer (type=type_error.integer)

4.2 自动类型转换

Pydantic 允许将传入的数据转换为指定的类型。例如，将字符串转换为整数、布尔类型等。

user = User(id="2", name="Bob", is_active="True")
print(user)

输出：

id=2 name='Bob' is_active=True

5. 字段默认值与可选字段

5.1 默认值

你可以为模型字段设置默认值：

class User(BaseModel):
    id: int
    name: str
    is_active: bool = True

user = User(id=1, name="Alice")
print(user)

输出：

id=1 name='Alice' is_active=True

5.2 可选字段

如果某个字段是可选的，可以使用 Optional 或 None 设置它。

from typing import Optional

class User(BaseModel):
    id: int
    name: Optional[str] = None

user = User(id=1)
print(user)

输出：

id=1 name=None

6. 嵌套模型

Pydantic 支持嵌套模型，允许将一个模型作为另一个模型的字段。

from typing import List

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

class User(BaseModel):
    id: int
    name: str
    addresses: List[Address]

# 使用嵌套模型
user = User(id=1, name="Alice", addresses=[{"city": "New York", "zipcode": "10001"}])
print(user)

输出：

id=1 name='Alice' addresses=[Address(city='New York', zipcode='10001')]

7. 自定义字段验证

你可以使用 Field() 函数来对字段设置更复杂的验证条件，比如字符串长度、数值范围等。

7.1 使用 Field() 添加约束

from pydantic import BaseModel, Field

class User(BaseModel):
    id: int = Field(..., gt=0)  # id 必须大于 0
    name: str = Field(..., min_length=3, max_length=50)  # 字符串长度 3 到 50

try:
    user = User(id=-1, name="Al")
except ValidationError as e:
    print(e)

输出：

2 validation errors for User
id
  ensure this value is greater than 0 (type=value_error.number.not_gt; limit_value=0)
name
  ensure this value has at least 3 characters (type=value_error.any_str.min_length; limit_value=3)

7.2 复杂验证逻辑

你可以通过定义模型的 @validator 方法来实现更复杂的验证逻辑：

from pydantic import BaseModel, validator

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

    @validator('age')
    def age_must_be_positive(cls, v):
        if v <= 0:
            raise ValueError('age must be positive')
        return v

try:
    user = User(id=1, name="Alice", age=-1)
except ValidationError as e:
    print(e)

输出：

1 validation error for User
age
  age must be positive (type=value_error)

8. 数据序列化与反序列化

8.1 转换为字典

你可以使用 dict() 方法将模型转换为字典：

user_dict = user.dict()
print(user_dict)

8.2 转换为 JSON

你可以使用 json() 方法将模型转换为 JSON 字符串：

user_json = user.json()
print(user_json)

9. 配置选项

你可以通过 Config 类来配置 Pydantic 模型的行为。

9.1 大小写敏感

你可以让字段名大小写不敏感：

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

    class Config:
        allow_population_by_field_name = True

user = User(id=1, name="Alice")

9.2 使用别名

你可以为字段设置别名：

class User(BaseModel):
    id: int
    full_name: str = Field(..., alias='fullName')

user = User(id=1, fullName="Alice Johnson")
print(user)

输出：

id=1 full_name='Alice Johnson'

10. 常见应用场景

10.1 用于 API 请求和响应

Pydantic 经常用于处理 API 的请求和响应数据。在构建 API 时，可以用 Pydantic 来定义和验证请求的数据结构：

from pydantic import BaseModel

class CreateUserRequest(BaseModel):
    name: str
    email: str

# 假设你使用 FastAPI 或其他框架，可以将模型作为请求体
# @app.post("/users/")
# async def create_user(user: CreateUserRequest):
#     return user

10.2 配置管理

你可以用 BaseSettings 类来管理应用的配置。它能够从环境变量或 .env 文件中加载配置。

from pydantic import BaseSettings

class Settings(BaseSettings):
    app_name: str
    debug: bool

    class Config:
        env_file = ".env"

settings = Settings()
print(settings.app_name)

11. 进阶用法

11.1 复杂字段类型

Pydantic 支持复杂类型如 List、Dict、Tuple 等。

from typing import List, Dict

class Item(BaseModel):
    name: str
    tags: List[str]
    metadata: Dict[str, str]

11.2 继承与重用

你可以使用类继承来复用和扩展 Pydantic 模型：

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

class AdminUser(BaseUser):
    admin_level: int

12. 总结

  • Pydantic 基于 Python 类型提示 来定义数据结构，提供了强大的自动验证和转换功能。
  • 你可以轻松地处理嵌套模型、自定义验证、数据序列化等复杂操作。
  • Pydantic 在 API 构建、配置管理 等场景中表现出色，能帮助开发者

简化代码逻辑。