使用错误

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:
    # this doesn't work, see raised error
    foo = Foo(a={'b': {'a': None}})
except PydanticUserError as exc_info:
    assert exc_info.code == 'class-not-fully-defined'


class Bar(BaseModel):
    b: 'Foo'


# this works, though
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 模式¶

V2 版本中不再支持 __modify_schema__ 方法。你应该改用 __get_pydantic_json_schema__ 方法。

__modify_schema__ 过去接收一个代表 JSON 模式的参数。参见以下示例：

Old way

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 模式。参见以下示例：

New way

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 cls, v: Any):
        return v


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