Pydantic 验证¶

Documentation for development version.

Pydantic 是 Python 中使用最广泛的数据验证库。

Pydantic 快速且可扩展，与您的代码检查工具/IDE/大脑完美配合。使用纯正、规范的 Python 3.9+ 定义数据应该是什么样子；使用 Pydantic 进行验证。

使用 Pydantic Logfire 监控 Pydantic

Pydantic Logfire 是一个应用程序监控工具，使用起来就像 Pydantic 本身一样简单而强大。

Logfire 与许多流行的 Python 库集成，包括 FastAPI、OpenAI 和 Pydantic 本身，因此您可以使用 Logfire 监控 Pydantic 验证并了解某些输入验证失败的原因：

使用 Logfire 监控 Pydantic

from datetime import datetime

import logfire

from pydantic import BaseModel

logfire.configure()
logfire.instrument_pydantic()  # (1)!


class Delivery(BaseModel):
    timestamp: datetime
    dimensions: tuple[int, int]


# 这将记录成功验证的详细信息到 logfire
m = Delivery(timestamp='2020-01-02T03:04:05Z', dimensions=['10', '20'])
print(repr(m.timestamp))
#> datetime.datetime(2020, 1, 2, 3, 4, 5, tzinfo=TzInfo(UTC))
print(m.dimensions)
#> (10, 20)

Delivery(timestamp='2020-01-02T03:04:05Z', dimensions=['10'])  # (2)!

设置 logfire 记录所有成功和失败的验证，使用 record='failure' 仅记录失败的验证，了解更多。
这将抛出 ValidationError，因为 dimensions 太少，输入数据和验证错误的详细信息将记录在 Logfire 中。

在 Logfire 平台中会给您这样的视图：

这只是一个简单的示例，但希望能够清楚地说明对更复杂应用程序进行监控的潜在价值。

了解更多关于 Pydantic Logfire

订阅 The Pydantic Stack 新闻通讯，获取 Logfire、Pydantic AI 和 Pydantic 的更新和教程：

为什么使用 Pydantic？¶

由类型提示驱动 — 使用 Pydantic，模式验证和序列化由类型注解控制；需要学习的内容更少，需要编写的代码更少，并且与您的 IDE 和静态分析工具集成。了解更多…
速度 — Pydantic 的核心验证逻辑用 Rust 编写。因此，Pydantic 是 Python 最快的数据验证库之一。了解更多…
JSON Schema — Pydantic 模型可以生成 JSON Schema，便于与其他工具集成。了解更多…
严格和宽松模式 — Pydantic 可以运行在严格模式（不转换数据）或宽松模式下，在宽松模式下 Pydantic 会尝试将数据强制转换为适当的正确类型。了解更多…
数据类、TypedDicts 等 — Pydantic 支持验证许多标准库类型，包括 dataclass 和 TypedDict。了解更多…
自定义 — Pydantic 允许自定义验证器和序列化器，以多种强大的方式改变数据处理方式。了解更多…
生态系统 — PyPI 上大约有 8,000 个包使用 Pydantic，包括非常受欢迎的库如 FastAPI、huggingface、Django Ninja、SQLModel 和 LangChain。了解更多…
久经考验 — Pydantic 每月下载量超过 3.6 亿次，被所有 FAANG 公司和纳斯达克 25 家最大公司中的 20 家使用。如果您想用 Pydantic 做某件事，可能已经有人做过了。了解更多…

安装 Pydantic 非常简单：pip install pydantic

Pydantic 示例¶

要看到 Pydantic 的实际效果，让我们从一个简单的示例开始，创建一个继承自 BaseModel 的自定义类：

验证成功

from datetime import datetime

from pydantic import BaseModel, PositiveInt


class User(BaseModel):
    id: int  # (1)!
    name: str = 'John Doe'  # (2)!
    signup_ts: datetime | None  # (3)!
    tastes: dict[str, PositiveInt]  # (4)!


external_data = {
    'id': 123,
    'signup_ts': '2019-06-01 12:22',  # (5)!
    'tastes': {
        'wine': 9,
        b'cheese': 7,  # (6)!
        'cabbage': '1',  # (7)!
    },
}

user = User(**external_data)  # (8)!

print(user.id)  # (9)!
#> 123
print(user.model_dump())  # (10)!
"""
{
    'id': 123,
    'name': 'John Doe',
    'signup_ts': datetime.datetime(2019, 6, 1, 12, 22),
    'tastes': {'wine': 9, 'cheese': 7, 'cabbage': 1},
}
"""

id 的类型是 int；仅注解声明告诉 Pydantic 这个字段是必需的。字符串、字节或浮点数在可能的情况下将被强制转换为整数；否则将抛出异常。
name 是一个字符串；因为它有默认值，所以不是必需的。
signup_ts 是一个必需的 datetime 字段，但可以提供值 None； Pydantic 将处理 Unix 时间戳整数（例如 1496498400）或表示日期和时间的字符串。
tastes 是一个字典，键为字符串，值为正整数。PositiveInt 类型是 Annotated[int, annotated_types.Gt(0)] 的简写。
这里的输入是 ISO 8601 格式的日期时间，但 Pydantic 会将其转换为 datetime 对象。
这里的键是 bytes，但 Pydantic 会处理将其强制转换为字符串。
同样，Pydantic 会将字符串 '1' 强制转换为整数 1。
我们通过将外部数据作为关键字参数传递给 User 来创建 User 的实例。
我们可以作为模型的属性访问字段。
我们可以使用 model_dump() 将模型转换为字典。

如果验证失败，Pydantic 将抛出一个包含问题详细信息的错误：

验证错误

# 继续上面的示例...

from datetime import datetime
from pydantic import BaseModel, PositiveInt, ValidationError


class User(BaseModel):
    id: int
    name: str = 'John Doe'
    signup_ts: datetime | None
    tastes: dict[str, PositiveInt]


external_data = {'id': 'not an int', 'tastes': {}}  # (1)!

try:
    User(**external_data)  # (2)!
except ValidationError as e:
    print(e.errors())
    """
    [
        {
            'type': 'int_parsing',
            'loc': ('id',),
            'msg': 'Input should be a valid integer, unable to parse string as an integer',
            'input': 'not an int',
            'url': 'https://errors.pydantic.dev/2/v/int_parsing',
        },
        {
            'type': 'missing',
            'loc': ('signup_ts',),
            'msg': 'Field required',
            'input': {'id': 'not an int', 'tastes': {}},
            'url': 'https://errors.pydantic.dev/2/v/missing',
        },
    ]
    """