字段

在模型上定义字段。

Field ¶

Field(
    default: ellipsis,
    *,
    alias: str | None = _Unset,
    alias_priority: int | None = _Unset,
    validation_alias: (
        str | AliasPath | AliasChoices | None
    ) = _Unset,
    serialization_alias: str | None = _Unset,
    title: str | None = _Unset,
    field_title_generator: (
        Callable[[str, FieldInfo], str] | None
    ) = _Unset,
    description: str | None = _Unset,
    examples: list[Any] | None = _Unset,
    exclude: bool | None = _Unset,
    discriminator: str | Discriminator | None = _Unset,
    deprecated: Deprecated | str | bool | None = _Unset,
    json_schema_extra: (
        JsonDict | Callable[[JsonDict], None] | None
    ) = _Unset,
    frozen: bool | None = _Unset,
    validate_default: bool | None = _Unset,
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | Pattern[str] | None = _Unset,
    strict: bool | None = _Unset,
    coerce_numbers_to_str: bool | None = _Unset,
    gt: SupportsGt | None = _Unset,
    ge: SupportsGe | None = _Unset,
    lt: SupportsLt | None = _Unset,
    le: SupportsLe | None = _Unset,
    multiple_of: float | None = _Unset,
    allow_inf_nan: bool | None = _Unset,
    max_digits: int | None = _Unset,
    decimal_places: int | None = _Unset,
    min_length: int | None = _Unset,
    max_length: int | None = _Unset,
    union_mode: Literal["smart", "left_to_right"] = _Unset,
    fail_fast: bool | None = _Unset,
    **extra: Unpack[_EmptyKwargs]
) -> Any

Field(
    default: _T,
    *,
    alias: str | None = _Unset,
    alias_priority: int | None = _Unset,
    validation_alias: (
        str | AliasPath | AliasChoices | None
    ) = _Unset,
    serialization_alias: str | None = _Unset,
    title: str | None = _Unset,
    field_title_generator: (
        Callable[[str, FieldInfo], str] | None
    ) = _Unset,
    description: str | None = _Unset,
    examples: list[Any] | None = _Unset,
    exclude: bool | None = _Unset,
    discriminator: str | Discriminator | None = _Unset,
    deprecated: Deprecated | str | bool | None = _Unset,
    json_schema_extra: (
        JsonDict | Callable[[JsonDict], None] | None
    ) = _Unset,
    frozen: bool | None = _Unset,
    validate_default: bool | None = _Unset,
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | Pattern[str] | None = _Unset,
    strict: bool | None = _Unset,
    coerce_numbers_to_str: bool | None = _Unset,
    gt: SupportsGt | None = _Unset,
    ge: SupportsGe | None = _Unset,
    lt: SupportsLt | None = _Unset,
    le: SupportsLe | None = _Unset,
    multiple_of: float | None = _Unset,
    allow_inf_nan: bool | None = _Unset,
    max_digits: int | None = _Unset,
    decimal_places: int | None = _Unset,
    min_length: int | None = _Unset,
    max_length: int | None = _Unset,
    union_mode: Literal["smart", "left_to_right"] = _Unset,
    fail_fast: bool | None = _Unset,
    **extra: Unpack[_EmptyKwargs]
) -> _T

Field(
    *,
    default_factory: (
        Callable[[], _T] | Callable[[dict[str, Any]], _T]
    ),
    alias: str | None = _Unset,
    alias_priority: int | None = _Unset,
    validation_alias: (
        str | AliasPath | AliasChoices | None
    ) = _Unset,
    serialization_alias: str | None = _Unset,
    title: str | None = _Unset,
    field_title_generator: (
        Callable[[str, FieldInfo], str] | None
    ) = _Unset,
    description: str | None = _Unset,
    examples: list[Any] | None = _Unset,
    exclude: bool | None = _Unset,
    discriminator: str | Discriminator | None = _Unset,
    deprecated: Deprecated | str | bool | None = _Unset,
    json_schema_extra: (
        JsonDict | Callable[[JsonDict], None] | None
    ) = _Unset,
    frozen: bool | None = _Unset,
    validate_default: bool | None = _Unset,
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | Pattern[str] | None = _Unset,
    strict: bool | None = _Unset,
    coerce_numbers_to_str: bool | None = _Unset,
    gt: SupportsGt | None = _Unset,
    ge: SupportsGe | None = _Unset,
    lt: SupportsLt | None = _Unset,
    le: SupportsLe | None = _Unset,
    multiple_of: float | None = _Unset,
    allow_inf_nan: bool | None = _Unset,
    max_digits: int | None = _Unset,
    decimal_places: int | None = _Unset,
    min_length: int | None = _Unset,
    max_length: int | None = _Unset,
    union_mode: Literal["smart", "left_to_right"] = _Unset,
    fail_fast: bool | None = _Unset,
    **extra: Unpack[_EmptyKwargs]
) -> _T

Field(
    *,
    alias: str | None = _Unset,
    alias_priority: int | None = _Unset,
    validation_alias: (
        str | AliasPath | AliasChoices | None
    ) = _Unset,
    serialization_alias: str | None = _Unset,
    title: str | None = _Unset,
    field_title_generator: (
        Callable[[str, FieldInfo], str] | None
    ) = _Unset,
    description: str | None = _Unset,
    examples: list[Any] | None = _Unset,
    exclude: bool | None = _Unset,
    discriminator: str | Discriminator | None = _Unset,
    deprecated: Deprecated | str | bool | None = _Unset,
    json_schema_extra: (
        JsonDict | Callable[[JsonDict], None] | None
    ) = _Unset,
    frozen: bool | None = _Unset,
    validate_default: bool | None = _Unset,
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | Pattern[str] | None = _Unset,
    strict: bool | None = _Unset,
    coerce_numbers_to_str: bool | None = _Unset,
    gt: SupportsGt | None = _Unset,
    ge: SupportsGe | None = _Unset,
    lt: SupportsLt | None = _Unset,
    le: SupportsLe | None = _Unset,
    multiple_of: float | None = _Unset,
    allow_inf_nan: bool | None = _Unset,
    max_digits: int | None = _Unset,
    decimal_places: int | None = _Unset,
    min_length: int | None = _Unset,
    max_length: int | None = _Unset,
    union_mode: Literal["smart", "left_to_right"] = _Unset,
    fail_fast: bool | None = _Unset,
    **extra: Unpack[_EmptyKwargs]
) -> Any

Field(
    default: Any = PydanticUndefined,
    *,
    default_factory: (
        Callable[[], Any]
        | Callable[[dict[str, Any]], Any]
        | None
    ) = _Unset,
    alias: str | None = _Unset,
    alias_priority: int | None = _Unset,
    validation_alias: (
        str | AliasPath | AliasChoices | None
    ) = _Unset,
    serialization_alias: str | None = _Unset,
    title: str | None = _Unset,
    field_title_generator: (
        Callable[[str, FieldInfo], str] | None
    ) = _Unset,
    description: str | None = _Unset,
    examples: list[Any] | None = _Unset,
    exclude: bool | None = _Unset,
    discriminator: str | Discriminator | None = _Unset,
    deprecated: Deprecated | str | bool | None = _Unset,
    json_schema_extra: (
        JsonDict | Callable[[JsonDict], None] | None
    ) = _Unset,
    frozen: bool | None = _Unset,
    validate_default: bool | None = _Unset,
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | Pattern[str] | None = _Unset,
    strict: bool | None = _Unset,
    coerce_numbers_to_str: bool | None = _Unset,
    gt: SupportsGt | None = _Unset,
    ge: SupportsGe | None = _Unset,
    lt: SupportsLt | None = _Unset,
    le: SupportsLe | None = _Unset,
    multiple_of: float | None = _Unset,
    allow_inf_nan: bool | None = _Unset,
    max_digits: int | None = _Unset,
    decimal_places: int | None = _Unset,
    min_length: int | None = _Unset,
    max_length: int | None = _Unset,
    union_mode: Literal["smart", "left_to_right"] = _Unset,
    fail_fast: bool | None = _Unset,
    **extra: Unpack[_EmptyKwargs]
) -> Any

用法文档

字段

为可配置的对象创建字段。

用于提供关于字段的额外信息，无论是为了模型模式还是复杂的验证。一些参数仅适用于数字字段 (int, float, Decimal)，另一些仅适用于 str。

注意

任何 _Unset 对象都将被 _DefaultValues 字典中定义的相应值替换。如果在 _DefaultValues 字典中找不到 _Unset 对象的键，则默认值为 None

参数

名称	类型	描述	默认值
`default`	`Any`	如果字段未设置，则为默认值。	`PydanticUndefined`
`default_factory`	`Callable[[], Any] \| Callable[[dict[str, Any]], Any] \| None`	用于生成默认值的可调用对象。该可调用对象可以接受 0 个参数（在这种情况下，它会被直接调用）或单个参数，其中包含已验证的数据。	`_Unset`
`alias`	`str \| None`	在通过别名验证或序列化时，用于属性的名称。这通常用于在 snake case 和 camel case 之间进行转换等操作。	`_Unset`
`alias_priority`	`int \| None`	别名的优先级。这会影响是否使用别名生成器。	`_Unset`
`validation_alias`	`str \| AliasPath \| AliasChoices \| None`	类似于 `alias`，但仅影响验证，不影响序列化。	`_Unset`
`serialization_alias`	`str \| None`	类似于 `alias`，但仅影响序列化，不影响验证。	`_Unset`
`title`	`str \| None`	人类可读的标题。	`_Unset`
`field_title_generator`	`Callable[[str, FieldInfo], str] \| None`	一个可调用对象，接受字段名称并返回其标题。	`_Unset`
`description`	`str \| None`	人类可读的描述。	`_Unset`
`examples`	`list[Any] \| None`	此字段的示例值。	`_Unset`
`exclude`	`bool \| None`	是否从模型序列化中排除该字段。	`_Unset`
`discriminator`	`str \| Discriminator \| None`	用于区分标记联合类型的字段名称或 Discriminator。	`_Unset`
`deprecated`	`Deprecated \| str \| bool \| None`	弃用消息、`warnings.deprecated` 或 `typing_extensions.deprecated` backport 的实例，或布尔值。如果为 `True`，则在访问该字段时将发出默认弃用消息。	`_Unset`
`json_schema_extra`	`JsonDict \| Callable[[JsonDict], None] \| None`	用于提供额外 JSON schema 属性的字典或可调用对象。	`_Unset`
`frozen`	`bool \| None`	字段是否为冻结状态。如果为 true，则尝试更改实例上的值将引发错误。	`_Unset`
`validate_default`	`bool \| None`	如果为 `True`，则每次创建实例时都对默认值应用验证。否则，出于性能原因，字段的默认值将被信任且不进行验证。	`_Unset`
`repr`	`bool`	一个布尔值，指示是否在 `__repr__` 输出中包含该字段。	`_Unset`
`init`	`bool \| None`	字段是否应包含在数据类的构造函数中。（仅适用于数据类。）	`_Unset`
`init_var`	`bool \| None`	字段是否应该仅包含在数据类的构造函数中。（仅适用于数据类。）	`_Unset`
`kw_only`	`bool \| None`	字段是否应为数据类构造函数中的仅关键字参数。（仅适用于数据类。）	`_Unset`
`coerce_numbers_to_str`	`bool \| None`	是否启用将任何 `Number` 类型强制转换为 `str`（不适用于 `strict` 模式）。	`_Unset`
`strict`	`bool \| None`	如果为 `True`，则对字段应用严格验证。有关详细信息，请参阅严格模式。	`_Unset`
`gt`	`SupportsGt \| None`	大于。如果设置，则值必须大于此值。仅适用于数字。	`_Unset`
`ge`	`SupportsGe \| None`	大于或等于。如果设置，则值必须大于或等于此值。仅适用于数字。	`_Unset`
`lt`	`SupportsLt \| None`	小于。如果设置，则值必须小于此值。仅适用于数字。	`_Unset`
`le`	`SupportsLe \| None`	小于或等于。如果设置，则值必须小于或等于此值。仅适用于数字。	`_Unset`
`multiple_of`	`float \| None`	值必须是此值的倍数。仅适用于数字。	`_Unset`
`min_length`	`int \| None`	可迭代对象的最小长度。	`_Unset`
`max_length`	`int \| None`	可迭代对象的最大长度。	`_Unset`
`pattern`	`str \| Pattern[str] \| None`	字符串的模式（正则表达式）。	`_Unset`
`allow_inf_nan`	`bool \| None`	允许 `inf`、`-inf`、`nan`。仅适用于 float 和 `Decimal` 数字。	`_Unset`
`max_digits`	`int \| None`	字符串允许的最大位数。	`_Unset`
`decimal_places`	`int \| None`	数字允许的最大小数位数。	`_Unset`
`union_mode`	`Literal['smart', 'left_to_right']`	验证联合类型时应用的策略。可以是 `smart`（默认）或 `left_to_right`。有关详细信息，请参阅联合模式。	`_Unset`
`fail_fast`	`bool \| None`	如果为 `True`，验证将在第一个错误时停止。如果为 `False`，则将收集所有验证错误。此选项仅适用于可迭代类型（list、tuple、set 和 frozenset）。	`_Unset`
`extra`	`Unpack[_EmptyKwargs]`	（已弃用）将包含在 JSON schema 中的额外字段。警告 `extra` kwargs 已弃用。请改用 `json_schema_extra`。	`{}`

返回

类型	描述
`Any`	一个新的 `FieldInfo`。返回注解为 `Any`，因此 `Field` 可以用于类型注解字段，而不会导致类型错误。

源代码位于 pydantic/fields.py

def Field(  # noqa: C901
    default: Any = PydanticUndefined,
    *,
    default_factory: Callable[[], Any] | Callable[[dict[str, Any]], Any] | None = _Unset,
    alias: str | None = _Unset,
    alias_priority: int | None = _Unset,
    validation_alias: str | AliasPath | AliasChoices | None = _Unset,
    serialization_alias: str | None = _Unset,
    title: str | None = _Unset,
    field_title_generator: Callable[[str, FieldInfo], str] | None = _Unset,
    description: str | None = _Unset,
    examples: list[Any] | None = _Unset,
    exclude: bool | None = _Unset,
    discriminator: str | types.Discriminator | None = _Unset,
    deprecated: Deprecated | str | bool | None = _Unset,
    json_schema_extra: JsonDict | Callable[[JsonDict], None] | None = _Unset,
    frozen: bool | None = _Unset,
    validate_default: bool | None = _Unset,
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | typing.Pattern[str] | None = _Unset,
    strict: bool | None = _Unset,
    coerce_numbers_to_str: bool | None = _Unset,
    gt: annotated_types.SupportsGt | None = _Unset,
    ge: annotated_types.SupportsGe | None = _Unset,
    lt: annotated_types.SupportsLt | None = _Unset,
    le: annotated_types.SupportsLe | None = _Unset,
    multiple_of: float | None = _Unset,
    allow_inf_nan: bool | None = _Unset,
    max_digits: int | None = _Unset,
    decimal_places: int | None = _Unset,
    min_length: int | None = _Unset,
    max_length: int | None = _Unset,
    union_mode: Literal['smart', 'left_to_right'] = _Unset,
    fail_fast: bool | None = _Unset,
    **extra: Unpack[_EmptyKwargs],
) -> Any:
    """!!! abstract "Usage Documentation"
        [Fields](../concepts/fields.md)

    Create a field for objects that can be configured.

    Used to provide extra information about a field, either for the model schema or complex validation. Some arguments
    apply only to number fields (`int`, `float`, `Decimal`) and some apply only to `str`.

    Note:
        - Any `_Unset` objects will be replaced by the corresponding value defined in the `_DefaultValues` dictionary. If a key for the `_Unset` object is not found in the `_DefaultValues` dictionary, it will default to `None`

    Args:
        default: Default value if the field is not set.
        default_factory: A callable to generate the default value. The callable can either take 0 arguments
            (in which case it is called as is) or a single argument containing the already validated data.
        alias: The name to use for the attribute when validating or serializing by alias.
            This is often used for things like converting between snake and camel case.
        alias_priority: Priority of the alias. This affects whether an alias generator is used.
        validation_alias: Like `alias`, but only affects validation, not serialization.
        serialization_alias: Like `alias`, but only affects serialization, not validation.
        title: Human-readable title.
        field_title_generator: A callable that takes a field name and returns title for it.
        description: Human-readable description.
        examples: Example values for this field.
        exclude: Whether to exclude the field from the model serialization.
        discriminator: Field name or Discriminator for discriminating the type in a tagged union.
        deprecated: A deprecation message, an instance of `warnings.deprecated` or the `typing_extensions.deprecated` backport,
            or a boolean. If `True`, a default deprecation message will be emitted when accessing the field.
        json_schema_extra: A dict or callable to provide extra JSON schema properties.
        frozen: Whether the field is frozen. If true, attempts to change the value on an instance will raise an error.
        validate_default: If `True`, apply validation to the default value every time you create an instance.
            Otherwise, for performance reasons, the default value of the field is trusted and not validated.
        repr: A boolean indicating whether to include the field in the `__repr__` output.
        init: Whether the field should be included in the constructor of the dataclass.
            (Only applies to dataclasses.)
        init_var: Whether the field should _only_ be included in the constructor of the dataclass.
            (Only applies to dataclasses.)
        kw_only: Whether the field should be a keyword-only argument in the constructor of the dataclass.
            (Only applies to dataclasses.)
        coerce_numbers_to_str: Whether to enable coercion of any `Number` type to `str` (not applicable in `strict` mode).
        strict: If `True`, strict validation is applied to the field.
            See [Strict Mode](../concepts/strict_mode.md) for details.
        gt: Greater than. If set, value must be greater than this. Only applicable to numbers.
        ge: Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers.
        lt: Less than. If set, value must be less than this. Only applicable to numbers.
        le: Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers.
        multiple_of: Value must be a multiple of this. Only applicable to numbers.
        min_length: Minimum length for iterables.
        max_length: Maximum length for iterables.
        pattern: Pattern for strings (a regular expression).
        allow_inf_nan: Allow `inf`, `-inf`, `nan`. Only applicable to float and [`Decimal`][decimal.Decimal] numbers.
        max_digits: Maximum number of allow digits for strings.
        decimal_places: Maximum number of decimal places allowed for numbers.
        union_mode: The strategy to apply when validating a union. Can be `smart` (the default), or `left_to_right`.
            See [Union Mode](../concepts/unions.md#union-modes) for details.
        fail_fast: If `True`, validation will stop on the first error. If `False`, all validation errors will be collected.
            This option can be applied only to iterable types (list, tuple, set, and frozenset).
        extra: (Deprecated) Extra fields that will be included in the JSON schema.

            !!! warning Deprecated
                The `extra` kwargs is deprecated. Use `json_schema_extra` instead.

    Returns:
        A new [`FieldInfo`][pydantic.fields.FieldInfo]. The return annotation is `Any` so `Field` can be used on
            type-annotated fields without causing a type error.
    """
    # Check deprecated and removed params from V1. This logic should eventually be removed.
    const = extra.pop('const', None)  # type: ignore
    if const is not None:
        raise PydanticUserError('`const` is removed, use `Literal` instead', code='removed-kwargs')

    min_items = extra.pop('min_items', None)  # type: ignore
    if min_items is not None:
        warn('`min_items` is deprecated and will be removed, use `min_length` instead', DeprecationWarning)
        if min_length in (None, _Unset):
            min_length = min_items  # type: ignore

    max_items = extra.pop('max_items', None)  # type: ignore
    if max_items is not None:
        warn('`max_items` is deprecated and will be removed, use `max_length` instead', DeprecationWarning)
        if max_length in (None, _Unset):
            max_length = max_items  # type: ignore

    unique_items = extra.pop('unique_items', None)  # type: ignore
    if unique_items is not None:
        raise PydanticUserError(
            (
                '`unique_items` is removed, use `Set` instead'
                '(this feature is discussed in https://github.com/pydantic/pydantic-core/issues/296)'
            ),
            code='removed-kwargs',
        )

    allow_mutation = extra.pop('allow_mutation', None)  # type: ignore
    if allow_mutation is not None:
        warn('`allow_mutation` is deprecated and will be removed. use `frozen` instead', DeprecationWarning)
        if allow_mutation is False:
            frozen = True

    regex = extra.pop('regex', None)  # type: ignore
    if regex is not None:
        raise PydanticUserError('`regex` is removed. use `pattern` instead', code='removed-kwargs')

    if extra:
        warn(
            'Using extra keyword arguments on `Field` is deprecated and will be removed.'
            ' Use `json_schema_extra` instead.'
            f' (Extra keys: {", ".join(k.__repr__() for k in extra.keys())})',
            DeprecationWarning,
        )
        if not json_schema_extra or json_schema_extra is _Unset:
            json_schema_extra = extra  # type: ignore

    if (
        validation_alias
        and validation_alias is not _Unset
        and not isinstance(validation_alias, (str, AliasChoices, AliasPath))
    ):
        raise TypeError('Invalid `validation_alias` type. it should be `str`, `AliasChoices`, or `AliasPath`')

    if serialization_alias in (_Unset, None) and isinstance(alias, str):
        serialization_alias = alias

    if validation_alias in (_Unset, None):
        validation_alias = alias

    include = extra.pop('include', None)  # type: ignore
    if include is not None:
        warn('`include` is deprecated and does nothing. It will be removed, use `exclude` instead', DeprecationWarning)

    return FieldInfo.from_field(
        default,
        default_factory=default_factory,
        alias=alias,
        alias_priority=alias_priority,
        validation_alias=validation_alias,
        serialization_alias=serialization_alias,
        title=title,
        field_title_generator=field_title_generator,
        description=description,
        examples=examples,
        exclude=exclude,
        discriminator=discriminator,
        deprecated=deprecated,
        json_schema_extra=json_schema_extra,
        frozen=frozen,
        pattern=pattern,
        validate_default=validate_default,
        repr=repr,
        init=init,
        init_var=init_var,
        kw_only=kw_only,
        coerce_numbers_to_str=coerce_numbers_to_str,
        strict=strict,
        gt=gt,
        ge=ge,
        lt=lt,
        le=le,
        multiple_of=multiple_of,
        min_length=min_length,
        max_length=max_length,
        allow_inf_nan=allow_inf_nan,
        max_digits=max_digits,
        decimal_places=decimal_places,
        union_mode=union_mode,
        fail_fast=fail_fast,
    )

FieldInfo ¶

FieldInfo(**kwargs: Unpack[_FieldInfoInputs])

基类：Representation

此类保存关于字段的信息。

FieldInfo 用于任何字段定义，无论是否显式使用 Field() 函数。

警告

通常不应直接创建 FieldInfo，您只需要在访问 BaseModel 的 .model_fields 内部结构时使用它。

属性

名称	类型	描述
`annotation`	`type[Any] \| None`	字段的类型注解。
`default`	`Any`	字段的默认值。
`default_factory`	`Callable[[], Any] \| Callable[[dict[str, Any]], Any] \| None`	用于生成默认值的可调用对象。该可调用对象可以接受 0 个参数（在这种情况下，它会被直接调用）或单个参数，其中包含已验证的数据。
`alias`	`str \| None`	字段的别名。
`alias_priority`	`int \| None`	字段别名的优先级。
`validation_alias`	`str \| AliasPath \| AliasChoices \| None`	字段的验证别名。
`serialization_alias`	`str \| None`	字段的序列化别名。
`title`	`str \| None`	字段的标题。
`field_title_generator`	`Callable[[str, FieldInfo], str] \| None`	一个可调用对象，接受字段名称并返回其标题。
`description`	`str \| None`	字段的描述。
`examples`	`list[Any] \| None`	字段的示例列表。
`exclude`	`bool \| None`	是否从模型序列化中排除该字段。
`discriminator`	`str \| Discriminator \| None`	用于区分标记联合类型的字段名称或 Discriminator。
`deprecated`	`Deprecated \| str \| bool \| None`	弃用消息、`warnings.deprecated` 或 `typing_extensions.deprecated` backport 的实例，或布尔值。如果为 `True`，则在访问该字段时将发出默认弃用消息。
`json_schema_extra`	`JsonDict \| Callable[[JsonDict], None] \| None`	用于提供额外 JSON schema 属性的字典或可调用对象。
`frozen`	`bool \| None`	字段是否为冻结状态。
`validate_default`	`bool \| None`	是否验证字段的默认值。
`repr`	`bool`	是否在模型的表示中包含该字段。
`init`	`bool \| None`	字段是否应包含在数据类的构造函数中。
`init_var`	`bool \| None`	字段是否应该仅包含在数据类的构造函数中，而不存储。
`kw_only`	`bool \| None`	字段是否应为数据类构造函数中的仅关键字参数。
`metadata`	`list[Any]`	元数据约束列表。

有关预期参数的更多详细信息，请参阅 pydantic.fields.Field 的签名。

源代码位于 pydantic/fields.py

def __init__(self, **kwargs: Unpack[_FieldInfoInputs]) -> None:
    """This class should generally not be initialized directly; instead, use the `pydantic.fields.Field` function
    or one of the constructor classmethods.

    See the signature of `pydantic.fields.Field` for more details about the expected arguments.
    """
    self._attributes_set = {k: v for k, v in kwargs.items() if v is not _Unset}
    kwargs = {k: _DefaultValues.get(k) if v is _Unset else v for k, v in kwargs.items()}  # type: ignore
    self.annotation = kwargs.get('annotation')

    default = kwargs.pop('default', PydanticUndefined)
    if default is Ellipsis:
        self.default = PydanticUndefined
        self._attributes_set.pop('default', None)
    else:
        self.default = default

    self.default_factory = kwargs.pop('default_factory', None)

    if self.default is not PydanticUndefined and self.default_factory is not None:
        raise TypeError('cannot specify both default and default_factory')

    self.alias = kwargs.pop('alias', None)
    self.validation_alias = kwargs.pop('validation_alias', None)
    self.serialization_alias = kwargs.pop('serialization_alias', None)
    alias_is_set = any(alias is not None for alias in (self.alias, self.validation_alias, self.serialization_alias))
    self.alias_priority = kwargs.pop('alias_priority', None) or 2 if alias_is_set else None
    self.title = kwargs.pop('title', None)
    self.field_title_generator = kwargs.pop('field_title_generator', None)
    self.description = kwargs.pop('description', None)
    self.examples = kwargs.pop('examples', None)
    self.exclude = kwargs.pop('exclude', None)
    self.discriminator = kwargs.pop('discriminator', None)
    # For compatibility with FastAPI<=0.110.0, we preserve the existing value if it is not overridden
    self.deprecated = kwargs.pop('deprecated', getattr(self, 'deprecated', None))
    self.repr = kwargs.pop('repr', True)
    self.json_schema_extra = kwargs.pop('json_schema_extra', None)
    self.validate_default = kwargs.pop('validate_default', None)
    self.frozen = kwargs.pop('frozen', None)
    # currently only used on dataclasses
    self.init = kwargs.pop('init', None)
    self.init_var = kwargs.pop('init_var', None)
    self.kw_only = kwargs.pop('kw_only', None)

    self.metadata = self._collect_metadata(kwargs)  # type: ignore

    # Private attributes:
    self._qualifiers: set[Qualifier] = set()
    # Used to rebuild FieldInfo instances:
    self._complete = True
    self._original_annotation: Any = PydanticUndefined
    self._original_assignment: Any = PydanticUndefined

from_field `staticmethod` ¶

from_field(
    default: Any = PydanticUndefined,
    **kwargs: Unpack[_FromFieldInfoInputs]
) -> FieldInfo

使用 Field 函数创建一个新的 FieldInfo 对象。

参数

名称	类型	描述	默认值
`default`	`Any`	字段的默认值。默认为 Undefined。	`PydanticUndefined`
`**kwargs`	`Unpack[_FromFieldInfoInputs]`	额外的参数字典。	`{}`

引发

类型	描述
`TypeError`	如果 'annotation' 作为关键字参数传递。

返回

类型	描述
`FieldInfo`	一个具有给定参数的新 FieldInfo 对象。

示例

以下是如何创建具有默认值的字段，如下所示

import pydantic

class MyModel(pydantic.BaseModel):
    foo: int = pydantic.Field(4)

源代码位于 pydantic/fields.py

@staticmethod
def from_field(default: Any = PydanticUndefined, **kwargs: Unpack[_FromFieldInfoInputs]) -> FieldInfo:
    """Create a new `FieldInfo` object with the `Field` function.

    Args:
        default: The default value for the field. Defaults to Undefined.
        **kwargs: Additional arguments dictionary.

    Raises:
        TypeError: If 'annotation' is passed as a keyword argument.

    Returns:
        A new FieldInfo object with the given parameters.

    Example:
        This is how you can create a field with default value like this:

        ```python
        import pydantic

        class MyModel(pydantic.BaseModel):
            foo: int = pydantic.Field(4)
        ```
    """
    if 'annotation' in kwargs:
        raise TypeError('"annotation" is not permitted as a Field keyword argument')
    return FieldInfo(default=default, **kwargs)

from_annotation `staticmethod` ¶

from_annotation(
    annotation: type[Any],
    *,
    _source: AnnotationSource = ANY
) -> FieldInfo

从裸注解创建 FieldInfo 实例。

此函数在内部用于从裸注解创建 FieldInfo，如下所示

import pydantic

class MyModel(pydantic.BaseModel):
    foo: int  # <-- like this

我们还考虑了注解可以是 Annotated 实例的情况，以及 Annotated 中（非第一个）参数之一是 FieldInfo 实例的情况，例如

from typing import Annotated

import annotated_types

import pydantic

class MyModel(pydantic.BaseModel):
    foo: Annotated[int, annotated_types.Gt(42)]
    bar: Annotated[int, pydantic.Field(gt=42)]

参数

名称	类型	描述	默认值
`annotation`	`type[Any]`	一个注解对象。	required

返回

类型	描述
`FieldInfo`	字段元数据的实例。

源代码位于 pydantic/fields.py

@staticmethod
def from_annotation(annotation: type[Any], *, _source: AnnotationSource = AnnotationSource.ANY) -> FieldInfo:
    """Creates a `FieldInfo` instance from a bare annotation.

    This function is used internally to create a `FieldInfo` from a bare annotation like this:

    ```python
    import pydantic

    class MyModel(pydantic.BaseModel):
        foo: int  # <-- like this
    ```

    We also account for the case where the annotation can be an instance of `Annotated` and where
    one of the (not first) arguments in `Annotated` is an instance of `FieldInfo`, e.g.:

    ```python
    from typing import Annotated

    import annotated_types

    import pydantic

    class MyModel(pydantic.BaseModel):
        foo: Annotated[int, annotated_types.Gt(42)]
        bar: Annotated[int, pydantic.Field(gt=42)]
    ```

    Args:
        annotation: An annotation object.

    Returns:
        An instance of the field metadata.
    """
    try:
        inspected_ann = inspect_annotation(
            annotation,
            annotation_source=_source,
            unpack_type_aliases='skip',
        )
    except ForbiddenQualifier as e:
        raise PydanticForbiddenQualifier(e.qualifier, annotation)

    # TODO check for classvar and error?

    # No assigned value, this happens when using a bare `Final` qualifier (also for other
    # qualifiers, but they shouldn't appear here). In this case we infer the type as `Any`
    # because we don't have any assigned value.
    type_expr: Any = Any if inspected_ann.type is UNKNOWN else inspected_ann.type
    final = 'final' in inspected_ann.qualifiers
    metadata = inspected_ann.metadata

    if not metadata:
        # No metadata, e.g. `field: int`, or `field: Final[str]`:
        field_info = FieldInfo(annotation=type_expr, frozen=final or None)
        field_info._qualifiers = inspected_ann.qualifiers
        return field_info

    # With metadata, e.g. `field: Annotated[int, Field(...), Gt(1)]`:
    field_info_annotations = [a for a in metadata if isinstance(a, FieldInfo)]
    field_info = FieldInfo.merge_field_infos(*field_info_annotations, annotation=type_expr)

    new_field_info = copy(field_info)
    new_field_info.annotation = type_expr
    new_field_info.frozen = final or field_info.frozen
    field_metadata: list[Any] = []
    for a in metadata:
        if typing_objects.is_deprecated(a):
            new_field_info.deprecated = a.message
        elif not isinstance(a, FieldInfo):
            field_metadata.append(a)
        else:
            field_metadata.extend(a.metadata)
        new_field_info.metadata = field_metadata
    new_field_info._qualifiers = inspected_ann.qualifiers
    return new_field_info

from_annotated_attribute `staticmethod` ¶

from_annotated_attribute(
    annotation: type[Any],
    default: Any,
    *,
    _source: AnnotationSource = ANY
) -> FieldInfo

从带有默认值的注解创建 FieldInfo。

这用于以下情况

from typing import Annotated

import annotated_types

import pydantic

class MyModel(pydantic.BaseModel):
    foo: int = 4  # <-- like this
    bar: Annotated[int, annotated_types.Gt(4)] = 4  # <-- or this
    spam: Annotated[int, pydantic.Field(gt=4)] = 4  # <-- or this

参数

名称	类型	描述	默认值
`annotation`	`type[Any]`	字段的类型注解。	required
`default`	`Any`	字段的默认值。	required

返回

类型	描述
`FieldInfo`	一个具有传递值的字段对象。

源代码位于 pydantic/fields.py

@staticmethod
def from_annotated_attribute(
    annotation: type[Any], default: Any, *, _source: AnnotationSource = AnnotationSource.ANY
) -> FieldInfo:
    """Create `FieldInfo` from an annotation with a default value.

    This is used in cases like the following:

    ```python
    from typing import Annotated

    import annotated_types

    import pydantic

    class MyModel(pydantic.BaseModel):
        foo: int = 4  # <-- like this
        bar: Annotated[int, annotated_types.Gt(4)] = 4  # <-- or this
        spam: Annotated[int, pydantic.Field(gt=4)] = 4  # <-- or this
    ```

    Args:
        annotation: The type annotation of the field.
        default: The default value of the field.

    Returns:
        A field object with the passed values.
    """
    if annotation is default:
        raise PydanticUserError(
            'Error when building FieldInfo from annotated attribute. '
            "Make sure you don't have any field name clashing with a type annotation.",
            code='unevaluable-type-annotation',
        )

    try:
        inspected_ann = inspect_annotation(
            annotation,
            annotation_source=_source,
            unpack_type_aliases='skip',
        )
    except ForbiddenQualifier as e:
        raise PydanticForbiddenQualifier(e.qualifier, annotation)

    # TODO check for classvar and error?

    # TODO infer from the default, this can be done in v3 once we treat final fields with
    # a default as proper fields and not class variables:
    type_expr: Any = Any if inspected_ann.type is UNKNOWN else inspected_ann.type
    final = 'final' in inspected_ann.qualifiers
    metadata = inspected_ann.metadata

    if isinstance(default, FieldInfo):
        # e.g. `field: int = Field(...)`
        default.annotation = type_expr
        default.metadata += metadata
        merged_default = FieldInfo.merge_field_infos(
            *[x for x in metadata if isinstance(x, FieldInfo)],
            default,
            annotation=default.annotation,
        )
        merged_default.frozen = final or merged_default.frozen
        merged_default._qualifiers = inspected_ann.qualifiers
        return merged_default

    if isinstance(default, dataclasses.Field):
        # `collect_dataclass_fields()` passes the dataclass Field as a default.
        pydantic_field = FieldInfo._from_dataclass_field(default)
        pydantic_field.annotation = type_expr
        pydantic_field.metadata += metadata
        pydantic_field = FieldInfo.merge_field_infos(
            *[x for x in metadata if isinstance(x, FieldInfo)],
            pydantic_field,
            annotation=pydantic_field.annotation,
        )
        pydantic_field.frozen = final or pydantic_field.frozen
        pydantic_field.init_var = 'init_var' in inspected_ann.qualifiers
        pydantic_field.init = getattr(default, 'init', None)
        pydantic_field.kw_only = getattr(default, 'kw_only', None)
        pydantic_field._qualifiers = inspected_ann.qualifiers
        return pydantic_field

    if not metadata:
        # No metadata, e.g. `field: int = ...`, or `field: Final[str] = ...`:
        field_info = FieldInfo(annotation=type_expr, default=default, frozen=final or None)
        field_info._qualifiers = inspected_ann.qualifiers
        return field_info

    # With metadata, e.g. `field: Annotated[int, Field(...), Gt(1)] = ...`:
    field_infos = [a for a in metadata if isinstance(a, FieldInfo)]
    field_info = FieldInfo.merge_field_infos(*field_infos, annotation=type_expr, default=default)
    field_metadata: list[Any] = []
    for a in metadata:
        if typing_objects.is_deprecated(a):
            field_info.deprecated = a.message
        elif not isinstance(a, FieldInfo):
            field_metadata.append(a)
        else:
            field_metadata.extend(a.metadata)
    field_info.metadata = field_metadata
    field_info._qualifiers = inspected_ann.qualifiers
    return field_info

merge_field_infos `staticmethod` ¶

merge_field_infos(
    *field_infos: FieldInfo, **overrides: Any
) -> FieldInfo

合并 FieldInfo 实例，仅保留显式设置的属性。

后面的 FieldInfo 实例会覆盖前面的实例。

返回

名称	类型	描述
`FieldInfo`	`FieldInfo`	一个合并的 FieldInfo 实例。

源代码位于 pydantic/fields.py

@staticmethod
def merge_field_infos(*field_infos: FieldInfo, **overrides: Any) -> FieldInfo:
    """Merge `FieldInfo` instances keeping only explicitly set attributes.

    Later `FieldInfo` instances override earlier ones.

    Returns:
        FieldInfo: A merged FieldInfo instance.
    """
    if len(field_infos) == 1:
        # No merging necessary, but we still need to make a copy and apply the overrides
        field_info = copy(field_infos[0])
        field_info._attributes_set.update(overrides)

        default_override = overrides.pop('default', PydanticUndefined)
        if default_override is Ellipsis:
            default_override = PydanticUndefined
        if default_override is not PydanticUndefined:
            field_info.default = default_override

        for k, v in overrides.items():
            setattr(field_info, k, v)
        return field_info  # type: ignore

    merged_field_info_kwargs: dict[str, Any] = {}
    metadata = {}
    for field_info in field_infos:
        attributes_set = field_info._attributes_set.copy()

        try:
            json_schema_extra = attributes_set.pop('json_schema_extra')
            existing_json_schema_extra = merged_field_info_kwargs.get('json_schema_extra')

            if existing_json_schema_extra is None:
                merged_field_info_kwargs['json_schema_extra'] = json_schema_extra
            if isinstance(existing_json_schema_extra, dict):
                if isinstance(json_schema_extra, dict):
                    merged_field_info_kwargs['json_schema_extra'] = {
                        **existing_json_schema_extra,
                        **json_schema_extra,
                    }
                if callable(json_schema_extra):
                    warn(
                        'Composing `dict` and `callable` type `json_schema_extra` is not supported.'
                        'The `callable` type is being ignored.'
                        "If you'd like support for this behavior, please open an issue on pydantic.",
                        PydanticJsonSchemaWarning,
                    )
            elif callable(json_schema_extra):
                # if ever there's a case of a callable, we'll just keep the last json schema extra spec
                merged_field_info_kwargs['json_schema_extra'] = json_schema_extra
        except KeyError:
            pass

        # later FieldInfo instances override everything except json_schema_extra from earlier FieldInfo instances
        merged_field_info_kwargs.update(attributes_set)

        for x in field_info.metadata:
            if not isinstance(x, FieldInfo):
                metadata[type(x)] = x

    merged_field_info_kwargs.update(overrides)
    field_info = FieldInfo(**merged_field_info_kwargs)
    field_info.metadata = list(metadata.values())
    return field_info

deprecation_message `property` ¶

deprecation_message: str | None

要发出的弃用消息，如果未设置则为 None。

default_factory_takes_validated_data `property` ¶

default_factory_takes_validated_data: bool | None

提供的默认工厂可调用对象是否具有已验证的数据参数。

如果未设置默认工厂，则返回 None。

get_default ¶

get_default(
    *,
    call_default_factory: Literal[True],
    validated_data: dict[str, Any] | None = None
) -> Any

get_default(
    *, call_default_factory: Literal[False] = ...
) -> Any

get_default(
    *,
    call_default_factory: bool = False,
    validated_data: dict[str, Any] | None = None
) -> Any

获取默认值。

我们公开了一个选项，用于是否调用 default_factory（如果存在），因为调用它可能会导致我们想要避免的副作用。但是，在某些情况下，确实应该调用它（即，当通过 model_construct 实例化模型时）。

参数

名称	类型	描述	默认值
`call_default_factory`	`bool`	是否调用默认工厂。	`False`
`validated_data`	`dict[str, Any] \| None`	要传递给默认工厂的已验证数据。	`None`

返回

类型	描述
`Any`	默认值，如果请求或未设置则调用默认工厂，否则为 `None`。

源代码位于 pydantic/fields.py

def get_default(self, *, call_default_factory: bool = False, validated_data: dict[str, Any] | None = None) -> Any:
    """Get the default value.

    We expose an option for whether to call the default_factory (if present), as calling it may
    result in side effects that we want to avoid. However, there are times when it really should
    be called (namely, when instantiating a model via `model_construct`).

    Args:
        call_default_factory: Whether to call the default factory or not.
        validated_data: The already validated data to be passed to the default factory.

    Returns:
        The default value, calling the default factory if requested or `None` if not set.
    """
    if self.default_factory is None:
        return _utils.smart_deepcopy(self.default)
    elif call_default_factory:
        if self.default_factory_takes_validated_data:
            fac = cast('Callable[[dict[str, Any]], Any]', self.default_factory)
            if validated_data is None:
                raise ValueError(
                    "The default factory requires the 'validated_data' argument, which was not provided when calling 'get_default'."
                )
            return fac(validated_data)
        else:
            fac = cast('Callable[[], Any]', self.default_factory)
            return fac()
    else:
        return None

is_required ¶

is_required() -> bool

检查字段是否为必需字段（即，没有默认值或工厂）。

返回

类型	描述
`bool`	如果字段是必需的，则返回 `True`，否则返回 `False`。

源代码位于 pydantic/fields.py

def is_required(self) -> bool:
    """Check if the field is required (i.e., does not have a default value or factory).

    Returns:
        `True` if the field is required, `False` otherwise.
    """
    return self.default is PydanticUndefined and self.default_factory is None

rebuild_annotation ¶

rebuild_annotation() -> Any

尝试重建原始注解，以便在函数签名中使用。

如果存在元数据，它会使用 Annotated 将其添加到原始注解中。否则，它会按原样返回原始注解。

请注意，由于元数据已展平，原始注解可能无法完全按最初提供的方式重建，例如，如果原始类型具有无法识别的注解，或者使用对 pydantic.Field 的调用进行注解。

返回

类型	描述
`Any`	重建的注解。

源代码位于 pydantic/fields.py

def rebuild_annotation(self) -> Any:
    """Attempts to rebuild the original annotation for use in function signatures.

    If metadata is present, it adds it to the original annotation using
    `Annotated`. Otherwise, it returns the original annotation as-is.

    Note that because the metadata has been flattened, the original annotation
    may not be reconstructed exactly as originally provided, e.g. if the original
    type had unrecognized annotations, or was annotated with a call to `pydantic.Field`.

    Returns:
        The rebuilt annotation.
    """
    if not self.metadata:
        return self.annotation
    else:
        # Annotated arguments must be a tuple
        return Annotated[(self.annotation, *self.metadata)]  # type: ignore

apply_typevars_map ¶

apply_typevars_map(
    typevars_map: Mapping[TypeVar, Any] | None,
    globalns: GlobalsNamespace | None = None,
    localns: MappingNamespace | None = None,
) -> None

将 typevars_map 应用于注解。

此方法在分析参数化泛型类型时使用，以将类型变量替换为其具体类型。

此方法将 typevars_map 就地应用于注解。

参数

名称	类型	描述	默认值
`typevars_map`	`Mapping[TypeVar, Any] \| None`	一个字典，将类型变量映射到它们的具体类型。	required
`globalns`	`GlobalsNamespace \| None`	在类型注解评估期间要使用的全局命名空间。	`None`
`localns`	`MappingNamespace \| None`	在类型注解评估期间要使用的局部命名空间。	`None`

另请参阅

pydantic._internal._generics.replace_types 用于将类型变量替换为其具体类型。

源代码位于 pydantic/fields.py

def apply_typevars_map(
    self,
    typevars_map: Mapping[TypeVar, Any] | None,
    globalns: GlobalsNamespace | None = None,
    localns: MappingNamespace | None = None,
) -> None:
    """Apply a `typevars_map` to the annotation.

    This method is used when analyzing parametrized generic types to replace typevars with their concrete types.

    This method applies the `typevars_map` to the annotation in place.

    Args:
        typevars_map: A dictionary mapping type variables to their concrete types.
        globalns: The globals namespace to use during type annotation evaluation.
        localns: The locals namespace to use during type annotation evaluation.

    See Also:
        pydantic._internal._generics.replace_types is used for replacing the typevars with
            their concrete types.
    """
    annotation, _ = _typing_extra.try_eval_type(self.annotation, globalns, localns)
    self.annotation = _generics.replace_types(annotation, typevars_map)

PrivateAttr ¶

PrivateAttr(
    default: _T, *, init: Literal[False] = False
) -> _T

PrivateAttr(
    *,
    default_factory: Callable[[], _T],
    init: Literal[False] = False
) -> _T

PrivateAttr(*, init: Literal[False] = False) -> Any

PrivateAttr(
    default: Any = PydanticUndefined,
    *,
    default_factory: Callable[[], Any] | None = None,
    init: Literal[False] = False
) -> Any

用法文档

私有模型属性

指示属性旨在私有使用，并且在正常验证/序列化期间不处理。

私有属性不由 Pydantic 验证，因此由您负责确保它们以类型安全的方式使用。

私有属性存储在模型上的 __private_attributes__ 中。

参数

名称	类型	描述	默认值
`default`	`Any`	属性的默认值。默认为 Undefined。	`PydanticUndefined`
`default_factory`	`Callable[[], Any] \| None`	当需要此属性的默认值时将调用的可调用对象。如果同时设置了 `default` 和 `default_factory`，则会引发错误。	`None`
`init`	`Literal[False]`	属性是否应包含在数据类的构造函数中。始终为 `False`。	`False`

返回

类型	描述
`Any`	类 `ModelPrivateAttr` 的实例。

引发

类型	描述
`ValueError`	如果同时设置了 `default` 和 `default_factory`。

源代码位于 pydantic/fields.py

def PrivateAttr(
    default: Any = PydanticUndefined,
    *,
    default_factory: Callable[[], Any] | None = None,
    init: Literal[False] = False,
) -> Any:
    """!!! abstract "Usage Documentation"
        [Private Model Attributes](../concepts/models.md#private-model-attributes)

    Indicates that an attribute is intended for private use and not handled during normal validation/serialization.

    Private attributes are not validated by Pydantic, so it's up to you to ensure they are used in a type-safe manner.

    Private attributes are stored in `__private_attributes__` on the model.

    Args:
        default: The attribute's default value. Defaults to Undefined.
        default_factory: Callable that will be
            called when a default value is needed for this attribute.
            If both `default` and `default_factory` are set, an error will be raised.
        init: Whether the attribute should be included in the constructor of the dataclass. Always `False`.

    Returns:
        An instance of [`ModelPrivateAttr`][pydantic.fields.ModelPrivateAttr] class.

    Raises:
        ValueError: If both `default` and `default_factory` are set.
    """
    if default is not PydanticUndefined and default_factory is not None:
        raise TypeError('cannot specify both default and default_factory')

    return ModelPrivateAttr(
        default,
        default_factory=default_factory,
    )

ModelPrivateAttr ¶

ModelPrivateAttr(
    default: Any = PydanticUndefined,
    *,
    default_factory: Callable[[], Any] | None = None
)

基类：Representation

类模型中私有属性的描述符。

警告

通常不应直接创建 ModelPrivateAttr 实例，而应使用 pydantic.fields.PrivateAttr。（这类似于 FieldInfo 与 Field。）

属性

名称	类型	描述
`default`		如果未提供属性的默认值。
`default_factory`		一个可调用函数，用于生成属性的默认值（如果未提供）。

源代码位于 pydantic/fields.py

def __init__(
    self, default: Any = PydanticUndefined, *, default_factory: typing.Callable[[], Any] | None = None
) -> None:
    if default is Ellipsis:
        self.default = PydanticUndefined
    else:
        self.default = default
    self.default_factory = default_factory

get_default ¶

get_default() -> Any

检索对象的默认值。

如果 self.default_factory 为 None，则该方法将返回 self.default 对象的深拷贝。

如果 self.default_factory 不为 None，它将调用 self.default_factory 并返回返回的值。

返回

类型	描述
`Any`	对象的默认值。

源代码位于 pydantic/fields.py

def get_default(self) -> Any:
    """Retrieve the default value of the object.

    If `self.default_factory` is `None`, the method will return a deep copy of the `self.default` object.

    If `self.default_factory` is not `None`, it will call `self.default_factory` and return the value returned.

    Returns:
        The default value of the object.
    """
    return _utils.smart_deepcopy(self.default) if self.default_factory is None else self.default_factory()

computed_field ¶

computed_field(func: PropertyT) -> PropertyT

computed_field(
    *,
    alias: str | None = None,
    alias_priority: int | None = None,
    title: str | None = None,
    field_title_generator: (
        Callable[[str, ComputedFieldInfo], str] | None
    ) = None,
    description: str | None = None,
    deprecated: Deprecated | str | bool | None = None,
    examples: list[Any] | None = None,
    json_schema_extra: (
        JsonDict | Callable[[JsonDict], None] | None
    ) = None,
    repr: bool = True,
    return_type: Any = PydanticUndefined
) -> Callable[[PropertyT], PropertyT]

computed_field(
    func: PropertyT | None = None,
    /,
    *,
    alias: str | None = None,
    alias_priority: int | None = None,
    title: str | None = None,
    field_title_generator: (
        Callable[[str, ComputedFieldInfo], str] | None
    ) = None,
    description: str | None = None,
    deprecated: Deprecated | str | bool | None = None,
    examples: list[Any] | None = None,
    json_schema_extra: (
        JsonDict | Callable[[JsonDict], None] | None
    ) = None,
    repr: bool | None = None,
    return_type: Any = PydanticUndefined,
) -> PropertyT | Callable[[PropertyT], PropertyT]

用法文档

computed_field 装饰器

装饰器，用于在序列化模型或数据类时包含 property 和 cached_property。

这对于从其他字段计算的字段，或对于计算成本高昂且应缓存的字段非常有用。

from pydantic import BaseModel, computed_field

class Rectangle(BaseModel):
    width: int
    length: int

    @computed_field
    @property
    def area(self) -> int:
        return self.width * self.length

print(Rectangle(width=3, length=2).model_dump())
#> {'width': 3, 'length': 2, 'area': 6}

如果应用于尚未用 @property 或 @cached_property 装饰的函数，则该函数将自动用 property 包装。虽然这更简洁，但您将在 IDE 中丢失 IntelliSense，并使静态类型检查器感到困惑，因此建议显式使用 @property。

Mypy 警告

即使在 @computed_field 之前将 @property 或 @cached_property 应用于您的函数，mypy 也可能抛出 Decorated property not supported 错误。有关更多信息，请参阅 mypy issue #1362。要避免此错误消息，请在 @computed_field 行中添加 # type: ignore[prop-decorator]。

pyright 支持 @computed_field，不会出现错误。

import random

from pydantic import BaseModel, computed_field

class Square(BaseModel):
    width: float

    @computed_field
    def area(self) -> float:  # converted to a `property` by `computed_field`
        return round(self.width**2, 2)

    @area.setter
    def area(self, new_area: float) -> None:
        self.width = new_area**0.5

    @computed_field(alias='the magic number', repr=False)
    def random_number(self) -> int:
        return random.randint(0, 1_000)

square = Square(width=1.3)

# `random_number` does not appear in representation
print(repr(square))
#> Square(width=1.3, area=1.69)

print(square.random_number)
#> 3

square.area = 4

print(square.model_dump_json(by_alias=True))
#> {"width":2.0,"area":4.0,"the magic number":3}

使用 computed_field 覆盖

您不能使用子类中的 computed_field 覆盖父类中的字段。如果允许这样做，mypy 会对此行为发出警告，并且 dataclasses 也不允许这种模式。请参阅以下示例

from pydantic import BaseModel, computed_field

class Parent(BaseModel):
    a: str

try:

    class Child(Parent):
        @computed_field
        @property
        def a(self) -> str:
            return 'new a'

except TypeError as e:
    print(e)
    '''
    Field 'a' of class 'Child' overrides symbol of same name in a parent class. This override with a computed_field is incompatible.
    '''

默认情况下，用 @computed_field 装饰的私有属性具有 repr=False。

from functools import cached_property

from pydantic import BaseModel, computed_field

class Model(BaseModel):
    foo: int

    @computed_field
    @cached_property
    def _private_cached_property(self) -> int:
        return -self.foo

    @computed_field
    @property
    def _private_property(self) -> int:
        return -self.foo

m = Model(foo=1)
print(repr(m))
#> Model(foo=1)

参数

名称	类型	描述	默认值
`func`	`PropertyT \| None`	要包装的函数。	`None`
`alias`	`str \| None`	当序列化此计算字段时要使用的别名，仅当 `by_alias=True` 时使用	`None`
`alias_priority`	`int \| None`	别名的优先级。这会影响是否使用别名生成器	`None`
`title`	`str \| None`	在 JSON Schema 中包含此计算字段时要使用的标题	`None`
`field_title_generator`	`Callable[[str, ComputedFieldInfo], str] \| None`	一个可调用对象，接受字段名称并返回其标题。	`None`
`description`	`str \| None`	在 JSON Schema 中包含此计算字段时要使用的描述，默认为函数的文档字符串	`None`
`deprecated`	`Deprecated \| str \| bool \| None`	弃用消息（或 `warnings.deprecated` 或 `typing_extensions.deprecated` backport 的实例）。在访问该字段时发出。或布尔值。如果属性用 `deprecated` 装饰器装饰，则将自动设置此值。	`None`
`examples`	`list[Any] \| None`	在 JSON Schema 中包含此计算字段时要使用的示例值	`None`
`json_schema_extra`	`JsonDict \| Callable[[JsonDict], None] \| None`	用于提供额外 JSON schema 属性的字典或可调用对象。	`None`
`repr`	`bool \| None`	是否在模型 repr 中包含此计算字段。私有属性的默认值为 `False`，公共属性的默认值为 `True`。	`None`
`return_type`	`Any`	序列化为 JSON 时序列化逻辑要期望的可选返回类型，如果包含此项，则必须正确，否则会引发 `TypeError`。如果您不包含返回类型，则使用 Any，它会进行运行时自省以处理任意对象。	`PydanticUndefined`

返回

类型	描述
`PropertyT \| Callable[[PropertyT], PropertyT]`	属性的代理包装器。

源代码位于 pydantic/fields.py

def computed_field(
    func: PropertyT | None = None,
    /,
    *,
    alias: str | None = None,
    alias_priority: int | None = None,
    title: str | None = None,
    field_title_generator: typing.Callable[[str, ComputedFieldInfo], str] | None = None,
    description: str | None = None,
    deprecated: Deprecated | str | bool | None = None,
    examples: list[Any] | None = None,
    json_schema_extra: JsonDict | typing.Callable[[JsonDict], None] | None = None,
    repr: bool | None = None,
    return_type: Any = PydanticUndefined,
) -> PropertyT | typing.Callable[[PropertyT], PropertyT]:
    """!!! abstract "Usage Documentation"
        [The `computed_field` decorator](../concepts/fields.md#the-computed_field-decorator)

    Decorator to include `property` and `cached_property` when serializing models or dataclasses.

    This is useful for fields that are computed from other fields, or for fields that are expensive to compute and should be cached.

    ```python
    from pydantic import BaseModel, computed_field

    class Rectangle(BaseModel):
        width: int
        length: int

        @computed_field
        @property
        def area(self) -> int:
            return self.width * self.length

    print(Rectangle(width=3, length=2).model_dump())
    #> {'width': 3, 'length': 2, 'area': 6}
    ```

    If applied to functions not yet decorated with `@property` or `@cached_property`, the function is
    automatically wrapped with `property`. Although this is more concise, you will lose IntelliSense in your IDE,
    and confuse static type checkers, thus explicit use of `@property` is recommended.

    !!! warning "Mypy Warning"
        Even with the `@property` or `@cached_property` applied to your function before `@computed_field`,
        mypy may throw a `Decorated property not supported` error.
        See [mypy issue #1362](https://github.com/python/mypy/issues/1362), for more information.
        To avoid this error message, add `# type: ignore[prop-decorator]` to the `@computed_field` line.

        [pyright](https://github.com/microsoft/pyright) supports `@computed_field` without error.

    ```python
    import random

    from pydantic import BaseModel, computed_field

    class Square(BaseModel):
        width: float

        @computed_field
        def area(self) -> float:  # converted to a `property` by `computed_field`
            return round(self.width**2, 2)

        @area.setter
        def area(self, new_area: float) -> None:
            self.width = new_area**0.5

        @computed_field(alias='the magic number', repr=False)
        def random_number(self) -> int:
            return random.randint(0, 1_000)

    square = Square(width=1.3)

    # `random_number` does not appear in representation
    print(repr(square))
    #> Square(width=1.3, area=1.69)

    print(square.random_number)
    #> 3

    square.area = 4

    print(square.model_dump_json(by_alias=True))
    #> {"width":2.0,"area":4.0,"the magic number":3}
    ```

    !!! warning "Overriding with `computed_field`"
        You can't override a field from a parent class with a `computed_field` in the child class.
        `mypy` complains about this behavior if allowed, and `dataclasses` doesn't allow this pattern either.
        See the example below:

    ```python
    from pydantic import BaseModel, computed_field

    class Parent(BaseModel):
        a: str

    try:

        class Child(Parent):
            @computed_field
            @property
            def a(self) -> str:
                return 'new a'

    except TypeError as e:
        print(e)
        '''
        Field 'a' of class 'Child' overrides symbol of same name in a parent class. This override with a computed_field is incompatible.
        '''
    ```

    Private properties decorated with `@computed_field` have `repr=False` by default.

    ```python
    from functools import cached_property

    from pydantic import BaseModel, computed_field

    class Model(BaseModel):
        foo: int

        @computed_field
        @cached_property
        def _private_cached_property(self) -> int:
            return -self.foo

        @computed_field
        @property
        def _private_property(self) -> int:
            return -self.foo

    m = Model(foo=1)
    print(repr(m))
    #> Model(foo=1)
    ```

    Args:
        func: the function to wrap.
        alias: alias to use when serializing this computed field, only used when `by_alias=True`
        alias_priority: priority of the alias. This affects whether an alias generator is used
        title: Title to use when including this computed field in JSON Schema
        field_title_generator: A callable that takes a field name and returns title for it.
        description: Description to use when including this computed field in JSON Schema, defaults to the function's
            docstring
        deprecated: A deprecation message (or an instance of `warnings.deprecated` or the `typing_extensions.deprecated` backport).
            to be emitted when accessing the field. Or a boolean. This will automatically be set if the property is decorated with the
            `deprecated` decorator.
        examples: Example values to use when including this computed field in JSON Schema
        json_schema_extra: A dict or callable to provide extra JSON schema properties.
        repr: whether to include this computed field in model repr.
            Default is `False` for private properties and `True` for public properties.
        return_type: optional return for serialization logic to expect when serializing to JSON, if included
            this must be correct, otherwise a `TypeError` is raised.
            If you don't include a return type Any is used, which does runtime introspection to handle arbitrary
            objects.

    Returns:
        A proxy wrapper for the property.
    """

    def dec(f: Any) -> Any:
        nonlocal description, deprecated, return_type, alias_priority
        unwrapped = _decorators.unwrap_wrapped_function(f)

        if description is None and unwrapped.__doc__:
            description = inspect.cleandoc(unwrapped.__doc__)

        if deprecated is None and hasattr(unwrapped, '__deprecated__'):
            deprecated = unwrapped.__deprecated__

        # if the function isn't already decorated with `@property` (or another descriptor), then we wrap it now
        f = _decorators.ensure_property(f)
        alias_priority = (alias_priority or 2) if alias is not None else None

        if repr is None:
            repr_: bool = not _wrapped_property_is_private(property_=f)
        else:
            repr_ = repr

        dec_info = ComputedFieldInfo(
            f,
            return_type,
            alias,
            alias_priority,
            title,
            field_title_generator,
            description,
            deprecated,
            examples,
            json_schema_extra,
            repr_,
        )
        return _decorators.PydanticDescriptorProxy(f, dec_info)

    if func is None:
        return dec
    else:
        return dec(func)

ComputedFieldInfo `dataclass` ¶

ComputedFieldInfo(
    wrapped_property: property,
    return_type: Any,
    alias: str | None,
    alias_priority: int | None,
    title: str | None,
    field_title_generator: (
        Callable[[str, ComputedFieldInfo], str] | None
    ),
    description: str | None,
    deprecated: Deprecated | str | bool | None,
    examples: list[Any] | None,
    json_schema_extra: (
        JsonDict | Callable[[JsonDict], None] | None
    ),
    repr: bool,
)

用于存储来自 @computed_field 的数据，以便在构建 pydantic-core schema 时可以访问它。

属性

名称	类型	描述
`decorator_repr`	`str`	表示装饰器字符串 '@computed_field' 的类变量。
`wrapped_property`	`property`	包装的计算字段属性。
`return_type`	`Any`	计算字段属性的返回值的类型。
`alias`	`str \| None`	序列化期间要使用的属性别名。
`alias_priority`	`int \| None`	别名的优先级。这会影响是否使用别名生成器。
`title`	`str \| None`	要包含在序列化 JSON schema 中的计算字段的标题。
`field_title_generator`	`Callable[[str, ComputedFieldInfo], str] \| None`	一个可调用对象，接受字段名称并返回其标题。
`description`	`str \| None`	要包含在序列化 JSON schema 中的计算字段的描述。
`deprecated`	`Deprecated \| str \| bool \| None`	弃用消息、`warnings.deprecated` 或 `typing_extensions.deprecated` backport 的实例，或布尔值。如果为 `True`，则在访问该字段时将发出默认弃用消息。
`examples`	`list[Any] \| None`	要包含在序列化 JSON schema 中的计算字段的示例值。
`json_schema_extra`	`JsonDict \| Callable[[JsonDict], None] \| None`	用于提供额外 JSON schema 属性的字典或可调用对象。
`repr`	`bool`	一个布尔值，指示是否在 repr 输出中包含该字段。

deprecation_message `property` ¶

deprecation_message: str | None

要发出的弃用消息，如果未设置则为 None。

字段

Field ¶

FieldInfo ¶

from_field staticmethod ¶

from_annotation staticmethod ¶

from_annotated_attribute staticmethod ¶

merge_field_infos staticmethod ¶

deprecation_message property ¶

default_factory_takes_validated_data property ¶

get_default ¶

is_required ¶

rebuild_annotation ¶

apply_typevars_map ¶

PrivateAttr ¶

ModelPrivateAttr ¶

get_default ¶

computed_field ¶

ComputedFieldInfo dataclass ¶

deprecation_message property ¶

from_field `staticmethod` ¶

from_annotation `staticmethod` ¶

from_annotated_attribute `staticmethod` ¶

merge_field_infos `staticmethod` ¶

deprecation_message `property` ¶

default_factory_takes_validated_data `property` ¶

ComputedFieldInfo `dataclass` ¶

deprecation_message `property` ¶