第19章 Pydantic v2.14 发布:支持 Python 3.15、延迟导入及 TypeForm
Pydantic v2.14 已于 10 月 8 日发布。
现在可以通过 PyPI 安装:
pip install --upgrade pydantic
本次发布汇聚了 13 位外部贡献者的成果,包含多项新功能、性能优化和 bug 修复。此外,根据我们的版本管理策略,本次还包含一些被视为非破坏性的小改动,升级前请务必了解这些内容。本版本不再支持 Python 3.9,新增了对 Python 3.15 的支持。
亮点包括:
稳定化的 MISSING 哨兵值 支持 lazy imports(延迟导入) 支持 TypeForm
完整更新日志请见 GitHub。
快速导航
新功能 行为变更 性能
新功能 Pydantic 2.14 正式支持 Python 3.15,包括其中的大部分新特性,下面依次介绍。
稳定化的 MISSING 哨兵值 MISSING 哨兵值于 2.12 作为实验性功能引入,现已稳定,成为 Pydantic 主 API 的一部分。
MISSING 是一个单例,表示某个字段在校验时未被提供值。序列化时,值为 MISSING 的字段会从输出中排除。
from pydantic import MISSING, BaseModel
class Configuration(BaseModel): timeout: int | None | MISSING = MISSING
# 存储在别处的配置默认值: defaults = {'timeout': 200}
conf = Configuration()
# `timeout` 不会出现在序列化输出中: conf.model_dump() #> {}
# `MISSING` 值不会出现在 JSON Schema 中: Configuration.model_json_schema()['properties']['timeout'] #> {'anyOf': [{'type': 'integer'}, {'type': 'null'}], 'title': 'Timeout'}
# 可以用 `is` 来区分哨兵值和其他值: timeout = conf.timeout if conf.timeout is not MISSING else defaults['timeout']
PR 参考:#13782。
支持 lazy imports Lazy imports 由 Python 3.15 中的 PEP 810 引入。
借助 lazy imports,不同模块中的模型可以互相引用,而不会陷入循环导入:
a.py: lazy from .b import B
from pydantic import BaseModel
class A(BaseModel): b: B | None = None
b.py: lazy from .a import A
from pydantic import BaseModel
class B(BaseModel): a: A | None = None
详情请见文档。
PR 参考:#13776。
支持 TypeForm typing.TypeForm 由 Python 3.15 中的 PEP 747 引入,各大静态类型检查器均已支持。
Pydantic 现在在多处使用 TypeForm,尤其是 TypeAdapter:
from typing import reveal_type
from pydantic import TypeAdapter
ta = TypeAdapter(int | str)
validated = ta.validate_python(1)
reveal_type(validated) # In <= 2.13: Unknown # In >= 2.14: int | str
现在,类型检查器能够为传入 Pydantic 的任何类型形式(如 x | y 联合类型、Annotated[...] 等)推断出正确的类型,而不仅仅是类。
PR 参考:#13459。
支持 frozendict frozendict 类型由 Python 3.15 中的 PEP 814 引入。Pydantic 已支持该类型,其校验和序列化方式与普通 dict 一致。详情请见文档。
PR 参考:#13634。
create_model() 新增 __namespace__ 参数 create_model() 现在接受 __namespace__ 参数,用于向所创建模型的类命名空间添加任意属性,例如校验器、方法或计算字段:
from pydantic import computed_field, create_model
def full_name(self) -> str: return f'{self.first_name} {self.last_name}'
UserModel = create_model( 'UserModel', first_name=str, last_name=str, __namespace__={'full_name': computed_field(property(full_name))}, )
UserModel(first_name='John', last_name='Doe').model_dump() #> {'first_name': 'John', 'last_name': 'Doe', 'full_name': 'John Doe'}
原有的 __validators__ 参数仅限于校验器。现在建议改用 __namespace__,因为 __validators__ 将在 v3 中被弃用。
PR 参考:#13895。
新增核心 schema 类型 多个此前支持的类型现在拥有了专属的 core schema,也就是说它们由 pydantic-core 的 Rust 组件原生进行校验/序列化。此前 Pydantic 为它们定义了自定义 Python 校验器,速度更慢且不支持约束。
以下类型已完成迁移:
fractions.Fraction,见 #13339。校验过程中的 ZeroDivisionError 现已得到妥善处理。 具名元组,见 #13505。修复了多个与校验相关的问题。 collections.deque,见 #13757。 collections.OrderedDict,见 #13796。 collections.Counter,见 #13824。
行为变更 本次发布包含一些可能影响现有代码的小改动,升级前请务必逐项确认。
JSON Schema 变更 本次发布带来若干 JSON Schema 变更,可能影响你生成的模型 schema。
Decimal 的 pattern 在 2.12 中,#11987 为 Decimal 类型的 JSON Schema 添加了正则 pattern。由于部分用户基于生成的 schema 制定校验契约,这引发了一些问题。
因此,默认不再包含该 pattern。如需重新启用,可以定义自定义的 GenerateJsonSchema 子类(详情见文档)。
PR 参考:#13672。
TypeAdapter 配置 生成 JSON Schema 时,现在会使用 TypeAdapter 的配置:
from pydantic import ConfigDict, TypeAdapter
ta = TypeAdapter(list[bytes], config=ConfigDict(ser_json_bytes='base64')) ta.json_schema() #> {'type': 'array', 'items': {'type': 'string', 'format': 'base64url'}}
PR 参考:#13676。
其他 JSON Schema 变更 这些改动多为 bug 修复,旨在让 JSON Schema 与校验/序列化行为保持一致:
在 #13711 中,校验 JSON Schema 不再应用序列化用的时间格式。 在 #13714 中,JSON Schema 会体现 str_min_length 和 str_max_length 配置。 在 #13717 中,当 validate_by_alias 为 False 时,校验 JSON Schema 使用字段名。 在 #13891 中,修复了标准库 dataclass 和 TypedDict 的 JSON Schema 配置传递问题。 在 #13892 中,序列化推断时不再将 ser_json_timedelta 应用于所有 datetime 类型。 在 #13893 中,以一致的配置编码 JSON Schema 默认值。
model_config 不再被修改 在 2.14 之前,Pydantic 可能会修改 model_config 属性,例如填充来自已弃用设置项的值。现在不会再这样了:model_config 始终反映用户设置的值(与父类配置合并后):
from pydantic import BaseModel
class Base(BaseModel): model_config = {'title': 'MyBase'}
class Model(Base): model_config = {'populate_by_name': True}
Model.model_config #> In <= 2.13: {'title': 'MyBase', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True} #> In >= 2.14: {'title': 'MyBase', 'populate_by_name': True}
PR 参考:#13825。
validate_by_alias=False 时的模型签名 当 validate_by_alias 设为 False 时,模型和 Pydantic dataclass 生成的 __signature__ 现在使用字段名而非别名,与校验实际接受的参数保持一致:
import inspect
from pydantic import BaseModel, ConfigDict, Field
class Model(BaseModel): model_config = ConfigDict(validate_by_alias=False, validate_by_name=True)
my_field: int = Field(alias='myAlias')
inspect.signature(Model) #> In <= 2.13: (*, myAlias: int) -> None # In >= 2.14: (*, my_field: int) -> None
由 @jaideeppyne 贡献。PR 参考:#13730。
multiple_of 约束 为 multiple_of 传入非正值时,现在会在模型定义阶段报错。此前是在校验阶段抛出未处理的运行时异常。
PR 参考:#13862。
pipeline API 中的数值约束 在实验性的 pipeline API 中,数值约束(gt()、ge()、lt()、le() 和 multiple_of())现在始终由 pydantic-core 对数值类型原生应用。此前,某些约束会以 Python 校验器的形式执行,例如链式使用多个约束或约束值与校验类型不匹配时。因此,这些约束现在会体现在 JSON Schema 中,且校验错误信息与普通字段一致:
from typing import Annotated
from pydantic import TypeAdapter from pydantic.experimental.pipeline import validate_as
ta = TypeAdapter(Annotated[int, validate_as(int).ge(1).le(100)])
ta.json_schema() #> In <= 2.13: {'minimum': 1, 'type': 'integer'} #> In >= 2.14: {'maximum': 100, 'minimum': 1, 'type': 'integer'}
ta.validate_python(200) """ In <= 2.13: Value error, Expected <= 100 [type=value_error, input_value=200, input_type=int] In >= 2.14: Input should be less than or equal to 100 [type=less_than_equal, input_value=200, input_type=int] """
PR 参考:#13516。
wrap 序列化器中的无效 index_key wrap 序列化器的 handler 可接受可选的第二个参数 index_key,其值必须是整数或字符串。此前文档中的一个示例错误地传入了 info 参数,且只有在使用 include 或 exclude 时才会暴露问题。现在,传入这类无效值会显式报错:
from pydantic import BaseModel, model_serializer
class Model(BaseModel): a: int
@model_serializer(mode='wrap') def ser_model(self, handler, info): return handler(self, info) # should be `handler(self)`
Model(a=1).model_dump() """ In <= 2.13: {'a': 1} In >= 2.14: PydanticSerializationError: Error calling function `ser_model`: TypeError: 'index_key' is expected to be an integer or a string, got 'SerializationInfo(...)' """
如果你复用了这个写法,请在调用 handler 时去掉第二个参数。
PR 参考:#13506。
性能 2.14 对 schema 生成进行了多项优化。在我们的基准测试中,大多数优化单独可将模型构建时间缩短 5–20%,对于定义了大量模型的应用来说,导入阶段的累计提升相当可观:
在 #13573 中优化核心 schema 生成中的类型查找逻辑。 在 #13643 中重构类型引用逻辑。 在 #13725 中将 schema 收集逻辑迁移至 pydantic-core。 在 #13726 中提升 FieldInfo 构建性能。 在 #13614 中提升 GenerateSchema.generate_schema() 的分发性能。 在 #13523 中避免 gather_schemas_for_cleaning() 中的指数级核心 schema 遍历。 在 #13540 中为模型类构建引入微优化。
想体验这些新功能?现在就运行 pip install --upgrade pydantic 或 uv add --upgrade pydantic 升级,并查看完整的发布说明。有问题或反馈?欢迎加入我们的社区 Slack 交流。