架构

注意

本节是内部原理文档的一部分，部分面向贡献者。

从 Pydantic V2 开始，部分代码库是用 Rust 编写的，放在一个名为 pydantic-core 的独立包中。这样做部分是为了提高验证和序列化性能（代价是限制了内部逻辑的自定义和可扩展性）。

本架构文档将首先介绍 pydantic 和 pydantic-core 这两个包如何协同工作，然后将详细介绍各种模式（模型定义、验证、序列化、JSON Schema）的架构细节。

Pydantic 库的使用可以分为两个部分

模型定义，在 pydantic 包中完成。
模型验证和序列化，在 pydantic-core 包中完成。

模型定义¶

每当定义 Pydantic BaseModel 时，元类将分析模型的主体以收集多个元素

定义的注解，用于构建模型字段（收集在 model_fields 属性中）。
模型配置，使用 model_config 设置。
额外的验证器/序列化器。
私有属性、类变量、泛型参数化的识别等。

`pydantic` 和 `pydantic-core` 之间的通信：核心模式¶

然后我们需要一种方法将从模型定义中收集的信息传递给 pydantic-core，以便相应地执行验证和序列化。为此，Pydantic 使用核心模式的概念：一个结构化的（和可序列化的）Python 字典（使用 TypedDict 定义表示），描述特定的验证和序列化逻辑。它是用于在 pydantic 和 pydantic-core 包之间进行通信的核心数据结构。每个核心模式都有一个必需的 type 键，以及取决于此 type 的额外属性。

核心模式的生成由 GenerateSchema 类在单个位置处理（无论是对于 Pydantic 模型还是其他任何内容）。

注意

无法定义自定义核心模式。核心模式需要被 pydantic-core 包理解，因此我们只支持固定数量的核心模式类型。这也是 GenerateSchema 没有真正公开和适当记录的部分原因。

核心模式定义可以在 pydantic_core.core_schema 模块中找到。

在 Pydantic 模型的情况下，将构造一个核心模式并将其设置为 __pydantic_core_schema__ 属性。

为了说明核心模式的外观，我们将以 bool 核心模式为例

class BoolSchema(TypedDict, total=False):
    type: Required[Literal['bool']]
    strict: bool
    ref: str
    metadata: Any
    serialization: SerSchema

当使用布尔字段定义 Pydantic 模型时

from pydantic import BaseModel, Field


class Model(BaseModel):
    foo: bool = Field(strict=True)

foo 字段的核心模式将如下所示

{
    'type': 'bool',
    'strict': True,
}

如 BoolSchema 定义中所见，序列化逻辑也在核心模式中定义。如果我们为 foo (1) 定义自定义序列化函数，则 serialization 键将如下所示

例如，使用 field_serializer 装饰器

class Model(BaseModel):
    foo: bool = Field(strict=True)

    @field_serializer('foo', mode='plain')
    def serialize_foo(self, value: bool) -> Any:
        ...

{
    'type': 'function-plain',
    'function': <function Model.serialize_foo at 0x111>,
    'is_field_serializer': True,
    'info_arg': False,
    'return_schema': {'type': 'int'},
}

请注意，这也是一个核心模式定义，只是它仅在序列化期间与 pydantic-core 相关。

核心模式涵盖了广泛的范围，并在我们想要在 Python 和 Rust 侧之间进行通信时使用。虽然之前的示例与验证和序列化有关，但理论上它可以用于任何事情：错误管理、额外的元数据等。

JSON Schema 生成¶

您可能已经注意到，之前的序列化核心模式有一个 return_schema 键。这是因为核心模式也用于生成相应的 JSON Schema。

与核心模式的生成方式类似，JSON Schema 的生成由 GenerateJsonSchema 类处理。generate 方法是主要入口点，并被赋予该模型的核心模式。

回到我们的 bool 字段示例，bool_schema 方法将被赋予先前生成的布尔核心模式，并将返回以下 JSON Schema

{
    {"type": "boolean"}
}

自定义核心模式和 JSON Schema¶

使用文档

自定义类型

实现 __get_pydantic_core_schema__

实现 __get_pydantic_json_schema__

虽然 GenerateSchema 和 GenerateJsonSchema 类处理相应模式的创建，但 Pydantic 提供了一种在某些情况下自定义它们的方法，遵循包装器模式。这种自定义是通过 __get_pydantic_core_schema__ 和 __get_pydantic_json_schema__ 方法完成的。

为了理解这种包装器模式，我们将以与 Annotated 一起使用的元数据类为例，其中可以使用 __get_pydantic_core_schema__ 方法

from typing import Annotated, Any

from pydantic_core import CoreSchema

from pydantic import GetCoreSchemaHandler, TypeAdapter


class MyStrict:
    @classmethod
    def __get_pydantic_core_schema__(
        cls, source: Any, handler: GetCoreSchemaHandler
    ) -> CoreSchema:
        schema = handler(source)  # (1)!
        schema['strict'] = True
        return schema


class MyGt:
    @classmethod
    def __get_pydantic_core_schema__(
        cls, source: Any, handler: GetCoreSchemaHandler
    ) -> CoreSchema:
        schema = handler(source)  # (2)!
        schema['gt'] = 1
        return schema


ta = TypeAdapter(Annotated[int, MyStrict(), MyGt()])

MyStrict 是要应用的第一个注解。此时，schema = {'type': 'int'}。
MyGt 是要应用的最后一个注解。此时，schema = {'type': 'int', 'strict': True}。

当 GenerateSchema 类为 Annotated[int, MyStrict(), MyGt()] 构建核心模式时，它将创建一个 GetCoreSchemaHandler 的实例，以便传递给 MyGt.__get_pydantic_core_schema__ 方法。(1)

在我们的 Annotated 模式中，GetCoreSchemaHandler 是以嵌套方式定义的。调用它将递归调用其他 __get_pydantic_core_schema__ 方法，直到到达 int 注解，此时返回一个简单的 {'type': 'int'} 模式。

source 参数取决于核心模式生成模式。在 Annotated 的情况下，source 将是被注解的类型。当在自定义类型上定义方法时，source 将是定义 __get_pydantic_core_schema__ 的实际类。

模型验证和序列化¶

虽然模型定义的作用域限定在类级别（即定义模型时），但模型验证和序列化发生在实例级别。这两个概念都在 pydantic-core 中处理（与 Pydantic V1 相比，性能提高了 5 到 20 倍），通过使用先前构建的核心模式。

pydantic-core 公开了 SchemaValidator 和 SchemaSerializer 类来执行这些任务

from pydantic import BaseModel


class Model(BaseModel):
    foo: int


model = Model.model_validate({'foo': 1})  # (1)!
dumped = model.model_dump()  # (2)!

通过使用 SchemaValidator.validate_python 方法将提供的数据发送到 pydantic-core。 pydantic-core 将验证（遵循模型的核心模式）数据并填充模型的 __dict__ 属性。
通过使用 SchemaSerializer.to_python 方法将 model 实例发送到 pydantic-core。 pydantic-core 将读取实例的 __dict__ 属性并构建适当的结果（同样，遵循模型的核心模式）。

架构