pydantic-compat

动机

Pydantic 2是一个重大版本，完全改变了pydantic API。

对于应用程序来说，这并不是什么大问题，因为它们可以将pydantic版本锁定在所需版本。但对于希望在更广泛环境中存在的库来说，将pydantic锁定在特定版本并不是总是可行的（因为它限制了与其他库共存的能力）。

此软件包提供（非官方）的pydantic v1-v2跨版本兼容性混合和函数适配器。它允许您使用v1或v2 API名称，而不管安装的pydantic版本如何。（如果可能，请首选使用v2名称）。

测试在Pydantic v1.8及以上版本上运行

API转换并非详尽无遗，但对于我遇到的大多数用例来说已经足够。它被以下库使用

• ome-types
• psygnal
• app-model
• useq-schema

如果您觉得它有用，但缺少您需要的功能，请随时打开一个问题或PR。

它做什么？

并不多！:joy

它主要服务于将一个API的名称翻译为另一个API。它将v2 API回退到v1（因此您可以在pydantic1运行时使用v2名称），并将v1 API转发到v2（因此您可以在v2运行时使用v1名称而不会收到弃用警告）。

虽然pydantic2提供对v1 API的弃用访问，但如果您希望在不让用户看到弃用警告的情况下显式支持pydantic1，那么您需要根据运行时pydantic版本进行大量的名称适配。这个包为您完成这些工作。

它不会进行任何显著复杂的API逻辑转换。对于自定义类型，您可能仍然需要添加类方法以支持pydantic的两个版本。

它也不会阻止您了解pydantic 2底层的更改。您应该在两个版本的pydantic上运行测试，以确保您的库按预期工作。这个库只是使您在单个代码库中支持两个版本变得更加容易，而不需要很多丑陋的条件和样板代码。

用法

from pydantic import BaseModel
from pydantic_compat import PydanticCompatMixin
from pydantic_compat import field_validator  # or 'validator'
from pydantic_compat import model_validator  # or 'root_validator'

class MyModel(PydanticCompatMixin, BaseModel):
    x: int
    y: int = 2

    # prefer v2 dict, but v1 class Config is supported
    model_config = {'frozen': True}

    @field_validator('x', mode='after')
    def _check_x(cls, v):
        if v != 42:
            raise ValueError("That's not the answer!")
        return v

    @model_validator('x', mode='after')
    def _check_x(cls, v: MyModel):
        # ...
        return v

现在，无论安装了哪个版本的pydantic，您都可以使用以下属性和方法（不会显示弃用警告）

Field说明

• pydantic_compat.Field将删除过时的字段（const）并翻译新名称的字段

  v1名称	v2名称
  min_items	min_length
  max_items	max_length
  regex	pattern
  allow_mutation	not frozen
  metadata	json_schema_extra

• 不要使用var = Field(..., const='val')，请使用var: Literal['val'] = 'val'，这在v1和v2中都有效
• 没有尝试在v1的unique_items和v2的Set[]语义之间进行转换。有关讨论，请参阅https://github.com/pydantic/pydantic-core/issues/296。

API规则

• 可以同时使用V1和V2的名称（无论pydantic版本），但强烈建议使用V2的名称。
• 但API必须与您使用的名称匹配的pydantic版本相匹配。例如，如果您使用pydantic_compat.field_validator，则签名必须匹配pydantic（v2）的field_validator签名（无论安装了哪个版本的pydantic）。同样，如果您选择使用pydantic_compat.validator，则签名必须匹配pydantic（v1）的validator签名。

显著差异

• 在v1中，BaseModel.__fields__是一个字典，格式为{'field_name' -> ModelField}，而在v2中，BaseModel.model_fields是一个字典，格式为{'field_name' -> FieldInfo}。FieldInfo是一个比ModelField更简单的对象，因此难以直接支持复杂的v1对__fields__的使用。pydantic-compat提供了一个名称适配器，允许您在v2环境中访问您可能在v1中对ModelField进行访问的许多属性，但不会提供ModelField的方法。您需要相应地更新您的使用。

• 在v2中，pydantic.model_validator(..., mode='after')将模型实例传递给验证函数，而pydantic.v1.root_validator(..., pre=False)将{'field_name' -> validated_value}的字典传递给验证函数。在pydantic-compat中，这两个装饰器遵循它们对应的pydantic版本的语义，但root_validator增加了一个参数construct_object: bool=False，这与model_validator的行为相匹配（仅当mode=='after'时）。如果您想使用这种行为，则首选直接使用model_validator。

待办事项

• 序列化装饰器