Usage Errors

Pydantic 尝试提供有用的错误信息。以下部分详细介绍了开发人员在使用 Pydantic 时可能遇到的常见错误，以及解决错误条件的建议。

类未完全定义¶

当在 pydantic 验证类型的注解中引用的类型（例如 BaseModel 的子类或 pydantic dataclass）未定义时，会引发此错误：

from typing import ForwardRef

from pydantic import BaseModel, PydanticUserError

UndefinedType = ForwardRef('UndefinedType')


class Foobar(BaseModel):
    a: UndefinedType


try:
    Foobar(a=1)
except PydanticUserError as exc_info:
    assert exc_info.code == 'class-not-fully-defined'

或者当类型在使用后才定义时：

from typing import Optional

from pydantic import BaseModel, PydanticUserError


class Foo(BaseModel):
    a: Optional['Bar'] = None


try:
    # 这不起作用，请查看引发的错误
    foo = Foo(a={'b': {'a': None}})
except PydanticUserError as exc_info:
    assert exc_info.code == 'class-not-fully-defined'


class Bar(BaseModel):
    b: 'Foo'


# 不过，这样可以工作
foo = Foo(a={'b': {'a': None}})

对于 BaseModel 子类，可以通过定义类型然后调用 .model_rebuild() 来修复：

from typing import Optional

from pydantic import BaseModel


class Foo(BaseModel):
    a: Optional['Bar'] = None


class Bar(BaseModel):
    b: 'Foo'


Foo.model_rebuild()

foo = Foo(a={'b': {'a': None}})

在其他情况下，错误消息应指示如何使用适当的类型定义重新构建类。

自定义 JSON Schema¶

__modify_schema__ 方法在 V2 中不再受支持。您应该改用 __get_pydantic_json_schema__ 方法。

__modify_schema__ 过去接收一个表示 JSON schema 的参数。请参见下面的示例：

旧方式

from pydantic import BaseModel, PydanticUserError

try:

    class Model(BaseModel):
        @classmethod
        def __modify_schema__(cls, field_schema):
            field_schema.update(examples=['example'])

except PydanticUserError as exc_info:
    assert exc_info.code == 'custom-json-schema'

新的 __get_pydantic_json_schema__ 方法接收两个参数：第一个是表示为 CoreSchema 的字典，第二个是一个可调用的 handler，它接收一个 CoreSchema 作为参数，并返回一个 JSON schema。请参见下面的示例：

新方式

from typing import Any

from pydantic_core import CoreSchema

from pydantic import BaseModel, GetJsonSchemaHandler


class Model(BaseModel):
    @classmethod
    def __get_pydantic_json_schema__(
        cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
    ) -> dict[str, Any]:
        json_schema = super().__get_pydantic_json_schema__(core_schema, handler)
        json_schema = handler.resolve_ref_schema(json_schema)
        json_schema.update(examples=['example'])
        return json_schema


print(Model.model_json_schema())
"""
{'examples': ['example'], 'properties': {}, 'title': 'Model', 'type': 'object'}
"""

装饰器应用于缺失的字段¶

当您使用无效的字段定义装饰器时，会引发此错误。

from typing import Any

from pydantic import BaseModel, PydanticUserError, field_validator

try:

    class Model(BaseModel):
        a: str

        @field_validator('b')
        def check_b(cls, v: Any):
            return v

except PydanticUserError as exc_info:
    assert exc_info.code == 'decorator-missing-field'

如果您从模型继承并且有意这样做，可以使用 check_fields=False。

from typing import Any

from pydantic import BaseModel, create_model, field_validator


class Model(BaseModel):
    @field_validator('a', check_fields=False)
    def check_a(cls, v: Any):
        return v


model = create_model('FooModel', a=(str, 'cake'), __base__=Model)