Pydantic¶

版本文档: v2.9.2.

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

Pydantic 快速且可扩展，与您的代码风格检查器/IDE/思维方式完美融合。使用纯正的规范 Python 3.8+ 定义数据应该是什么样子；使用 Pydantic 验证它。

使用 Logfire 监控 Pydantic

Logfire 由与 Pydantic 相同的团队构建，是一个应用程序监控工具，与 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]


# this will record details of a successful validation to 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 的更多信息

为什么要使用 Pydantic？¶

由类型提示提供支持 - 使用 Pydantic，模式验证和序列化由类型注释控制；学习更少，编写更少代码，并与您的 IDE 和静态分析工具集成。了解更多…
速度 - Pydantic 的核心验证逻辑是用 Rust 编写的。因此，Pydantic 是 Python 中最快的數據验证库之一。了解更多…
JSON Schema - Pydantic 模型可以发出 JSON Schema，从而允许与其他工具轻松集成。了解更多…
严格和宽松模式 - Pydantic 可以在严格模式（数据不转换）或宽松模式（Pydantic 尝试将数据强制转换为适当的类型）下运行。了解更多…
数据类、TypedDicts 等等 - Pydantic 支持许多标准库类型的验证，包括 dataclass 和 TypedDict。了解更多…
自定义 - Pydantic 允许自定义验证器和序列化器以多种强大的方式更改数据处理方式。了解更多…
生态系统 - PyPI 上大约有 8000 个包使用 Pydantic，包括像 FastAPI、huggingface、Django Ninja、SQLModel 和 LangChain 这样的极受欢迎的库。了解更多…
经过实战检验 - Pydantic 每月下载量超过 7000 万次，被所有 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 将引发一个错误，并详细说明出了什么问题

验证错误

# continuing the above example...

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',
        },
    ]
    """