概览
使用 Python 类型注解的数据验证和设置管理。
pydantic 在运行时强制执行类型提示，并在数据无效时提供用户友好的错误。
定义数据应该如何在纯正的、规范的 Python 中； 用 pydantic 验证它。
赞助商(Sponsors)¶
以下赞助商使 pydantic 的开发成为可能：
还有更多人在 GitHub 赞助商 上慷慨赞助 Samuel Colvin。
Example¶
from datetime import datetime
from typing import List, Optional
from pydantic import BaseModel
class User(BaseModel):
id: int
name = 'John Doe'
signup_ts: Optional[datetime] = None
friends: List[int] = []
external_data = {
'id': '123',
'signup_ts': '2019-06-01 12:22',
'friends': [1, 2, '3'],
}
user = User(**external_data)
print(user.id)
#> 123
print(repr(user.signup_ts))
#> datetime.datetime(2019, 6, 1, 12, 22)
print(user.friends)
#> [1, 2, 3]
print(user.dict())
"""
{
'id': 123,
'signup_ts': datetime.datetime(2019, 6, 1, 12, 22),
'friends': [1, 2, 3],
'name': 'John Doe',
}
"""
from datetime import datetime
from typing import Optional
from pydantic import BaseModel
class User(BaseModel):
id: int
name = 'John Doe'
signup_ts: Optional[datetime] = None
friends: list[int] = []
external_data = {
'id': '123',
'signup_ts': '2019-06-01 12:22',
'friends': [1, 2, '3'],
}
user = User(**external_data)
print(user.id)
#> 123
print(repr(user.signup_ts))
#> datetime.datetime(2019, 6, 1, 12, 22)
print(user.friends)
#> [1, 2, 3]
print(user.dict())
"""
{
'id': 123,
'signup_ts': datetime.datetime(2019, 6, 1, 12, 22),
'friends': [1, 2, 3],
'name': 'John Doe',
}
"""
from datetime import datetime
from pydantic import BaseModel
class User(BaseModel):
id: int
name = 'John Doe'
signup_ts: datetime | None = None
friends: list[int] = []
external_data = {
'id': '123',
'signup_ts': '2019-06-01 12:22',
'friends': [1, 2, '3'],
}
user = User(**external_data)
print(user.id)
#> 123
print(repr(user.signup_ts))
#> datetime.datetime(2019, 6, 1, 12, 22)
print(user.friends)
#> [1, 2, 3]
print(user.dict())
"""
{
'id': 123,
'signup_ts': datetime.datetime(2019, 6, 1, 12, 22),
'friends': [1, 2, 3],
'name': 'John Doe',
}
"""
(这个脚本是完整的，它应该“按原样”运行)
这里发生了什么：
id是 int 类型； 仅注解声明告诉 pydantic 这个字段是必需的。 如果可能，字符串、字节或浮点数将被强制转换为整数； 否则将引发异常。name从提供的默认值推断为字符串； 因为它有一个默认值，所以它不是必需的。signup_ts是一个不需要的日期时间字段（如果未提供则取值None）。 pydantic 将处理 unix 时间戳 int（例如1496498400）或表示日期和时间的字符串。friends使用 Python 的类型系统，并且需要一个整数列表。 与id一样，类整数对象将被转换为整数。
如果验证失败，pydantic 将引发错误并详细说明错误：
from pydantic import ValidationError
try:
User(signup_ts='broken', friends=[1, 2, 'not number'])
except ValidationError as e:
print(e.json())
(这个脚本依赖 User from previous example)
输出:
[
{
"loc": [
"id"
],
"msg": "field required",
"type": "value_error.missing"
},
{
"loc": [
"signup_ts"
],
"msg": "invalid datetime format",
"type": "value_error.datetime"
},
{
"loc": [
"friends",
2
],
"msg": "value is not a valid integer",
"type": "type_error.integer"
}
]
基本原理(Rationale)¶
所以 pydantic 使用了一些很酷的新语言特性，但我为什么要真正去使用它呢？
- 与您的 IDE/linter/brain 完美搭配
- 无需学习新的模式定义微语言。 如果您知道如何使用 Python 类型提示，您就会知道如何使用 pydantic。 数据结构只是您使用类型注释定义的类的实例，因此自动完成、linting、mypy、IDE（尤其是 PyCharm）和您的直觉都应该有效 正确使用您的验证数据。
- 双重用途
- pydantic 的 BaseSettings 类允许 pydantic 在“验证此请求数据”上下文和“加载我的系统设置”上下文中使用。 主要区别在于系统设置可以从环境变量中读取，并且通常需要更复杂的对象，如 DSN 和 Python 对象。
- 快速
- pydantic 一直很重视性能，大部分库都是用 cython 编译的，加速了 ~50%，它通常比大多数类似的库快或更快。
- 验证复杂结构
- 使用递归 pydantic 模型、
typing的 标准类型（例如List、Tuple、Dict等）和 validators 允许清晰、轻松地定义、验证和解析复杂的数据模式。 - 可扩展的
- pydantic 允许定义自定义数据类型，或者您可以在装饰有
validator的模型上使用方法扩展验证装饰器。 - 数据类整合
- 除了
BaseModel之外，pydantic 还提供了一个dataclass装饰器，它创建（几乎）带有输入数据解析和验证的普通 Python 数据类。
使用 Pydantic(Using Pydantic)¶
数百个组织和软件包正在使用 pydantic，包括：
- FastAPI
- 基于pydantic 和 Starlette 的高性能 API 框架，易于学习，编码速度快，可用于生产。
- Project Jupyter
- Jupyter notebook 的开发人员正在使用 pydantic 用于子项目，通过基于 FastAPI 的 Jupyter 服务器 Jupyverse，以及 FPS 的配置管理。
- Microsoft
- 正在将 pydantic（通过 FastAPI）用于 众多服务，其中一些正在“集成到核心 Windows 产品中，一些 办公用品。”
- Amazon Web Services
- 在 gluon-ts 中使用 pydantic，这是一个开源概率时间序列建模库。
- The NSA
- 在开源自动化框架 WALKOFF 中使用 pydantic。
- Uber
- 在 Ludwig 中使用 pydantic，这是一个开源 TensorFlow 包装器。
- Cuenca
- 是一家墨西哥新银行，它使用 pydantic 用于多个内部工具（包括 API 验证）和开源项目，如 stpmex，用于处理 墨西哥实时 24/7 银行间转账。
- 分子科学软件研究所
- 在 QCFractal 中使用 pydantic，这是一个用于量子化学的大规模分布式计算框架。
- Reach
- 信任 pydantic（通过 FastAPI）和 arq（Samuel 出色的异步任务队列）来可靠地支持多个关键任务微服务。
- Robusta.dev
- 正在使用 pydantic 来自动化 Kubernetes 故障排除和维护。 例如，他们的开源 在 Kubernetes 上调试和分析 Python 应用程序的工具 使用 pydantic 模型。
有关使用 pydantic 的更全面的开源项目列表，请参阅 github 上的依赖列表。
对 Pydantic 的讨论(Discussion of Pydantic)¶
讨论 pydantic 的播客和视频。
- Talk Python To Me
- pydantic 的创始人迈克尔·肯尼迪 (Michael Kennedy) 和塞缪尔·科尔文 (Samuel Colvin) 深入探讨了 pydantic 的历史及其众多用途和好处。
- Podcast.__init__
- 与 pydantic 的创造者 Samuel Colvin 讨论 pydantic 的起源以及它下一步可能走向何方的想法。
- Python Bytes Podcast
- “这是一个可爱的简单框架，解决了一些非常好的问题......使用 Python 类型注释的数据验证和设置管理，正是 Python 类型注释让我非常高兴......它自动与你的所有 IDE 一起工作 已经有了。”——迈克尔·肯尼迪
- Python pydantic Introduction – 赋予数据类超能力
- Alexander Hultnér 最初在 Python Pizza 大会上的演讲，向新用户介绍了 pydantic 并介绍了 pydantic 的核心功能。