迁移指南

Pydantic V2 引入了许多对 API 的变更，包括一些破坏性变更。

本页面提供了一份指南，重点介绍最重要的变更，以帮助您将代码从 Pydantic V1 迁移到 Pydantic V2。

安装 Pydantic V2¶

Pydantic V2 现在是 Pydantic 的当前生产版本。您可以从 PyPI 安装 Pydantic V2

pip install -U pydantic

如果您遇到任何问题，请使用 bug V2 标签在 GitHub 上创建一个 issue。这将有助于我们积极监控和跟踪错误，并持续改进库的性能。

如果您因任何原因需要使用最新的 Pydantic V1，请参阅下面的继续使用 Pydantic V1 的功能部分，了解有关安装和从 pydantic.v1 导入的详细信息。

代码转换工具¶

我们创建了一个工具来帮助您迁移代码。该工具仍处于测试阶段，但我们希望它能帮助您更快地迁移代码。

您可以从 PyPI 安装该工具

pip install bump-pydantic

使用方法很简单。如果您的项目结构是

* repo_folder
    * my_package
        * <python source files> ...

那么您需要执行

cd /path/to/repo_folder
bump-pydantic my_package

请在 Bump Pydantic 仓库中查看更多相关信息。

继续使用 Pydantic V1 的功能¶

当您需要时，Pydantic V1 仍然可用，但我们建议迁移到 Pydantic V2 以利用其改进和新功能。

如果您需要使用最新的 Pydantic V1，您可以通过以下命令安装它

pip install "pydantic==1.*"

Pydantic V2 包也继续通过从 pydantic.v1 导入来提供对 Pydantic V1 API 的访问。

例如，您可以使用 Pydantic V1 的 BaseModel 类，而不是 Pydantic V2 的 pydantic.BaseModel 类

from pydantic.v1 import BaseModel

您还可以导入已从 Pydantic V2 中移除的函数，例如 lenient_isinstance

from pydantic.v1.utils import lenient_isinstance

Pydantic V1 文档可在 https://docs.pydantic.org.cn/1.10/ 查看。

在 v1/v2 环境中使用 Pydantic v1 功能¶

从 pydantic>=1.10.17 开始，pydantic.v1 命名空间可以在 V1 中使用。这使得迁移到同样支持 pydantic.v1 命名空间的 V2 更加容易。为了解除对 pydantic<2 的依赖并继续使用 V1 功能，请执行以下步骤

将 pydantic<2 替换为 pydantic>=1.10.17
查找并替换所有出现的

from pydantic.<module> import <object>

为

from pydantic.v1.<module> import <object>

以下是根据您的 pydantic 版本导入 v1 功能的方法

pydantic>=1.10.17,<3pydantic<3

从 v1.10.17 开始，.v1 命名空间在 V1 中可用，允许如下导入

from pydantic.v1.fields import ModelField

所有 Pydantic V1 和 V2 版本都支持以下导入模式，以防您不知道正在使用哪个版本的 Pydantic

try:
    from pydantic.v1.fields import ModelField
except ImportError:
    from pydantic.fields import ModelField

注意

当使用 pydantic>=1.10.17,<2 并带有 .v1 命名空间导入模块时，这些模块将*不*是与没有 .v1 命名空间的相同导入相同的模块，但导入的符号*将*是相同的。例如 pydantic.v1.fields is not pydantic.fields 但 pydantic.v1.fields.ModelField is pydantic.fields.ModelField。幸运的是，这在绝大多数情况下不太可能产生影响。这只是提供更平滑迁移体验所带来的一个不幸的后果。

迁移指南¶

以下各节详细介绍了 Pydantic V2 中最重要的变更。

对 `pydantic.BaseModel` 的变更¶

各种方法名已更改；所有未弃用的 BaseModel 方法现在的名称都匹配 model_.* 或 __.*pydantic.*__ 格式。在可能的情况下，我们保留了旧名称的已弃用方法以帮助简化迁移，但调用它们会发出 DeprecationWarning 警告。

Pydantic V1	Pydantic V2
`__fields__`	`model_fields`
`__private_attributes__`	`__pydantic_private__`
`__validators__`	`__pydantic_validator__`
`construct()`	`model_construct()`
`copy()`	`model_copy()`
`dict()`	`model_dump()`
`json_schema()`	`model_json_schema()`
`json()`	`model_dump_json()`
`parse_obj()`	`model_validate()`
`update_forward_refs()`	`model_rebuild()`

一些内置的数据加载功能已被计划移除。特别是，parse_raw 和 parse_file 现已弃用。在 Pydantic V2 中，model_validate_json 的工作方式类似于 parse_raw。否则，您应该先加载数据，然后将其传递给 model_validate。
from_orm 方法已被弃用；您现在只需使用 model_validate（相当于 Pydantic V1 中的 parse_obj）即可实现类似的功能，前提是您已在模型配置中设置 from_attributes=True。
模型的 __eq__ 方法已更改。
- 模型只能与其他 BaseModel 实例相等。
- 要使两个模型实例相等，它们必须具有相同的
  - 类型（或者，对于泛型模型，是非参数化的泛型原始类型）
  - 字段值
  - 额外值（仅当 model_config['extra'] == 'allow' 时相关）
  - 私有属性值；具有不同私有属性值的模型不再相等。
  - 模型不再等于包含其数据的字典。
  - 不同类型的非泛型模型永远不相等。
  - 具有不同原始类型的泛型模型永远不相等。我们不要求*精确*的类型相等，以便例如 MyGenericModel[Any] 的实例可以等于 MyGenericModel[int] 的实例。
我们用一个名为 RootModel 的新类型替换了使用 __root__ 字段来指定“自定义根模型”的方式，该新类型旨在取代 Pydantic V1 中使用名为 __root__ 的字段的功能。请注意，RootModel 类型不再支持 arbitrary_types_allowed 配置设置。有关解释，请参阅此 issue 评论。
我们显著扩展了 Pydantic 与自定义序列化相关的能力。特别是，我们添加了 @field_serializer、@model_serializer 和 @computed_field 装饰器，它们各自解决了 Pydantic V1 中的各种不足。
- 有关这些新装饰器的用法文档，请参阅自定义序列化器。
- 由于性能开销和实现复杂性，我们现在已弃用在模型配置中指定 json_encoders 的支持。此功能最初是为了实现自定义序列化逻辑而添加的，我们认为新的序列化装饰器在大多数常见场景中是更好的选择。
我们更改了当模型的子类作为父模型中的嵌套字段出现时与序列化相关的行为。在 V1 中，我们总是包含子类实例的所有字段。在 V2 中，当我们转储一个模型时，我们只包含在字段的注解类型上定义的字段。这有助于防止一些意外的安全漏洞。您可以在模型导出文档的相关部分中阅读更多相关信息（包括如何选择退出此行为）。
GetterDict 已被移除，因为它只是 orm_mode 的一个实现细节，而 orm_mode 已被移除。
在许多情况下，传递给构造函数的参数将被**复制**以执行验证和必要时的强制转换（请参阅文档）。在将可变对象作为参数传递给构造函数的情况下，这一点尤其值得注意。
.json() 方法已被弃用，尝试使用此已弃用的方法并带有 indent 或 ensure_ascii 等参数可能会导致令人困惑的错误。为获得最佳效果，请切换到 V2 的等效方法 model_dump_json()。如果您仍想使用上述参数，可以使用此变通方法。
非字符串键值的 JSON 序列化通常通过 str(key) 完成，这导致了一些行为上的变化，例如以下

from typing import Optional

from pydantic import BaseModel as V2BaseModel
from pydantic.v1 import BaseModel as V1BaseModel


class V1Model(V1BaseModel):
    a: dict[Optional[str], int]


class V2Model(V2BaseModel):
    a: dict[Optional[str], int]


v1_model = V1Model(a={None: 123})
v2_model = V2Model(a={None: 123})

# V1
print(v1_model.json())
#> {"a": {"null": 123}}

# V2
print(v2_model.model_dump_json())
#> {"a":{"None":123}}

model_dump_json() 的结果是紧凑的以节省空间，并且并不总是与 json.dumps() 的输出完全匹配。尽管如此，您可以轻松修改 json.dumps() 结果中使用的分隔符以使两个输出对齐

import json

from pydantic import BaseModel as V2BaseModel
from pydantic.v1 import BaseModel as V1BaseModel


class V1Model(V1BaseModel):
    a: list[str]


class V2Model(V2BaseModel):
    a: list[str]


v1_model = V1Model(a=['fancy', 'sushi'])
v2_model = V2Model(a=['fancy', 'sushi'])

# V1
print(v1_model.json())
#> {"a": ["fancy", "sushi"]}

# V2
print(v2_model.model_dump_json())
#> {"a":["fancy","sushi"]}

# Plain json.dumps
print(json.dumps(v2_model.model_dump()))
#> {"a": ["fancy", "sushi"]}

# Modified json.dumps
print(json.dumps(v2_model.model_dump(), separators=(',', ':')))
#> {"a":["fancy","sushi"]}

对 `pydantic.generics.GenericModel` 的变更¶

pydantic.generics.GenericModel 类不再是必需的，并已被移除。相反，您现在可以通过直接在 BaseModel 子类上添加 Generic 作为父类来创建泛型 BaseModel 子类。这看起来像 class MyGenericModel(BaseModel, Generic[T]): ...。

不支持 V1 和 V2 模型的混合使用，这意味着此类泛型 BaseModel (V2) 的类型参数不能是 V1 模型。

虽然可能不会引发错误，但我们强烈建议不要在 isinstance 检查中使用*参数化*的泛型。

例如，您不应该执行 isinstance(my_model, MyGenericModel[int])。但是，执行 isinstance(my_model, MyGenericModel) 是可以的。（请注意，对于标准泛型，使用参数化泛型进行子类检查会引发错误。）
如果您需要对参数化泛型执行 isinstance 检查，您可以通过子类化参数化泛型类来实现。这看起来像 class MyIntModel(MyGenericModel[int]): ... 和 isinstance(my_model, MyIntModel)。

在泛型模型文档中查找更多信息。

对 `pydantic.Field` 的变更¶

Field 不再支持将任意关键字参数添加到 JSON schema 中。相反，您想添加到 JSON schema 中的任何额外数据都应作为字典传递给 json_schema_extra 关键字参数。

在 Pydantic V1 中，当未设置别名时，alias 属性返回字段的名称。在 Pydantic V2 中，此行为已更改为在未设置别名时返回 None。

以下属性已从 Field 中移除或更改

const
min_items (请改用 min_length)
max_items (请改用 max_length)
unique_items
allow_mutation (请改用 frozen)
regex (请改用 pattern)
final (请改用 typing.Final 类型提示)

字段约束不再自动向下传递给泛型的参数。例如，您不能再通过提供 my_list: list[str] = Field(pattern=".*") 来验证列表的每个元素是否匹配正则表达式。相反，请使用 typing.Annotated 在 str 本身上提供注解：my_list: list[Annotated[str, Field(pattern=".*")]]

对 dataclasses 的变更¶

Pydantic dataclasses 仍然对于在标准 dataclasses 上启用数据验证而无需子类化 BaseModel 很有用。Pydantic V2 对此 dataclass 行为引入了以下变更

当用作字段时，dataclasses（Pydantic 或原生的）不再接受元组作为验证输入；应改用字典。
Pydantic dataclasses 中的 __post_init__ 现在将在验证*之后*调用，而不是之前。
- 因此，__post_init_post_parse__ 方法将变得多余，因此已被移除。
Pydantic 不再支持 Pydantic dataclasses 的 extra='allow'，即传递给初始化器的额外字段将作为额外属性存储在 dataclass 上。extra='ignore' 仍然支持，用于在解析数据时忽略意外字段，只是它们不会存储在实例上。
Pydantic dataclasses 不再有 __pydantic_model__ 属性，也不再使用底层的 BaseModel 来执行验证或提供其他功能。
- 要执行验证、生成 JSON schema 或利用任何其他可能在 V1 中需要 __pydantic_model__ 的功能，您现在应该用 TypeAdapter（下文将详细讨论）包装 dataclass，并利用其方法。
在 Pydantic V1 中，如果您使用一个原生的（即非 Pydantic 的）dataclass 作为字段，父类型的配置将被用作 dataclass 本身的配置。在 Pydantic V2 中，情况不再如此。
- 在 Pydantic V2 中，要覆盖配置（就像您在 BaseModel 上使用 model_config 一样），您可以在 @dataclass 装饰器上使用 config 参数。有关示例，请参阅Dataclass 配置。

对配置 (config) 的变更¶

在 Pydantic V2 中，要在模型上指定配置，您应该将一个名为 model_config 的类属性设置为一个字典，其中包含您希望用作配置的键/值对。Pydantic V1 中在父 BaseModel 子类的命名空间中创建一个名为 Config 的类的行为现已弃用。
当子类化一个模型时，model_config 属性会被继承。这在您希望为许多模型使用具有给定配置的基类时很有用。请注意，如果您从多个 BaseModel 子类继承，例如 class MyModel(Model1, Model2)，来自这两个模型的 model_config 属性中的非默认设置将被合并，对于任何在两者中都定义的设置，来自 Model2 的设置将覆盖来自 Model1 的设置。
以下配置设置已被移除
- allow_mutation — 已被移除。您应该可以使用 frozen 等效地实现（与当前用法相反）。
- error_msg_templates
- fields — 这是各种错误的来源，因此已被移除。您应该可以在字段上使用 Annotated 来按需修改它们。
- getter_dict — orm_mode 已被移除，这个实现细节不再需要。
- smart_union - Pydantic V2 中的默认 union_mode 是 'smart'。
- underscore_attrs_are_private — Pydantic V2 的行为现在与 Pydantic V1 中始终将此设置为 True 时的行为相同。
- json_loads
- json_dumps
- copy_on_model_validation
- post_init_call
以下配置设置已重命名
- allow_population_by_field_name → populate_by_name (或从 v2.11 开始的 validate_by_name)
- anystr_lower → str_to_lower
- anystr_strip_whitespace → str_strip_whitespace
- anystr_upper → str_to_upper
- keep_untouched → ignored_types
- max_anystr_length → str_max_length
- min_anystr_length → str_min_length
- orm_mode → from_attributes
- schema_extra → json_schema_extra
- validate_all → validate_default

有关更多详细信息，请参阅 ConfigDict API 参考。

对验证器 (validators) 的变更¶

`@validator` 和 `@root_validator` 已被弃用¶

@validator 已被弃用，应替换为 @field_validator，后者提供了各种新功能和改进。
- 新的 @field_validator 装饰器没有 each_item 关键字参数；您希望应用于泛型容器内项目的验证器应通过注解类型参数来添加。有关详细信息，请参阅Annotated 元数据中的验证器。这看起来像 list[Annotated[int, Field(ge=0)]]
- 即使您继续使用已弃用的 @validator 装饰器，您也不能再向验证器函数的签名中添加 field 或 config 参数。如果您需要访问这些参数，您需要迁移到 @field_validator — 有关更多详细信息，请参阅下一节。
- 如果您对验证器函数使用 always=True 关键字参数，请注意，即使对于默认值，注解类型的标准验证器也*将*被应用，而不仅仅是自定义验证器。例如，尽管下面的验证器永远不会出错，但以下代码会引发 ValidationError

注意

为避免这种情况，您可以在 Field 函数中使用 validate_default 参数。当设置为 True 时，它模仿了 Pydantic v1 中 always=True 的行为。但是，鼓励使用新的 validate_default 方式，因为它提供了更大的灵活性和控制力。

from pydantic import BaseModel, validator


class Model(BaseModel):
    x: str = 1

    @validator('x', always=True)
    @classmethod
    def validate_x(cls, v):
        return v


Model()

@root_validator 已被弃用，应替换为 @model_validator，后者也提供了新功能和改进。
- 在某些情况下（例如当 model_config['validate_assignment'] is True 时进行赋值），@model_validator 装饰器将接收一个模型实例，而不是一个值字典。您可能需要小心处理这种情况。
- 即使您继续使用已弃用的 @root_validator 装饰器，由于验证逻辑的重构，您不能再以 skip_on_failure=False 运行（这是此关键字参数的默认值，因此必须明确设置为 True）。

对 `@validator` 允许的签名的变更¶

在 Pydantic V1 中，由 @validator 包装的函数可以接收包含有关正在验证内容的元数据的关键字参数。其中一些参数已从 Pydantic V2 的 @field_validator 中移除

config: Pydantic V2 的配置现在是一个字典而不是一个类，这意味着此参数不再向后兼容。如果您需要访问配置，您应该迁移到 @field_validator 并使用 info.config。
field: 这个参数曾经是一个 ModelField 对象，这是一个在 Pydantic V2 中不再存在的准内部类。大部分信息仍然可以通过使用来自 info.field_name 的字段名来索引 cls.model_fields 来访问

from pydantic import BaseModel, ValidationInfo, field_validator


class Model(BaseModel):
    x: int

    @field_validator('x')
    def val_x(cls, v: int, info: ValidationInfo) -> int:
        assert info.config is not None
        print(info.config.get('title'))
        #> Model
        print(cls.model_fields[info.field_name].is_required())
        #> True
        return v


Model(x=1)

在验证器中，`TypeError` 不再被转换为 `ValidationError`¶

以前，在验证器函数中引发 TypeError 时，该错误将被包装成 ValidationError，并且在某些情况下（例如在 FastAPI 中），这些错误可能会显示给最终用户。这导致了各种不希望出现的行为 — 例如，使用错误的签名调用函数可能会产生面向用户的 ValidationError。

然而，在 Pydantic V2 中，当在验证器中引发 TypeError 时，它不再被转换为 ValidationError

import pytest

from pydantic import BaseModel, field_validator


class Model(BaseModel):
    x: int

    @field_validator('x')
    def val_x(cls, v: int) -> int:
        return str.lower(v)  # raises a TypeError


with pytest.raises(TypeError):
    Model(x=1)

这适用于所有验证装饰器。

验证器行为的变更¶

Pydantic V2 包含一些对类型强制转换的变更。例如

将 int、float 和 Decimal 值强制转换为字符串现在是可选的，并且默认禁用，请参阅将数字强制转换为字符串。
由键值对组成的可迭代对象不再被强制转换为字典。

有关 Pydantic V2 类型强制转换默认值的详细信息，请参阅转换表。

不再需要 `allow_reuse` 关键字参数¶

以前，Pydantic 会跟踪装饰器中“重用”的函数，因为这是一个常见的错误来源。我们通过比较函数的完全限定名称（模块名 + 函数名）来做到这一点，这可能导致误报。当这是有意为之时，可以使用 allow_reuse 关键字参数来禁用此功能。

我们检测重复定义函数的方法已经彻底改革，现在只在单个类中重复定义时才会出错，从而减少了误报，并使行为更符合类型检查器和 linter 在单个类定义中多次定义同名方法时会给出的错误。

在几乎所有情况下，如果您之前使用了 allow_reuse=True，您应该能够简单地删除该关键字参数，并且一切都能正常工作。

`@validate_arguments` 已重命名为 `@validate_call`¶

在 Pydantic V2 中，@validate_arguments 装饰器已重命名为 @validate_call。

在 Pydantic V1 中，被装饰的函数会添加各种属性，例如 raw_function 和 validate（可用于验证参数而不实际调用被装饰的函数）。由于这些属性的使用有限，以及以性能为导向的实现变化，我们没有在 @validate_call 中保留此功能。

输入类型不被保留¶

在 Pydantic V1 中，我们尽力保留所有泛型集合的字段输入的类型，当它们是字段注解的适当子类型时。例如，给定注解 Mapping[str, int]，如果您传入一个 collection.Counter()，您将得到一个 collection.Counter() 作为值。

在 V2 中支持此行为将对一般情况产生负面的性能影响（我们必须每次都检查类型），并且会给验证增加很多复杂性。此外，即使在 V1 中，这种行为也是不一致且部分损坏的：它对许多类型（str、UUID 等）不起作用，并且对于泛型集合，如果不进行大量特殊处理，就不可能正确地重新构建原始输入（考虑 ChainMap；重新构建输入是必要的，因为我们需要在验证后替换值，例如，如果将字符串强制转换为整数）。

在 Pydantic V2 中，我们不再尝试在所有情况下都保留输入类型；相反，我们只承诺输出类型将与类型注解匹配。

回到 Mapping 的例子，我们承诺输出将是一个有效的 Mapping，实际上它将是一个普通的 dict

from collections.abc import Mapping

from pydantic import TypeAdapter


class MyDict(dict):
    pass


ta = TypeAdapter(Mapping[str, int])
v = ta.validate_python(MyDict())
print(type(v))
#> <class 'dict'>

如果您希望输出类型是特定类型，请考虑将其注解为该类型或实现自定义验证器

from collections.abc import Mapping
from typing import Annotated, Any, TypeVar

from pydantic import (
    TypeAdapter,
    ValidationInfo,
    ValidatorFunctionWrapHandler,
    WrapValidator,
)


def restore_input_type(
    value: Any, handler: ValidatorFunctionWrapHandler, _info: ValidationInfo
) -> Any:
    return type(value)(handler(value))


T = TypeVar('T')
PreserveType = Annotated[T, WrapValidator(restore_input_type)]


ta = TypeAdapter(PreserveType[Mapping[str, int]])


class MyDict(dict):
    pass


v = ta.validate_python(MyDict())
assert type(v) is MyDict

虽然我们不承诺在所有地方都保留输入类型，但我们*确实*为 BaseModel 的子类和 dataclasses 保留它们

import pydantic.dataclasses
from pydantic import BaseModel


class InnerModel(BaseModel):
    x: int


class OuterModel(BaseModel):
    inner: InnerModel


class SubInnerModel(InnerModel):
    y: int


m = OuterModel(inner=SubInnerModel(x=1, y=2))
print(m)
#> inner=SubInnerModel(x=1, y=2)


@pydantic.dataclasses.dataclass
class InnerDataclass:
    x: int


@pydantic.dataclasses.dataclass
class SubInnerDataclass(InnerDataclass):
    y: int


@pydantic.dataclasses.dataclass
class OuterDataclass:
    inner: InnerDataclass


d = OuterDataclass(inner=SubInnerDataclass(x=1, y=2))
print(d)
#> OuterDataclass(inner=SubInnerDataclass(x=1, y=2))

对标准类型处理的变更¶

字典 (Dicts)¶

由键值对组成的可迭代对象（包括空的可迭代对象）不再能通过 dict 类型字段的验证。

联合类型 (Unions)¶

虽然联合类型仍会尝试从左到右验证每个选项，但它们现在会尽可能保留输入的类型，即使正确的类型不是输入能通过验证的第一个选项。为了演示，请考虑以下示例

Python 3.9 及以上版本Python 3.10 及以上版本

from typing import Union

from pydantic import BaseModel


class Model(BaseModel):
    x: Union[int, str]


print(Model(x='1'))
#> x='1'

from pydantic import BaseModel


class Model(BaseModel):
    x: int | str


print(Model(x='1'))
#> x='1'

在 Pydantic V1 中，打印的结果将是 x=1，因为该值将作为 int 通过验证。在 Pydantic V2 中，我们识别出该值是其中一种情况的实例，并短路了标准的联合验证。

要恢复到 V1 的非短路从左到右的行为，请使用 Field(union_mode='left_to_right') 注解联合类型。有关更多详细信息，请参阅联合模式。

必需、可选和可为空的字段¶

Pydantic V2 更改了一些用于指定注解为 Optional 的字段是否是必需的（即没有默认值）或非必需的（即具有 None 或相应类型的任何其他值的默认值）的逻辑，并且现在更接近于 dataclasses 的行为。类似地，注解为 Any 的字段不再具有 None 的默认值。

下表描述了 V2 中字段注解的行为

状态	字段定义
必需，不能为 `None`	`f1: str`
非必需，不能为 `None`，默认为 `'abc'`	`f2: str = 'abc'`
必需，可以为 `None`	`f3: Optional[str]`
非必需，可以为 `None`，默认为 `None`	`f4: Optional[str] = None`
非必需，可以为 `None`，默认为 `'abc'`	`f5: Optional[str] = 'abc'`
必需，可以是任何类型（包括 `None`）	`f6: Any`
非必需，可以是任何类型（包括 `None`）	`f7: Any = None`

注意

注解为 typing.Optional[T] 的字段将是必需的，并允许值为 None。它并不意味着该字段具有 None 的默认值。（这是与 V1 的一个破坏性变更。）

注意

如果提供了任何默认值，则该字段变为非必需。

以下是演示上述内容的代码示例

Python 3.9 及以上版本Python 3.10 及以上版本

from typing import Optional

from pydantic import BaseModel, ValidationError


class Foo(BaseModel):
    f1: str  # required, cannot be None
    f2: Optional[str]  # required, can be None - same as str | None
    f3: Optional[str] = None  # not required, can be None
    f4: str = 'Foobar'  # not required, but cannot be None


try:
    Foo(f1=None, f2=None, f4='b')
except ValidationError as e:
    print(e)
    """
    1 validation error for Foo
    f1
      Input should be a valid string [type=string_type, input_value=None, input_type=NoneType]
    """

from pydantic import BaseModel, ValidationError


class Foo(BaseModel):
    f1: str  # required, cannot be None
    f2: str | None  # required, can be None - same as str | None
    f3: str | None = None  # not required, can be None
    f4: str = 'Foobar'  # not required, but cannot be None


try:
    Foo(f1=None, f2=None, f4='b')
except ValidationError as e:
    print(e)
    """
    1 validation error for Foo
    f1
      Input should be a valid string [type=string_type, input_value=None, input_type=NoneType]
    """

字符串的模式/正则表达式¶

Pydantic V1 使用 Python 的 regex 库。Pydantic V2 使用 Rust 的 regex crate。这个 crate 不仅仅是“Rust 版本的正则表达式”，它是一种完全不同的正则表达式方法。特别是，它承诺以线性时间搜索字符串，以换取放弃一些功能（即环视和反向引用）。我们认为这是一个值得做的权衡，特别是因为 Pydantic 用于验证不受信任的输入，在这种情况下，确保事情不会因不受信任的输入而意外地以指数时间运行是很重要的。另一方面，对于任何不使用这些功能的人来说，复杂的正则表达式验证应该快几个数量级，因为它是在 Rust 中以线性时间完成的。

如果您仍想使用 Python 的 regex 库，可以使用 regex_engine 配置设置。

从浮点数到整数的类型转换¶

在 V1 中，每当字段被注解为 int 时，任何浮点数值都会被接受，如果浮点数值包含非零的小数部分，这可能导致数据丢失。在 V2 中，只有当小数部分为零时，才允许从浮点数到整数的类型转换

from pydantic import BaseModel, ValidationError


class Model(BaseModel):
    x: int


print(Model(x=10.0))
#> x=10
try:
    Model(x=10.2)
except ValidationError as err:
    print(err)
    """
    1 validation error for Model
    x
      Input should be a valid integer, got a number with a fractional part [type=int_from_float, input_value=10.2, input_type=float]
    """

`TypeAdapter` 的引入¶

Pydantic V1 对验证或序列化非 BaseModel 类型的支持较弱。

要处理它们，您必须要么创建一个“根”模型，要么使用 pydantic.tools 中的实用函数（即 parse_obj_as 和 schema_of）。

在 Pydantic V2 中，这要容易*得多*：TypeAdapter 类让您创建一个对象，该对象具有用于验证、序列化和为任意类型生成 JSON schema 的方法。这完全替代了 parse_obj_as 和 schema_of（它们现在已被弃用），并且还涵盖了“根”模型的一些用例。（RootModel，上文已讨论，涵盖了其他用例。）

from pydantic import TypeAdapter

adapter = TypeAdapter(list[int])
assert adapter.validate_python(['1', '2', '3']) == [1, 2, 3]
print(adapter.json_schema())
#> {'items': {'type': 'integer'}, 'type': 'array'}

由于常用类型检查器在推断泛型类型方面存在局限性，要在某些场景中获得正确的类型提示，您可能需要显式指定泛型参数

from pydantic import TypeAdapter

adapter = TypeAdapter[str | int](str | int)
...

更多信息请参阅类型适配器。

定义自定义类型¶

我们已经完全 overhaul 了在 pydantic 中定义自定义类型的方式。

我们暴露了用于生成 pydantic-core 和 JSON schema 的钩子，即使在使用您自己的自定义类型时，也能让您获得 Pydantic V2 的所有性能优势。

我们还引入了使用 typing.Annotated 为您自己的类型添加自定义验证的方法。

主要变更是

__get_validators__ 应替换为 __get_pydantic_core_schema__。更多信息请参阅自定义数据类型。
__modify_schema__ 变为 __get_pydantic_json_schema__。更多信息请参阅JSON Schema 自定义。

此外，您可以使用 typing.Annotated 来修改或提供一个类型的 __get_pydantic_core_schema__ 和 __get_pydantic_json_schema__ 函数，通过对其进行注解，而不是修改类型本身。这为将第三方类型与 Pydantic 集成提供了一个强大而灵活的机制，并且在某些情况下可以帮助您移除 Pydantic V1 中为绕过自定义类型限制而引入的 hack。

更多信息请参阅自定义数据类型。

对 JSON schema 生成的变更¶

多年来，我们收到了许多关于更改 pydantic 生成的 JSON schema 的请求。

在 Pydantic V2 中，我们试图解决许多常见的请求

Optional 字段的 JSON schema 现在会指明允许 null 值。
Decimal 类型现在在 JSON schema 中（以及序列化时）作为字符串公开。
JSON schema 不再将 namedtuples 保留为 namedtuples。
我们默认生成的 JSON schema 现在以 draft 2020-12 为目标（带有一些 OpenAPI 扩展）。
当它们不同时，您现在可以指定您想要表示验证输入的 JSON schema，还是序列化输出的 JSON schema。

然而，多年来有许多合理的变更请求我们没有选择实施。

在 Pydantic V1 中，即使您愿意自己实施变更，也非常困难，因为 JSON schema 生成过程涉及各种递归函数调用；要覆盖一个，您必须复制并修改整个实现。

在 Pydantic V2 中，我们的设计目标之一是使自定义 JSON schema 生成更容易。为此，我们引入了 GenerateJsonSchema 类，它实现了将类型的 pydantic-core schema 转换为 JSON schema 的过程。通过设计，这个类将 JSON schema 生成过程分解为更小的方法，这些方法可以在子类中轻松覆盖，以修改生成 JSON schema 的“全局”方法。

各种可用于生成 JSON schema 的方法（例如 BaseModel.model_json_schema 或 TypeAdapter.json_schema）都接受一个关键字参数 schema_generator: type[GenerateJsonSchema] = GenerateJsonSchema，您可以将您的自定义子类传递给这些方法，以使用您自己的方法生成 JSON schema。

希望这意味着，如果您不同意我们做出的任何选择，或者您依赖于 Pydantic V1 中已在 Pydantic V2 中更改的行为，您可以使用自定义的 schema_generator，根据您的应用程序需要修改 GenerateJsonSchema 类。

`BaseSettings` 已移至 `pydantic-settings`¶

BaseSettings，用于 Pydantic 设置管理的基础对象，已移至一个独立的包 pydantic-settings。

此外，parse_env_var 类方法已被移除。因此，您需要自定义设置来源来拥有您自己的解析函数。

Color 和 Payment Card Numbers 已移至 `pydantic-extra-types`¶

以下特殊用途的类型已移至 Pydantic Extra Types 包，如果需要，可以单独安装。

`pydantic.networks` 中的 Url 和 Dsn 类型不再继承自 `str`¶

在 Pydantic V1 中，AnyUrl 类型继承自 str，所有其他的 Url 和 Dsn 类型都继承自这些。在 Pydantic V2 中，这些类型是基于两个新的 Url 和 MultiHostUrl 类使用 Annotated 构建的。

继承自 str 有其优缺点，对于 V2，我们决定最好移除这一点。要在期望 str 的 API 中使用这些类型，您现在需要转换它们（使用 str(url)）。

Pydantic V2 使用 Rust 的 Url crate 进行 URL 验证。一些 URL 验证与 V1 中的先前行为略有不同。一个显著的区别是，新的 Url 类型会在验证后的版本中追加斜杠，如果没有包含路径，即使在 Url 类型构造函数的参数中没有指定斜杠。请参阅下面的示例了解此行为

from pydantic import AnyUrl

assert str(AnyUrl(url='https://google.com')) == 'https://google.com/'
assert str(AnyUrl(url='https://google.com/')) == 'https://google.com/'
assert str(AnyUrl(url='https://google.com/api')) == 'https://google.com/api'
assert str(AnyUrl(url='https://google.com/api/')) == 'https://google.com/api/'

如果您仍想使用不带附加斜杠的旧行为，请查看这个解决方案。

约束类型¶

Constrained* 类被*移除*了，您应该用 Annotated[<type>, Field(...)] 替换它们，例如

from pydantic import BaseModel, ConstrainedInt


class MyInt(ConstrainedInt):
    ge = 0


class Model(BaseModel):
    x: MyInt

...变为

from typing import Annotated

from pydantic import BaseModel, Field

MyInt = Annotated[int, Field(ge=0)]


class Model(BaseModel):
    x: MyInt

在通过 Annotated 组合类型文档中阅读更多相关信息。

对于 ConstrainedStr，您可以改用 StringConstraints。

Mypy 插件¶

Pydantic V2 在 pydantic.mypy 中包含一个 mypy 插件。

当使用V1 功能时，可能还需要启用 pydantic.v1.mypy 插件。

配置 mypy 插件

mypy.inipyproject.toml

[mypy]
plugins = pydantic.mypy, pydantic.v1.mypy  # include `.v1.mypy` if required.

[tool.mypy]
plugins = [
    "pydantic.mypy",
    "pydantic.v1.mypy",  # include `.v1.mypy` if required.
]

其他变更¶

放弃了对 email-validator<2.0.0 的支持。请确保使用 pip install -U email-validator进行更新。

在 Pydantic V2 中移动的¶

Pydantic V1	Pydantic V2
`pydantic.BaseSettings`	`pydantic_settings.BaseSettings`
`pydantic.color`	`pydantic_extra_types.color`
`pydantic.types.PaymentCardBrand`	`pydantic_extra_types.PaymentCardBrand`
`pydantic.types.PaymentCardNumber`	`pydantic_extra_types.PaymentCardNumber`
`pydantic.utils.version_info`	`pydantic.version.version_info`
`pydantic.error_wrappers.ValidationError`	`pydantic.ValidationError`
`pydantic.utils.to_camel`	`pydantic.alias_generators.to_pascal`
`pydantic.utils.to_lower_camel`	`pydantic.alias_generators.to_camel`
`pydantic.PyObject`	`pydantic.ImportString`

在 Pydantic V2 中弃用并移动的¶

Pydantic V1	Pydantic V2
`pydantic.tools.schema_of`	`pydantic.deprecated.tools.schema_of`
`pydantic.tools.parse_obj_as`	`pydantic.deprecated.tools.parse_obj_as`
`pydantic.tools.schema_json_of`	`pydantic.deprecated.tools.schema_json_of`
`pydantic.json.pydantic_encoder`	`pydantic.deprecated.json.pydantic_encoder`
`pydantic.validate_arguments`	`pydantic.deprecated.decorator.validate_arguments`
`pydantic.json.custom_pydantic_encoder`	`pydantic.deprecated.json.custom_pydantic_encoder`
`pydantic.json.ENCODERS_BY_TYPE`	`pydantic.deprecated.json.ENCODERS_BY_TYPE`
`pydantic.json.timedelta_isoformat`	`pydantic.deprecated.json.timedelta_isoformat`
`pydantic.decorator.validate_arguments`	`pydantic.deprecated.decorator.validate_arguments`
`pydantic.class_validators.validator`	`pydantic.deprecated.class_validators.validator`
`pydantic.class_validators.root_validator`	`pydantic.deprecated.class_validators.root_validator`
`pydantic.utils.deep_update`	`pydantic.v1.utils.deep_update`
`pydantic.utils.GetterDict`	`pydantic.v1.utils.GetterDict`
`pydantic.utils.lenient_issubclass`	`pydantic.v1.utils.lenient_issubclass`
`pydantic.utils.lenient_isinstance`	`pydantic.v1.utils.lenient_isinstance`
`pydantic.utils.is_valid_field`	`pydantic.v1.utils.is_valid_field`
`pydantic.utils.update_not_none`	`pydantic.v1.utils.update_not_none`
`pydantic.utils.import_string`	`pydantic.v1.utils.import_string`
`pydantic.utils.Representation`	`pydantic.v1.utils.Representation`
`pydantic.utils.ROOT_KEY`	`pydantic.v1.utils.ROOT_KEY`
`pydantic.utils.smart_deepcopy`	`pydantic.v1.utils.smart_deepcopy`
`pydantic.utils.sequence_like`	`pydantic.v1.utils.sequence_like`

在 Pydantic V2 中移除的¶

pydantic.ConstrainedBytes
pydantic.ConstrainedDate
pydantic.ConstrainedDecimal
pydantic.ConstrainedFloat
pydantic.ConstrainedFrozenSet
pydantic.ConstrainedInt
pydantic.ConstrainedList
pydantic.ConstrainedSet
pydantic.ConstrainedStr
pydantic.JsonWrapper
pydantic.NoneBytes
- 这是 None | bytes 的别名。
pydantic.NoneStr
- 这是 None | str 的别名。
pydantic.NoneStrBytes
- 这是 None | str | bytes 的别名。
pydantic.Protocol
pydantic.Required
pydantic.StrBytes
- 这是 str | bytes 的别名。
pydantic.compiled
pydantic.config.get_config
pydantic.config.inherit_config
pydantic.config.prepare_config
pydantic.create_model_from_namedtuple
pydantic.create_model_from_typeddict
pydantic.dataclasses.create_pydantic_model_from_dataclass
pydantic.dataclasses.make_dataclass_validator
pydantic.dataclasses.set_validation
pydantic.datetime_parse.parse_date
pydantic.datetime_parse.parse_time
pydantic.datetime_parse.parse_datetime
pydantic.datetime_parse.parse_duration
pydantic.error_wrappers.ErrorWrapper
pydantic.errors.AnyStrMaxLengthError
pydantic.errors.AnyStrMinLengthError
pydantic.errors.ArbitraryTypeError
pydantic.errors.BoolError
pydantic.errors.BytesError
pydantic.errors.CallableError
pydantic.errors.ClassError
pydantic.errors.ColorError
pydantic.errors.ConfigError
pydantic.errors.DataclassTypeError
pydantic.errors.DateError
pydantic.errors.DateNotInTheFutureError
pydantic.errors.DateNotInThePastError
pydantic.errors.DateTimeError
pydantic.errors.DecimalError
pydantic.errors.DecimalIsNotFiniteError
pydantic.errors.DecimalMaxDigitsError
pydantic.errors.DecimalMaxPlacesError
pydantic.errors.DecimalWholeDigitsError
pydantic.errors.DictError
pydantic.errors.DurationError
pydantic.errors.EmailError
pydantic.errors.EnumError
pydantic.errors.EnumMemberError
pydantic.errors.ExtraError
pydantic.errors.FloatError
pydantic.errors.FrozenSetError
pydantic.errors.FrozenSetMaxLengthError
pydantic.errors.FrozenSetMinLengthError
pydantic.errors.HashableError
pydantic.errors.IPv4AddressError
pydantic.errors.IPv4InterfaceError
pydantic.errors.IPv4NetworkError
pydantic.errors.IPv6AddressError
pydantic.errors.IPv6InterfaceError
pydantic.errors.IPv6NetworkError
pydantic.errors.IPvAnyAddressError
pydantic.errors.IPvAnyInterfaceError
pydantic.errors.IPvAnyNetworkError
pydantic.errors.IntEnumError
pydantic.errors.IntegerError
pydantic.errors.InvalidByteSize
pydantic.errors.InvalidByteSizeUnit
pydantic.errors.InvalidDiscriminator
pydantic.errors.InvalidLengthForBrand
pydantic.errors.JsonError
pydantic.errors.JsonTypeError
pydantic.errors.ListError
pydantic.errors.ListMaxLengthError
pydantic.errors.ListMinLengthError
pydantic.errors.ListUniqueItemsError
pydantic.errors.LuhnValidationError
pydantic.errors.MissingDiscriminator
pydantic.errors.MissingError
pydantic.errors.NoneIsAllowedError
pydantic.errors.NoneIsNotAllowedError
pydantic.errors.NotDigitError
pydantic.errors.NotNoneError
pydantic.errors.NumberNotGeError
pydantic.errors.NumberNotGtError
pydantic.errors.NumberNotLeError
pydantic.errors.NumberNotLtError
pydantic.errors.NumberNotMultipleError
pydantic.errors.PathError
pydantic.errors.PathNotADirectoryError
pydantic.errors.PathNotAFileError
pydantic.errors.PathNotExistsError
pydantic.errors.PatternError
pydantic.errors.PyObjectError
pydantic.errors.PydanticTypeError
pydantic.errors.PydanticValueError
pydantic.errors.SequenceError
pydantic.errors.SetError
pydantic.errors.SetMaxLengthError
pydantic.errors.SetMinLengthError
pydantic.errors.StrError
pydantic.errors.StrRegexError
pydantic.errors.StrictBoolError
pydantic.errors.SubclassError
pydantic.errors.TimeError
pydantic.errors.TupleError
pydantic.errors.TupleLengthError
pydantic.errors.UUIDError
pydantic.errors.UUIDVersionError
pydantic.errors.UrlError
pydantic.errors.UrlExtraError
pydantic.errors.UrlHostError
pydantic.errors.UrlHostTldError
pydantic.errors.UrlPortError
pydantic.errors.UrlSchemeError
pydantic.errors.UrlSchemePermittedError
pydantic.errors.UrlUserInfoError
pydantic.errors.WrongConstantError
pydantic.main.validate_model
pydantic.networks.stricturl
pydantic.parse_file_as
pydantic.parse_raw_as
pydantic.stricturl
pydantic.tools.parse_file_as
pydantic.tools.parse_raw_as
pydantic.types.JsonWrapper
pydantic.types.NoneBytes
pydantic.types.NoneStr
pydantic.types.NoneStrBytes
pydantic.types.PyObject
pydantic.types.StrBytes
pydantic.typing.evaluate_forwardref
pydantic.typing.AbstractSetIntStr
pydantic.typing.AnyCallable
pydantic.typing.AnyClassMethod
pydantic.typing.CallableGenerator
pydantic.typing.DictAny
pydantic.typing.DictIntStrAny
pydantic.typing.DictStrAny
pydantic.typing.IntStr
pydantic.typing.ListStr
pydantic.typing.MappingIntStrAny
pydantic.typing.NoArgAnyCallable
pydantic.typing.NoneType
pydantic.typing.ReprArgs
pydantic.typing.SetStr
pydantic.typing.StrPath
pydantic.typing.TupleGenerator
pydantic.typing.WithArgsTypes
pydantic.typing.all_literal_values
pydantic.typing.display_as_type
pydantic.typing.get_all_type_hints
pydantic.typing.get_args
pydantic.typing.get_origin
pydantic.typing.get_sub_types
pydantic.typing.is_callable_type
pydantic.typing.is_classvar
pydantic.typing.is_finalvar
pydantic.typing.is_literal_type
pydantic.typing.is_namedtuple
pydantic.typing.is_new_type
pydantic.typing.is_none_type
pydantic.typing.is_typeddict
pydantic.typing.is_typeddict_special
pydantic.typing.is_union
pydantic.typing.new_type_supertype
pydantic.typing.resolve_annotations
pydantic.typing.typing_base
pydantic.typing.update_field_forward_refs
pydantic.typing.update_model_forward_refs
pydantic.utils.ClassAttribute
pydantic.utils.DUNDER_ATTRIBUTES
pydantic.utils.PyObjectStr
pydantic.utils.ValueItems
pydantic.utils.almost_equal_floats
pydantic.utils.get_discriminator_alias_and_values
pydantic.utils.get_model
pydantic.utils.get_unique_discriminator_alias
pydantic.utils.in_ipython
pydantic.utils.is_valid_identifier
pydantic.utils.path_type
pydantic.utils.validate_field_name
pydantic.validate_model