Fields

Defining fields on models.

Bases: Representation

This class holds information about a field.

FieldInfo is used for any field definition regardless of whether the Field() function is explicitly used.

The type annotation of the field.

Type: type[Any] | None

The default value of the field.

Type: Any

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.

Type: Callable[[], Any] | Callable[[dict[str, Any]], Any] | None

The alias name of the field.

Type: str | None

The priority of the field’s alias.

Type: int | None

The validation alias of the field.

Type: str | AliasPath | AliasChoices | None

The serialization alias of the field.

Type: str | None

The title of the field.

Type: str | None

A callable that takes a field name and returns title for it.

Type: Callable[[str, FieldInfo], str] | None

The description of the field.

Type: str | None

List of examples of the field.

Type: list[Any] | None

Whether to exclude the field from the model serialization.

Type: bool | None

A callable that determines whether to exclude a field during serialization based on its value.

Type: Callable[[Any], bool] | None

Field name or Discriminator for discriminating the type in a tagged union.

Type: str | types.Discriminator | None

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.

Type: Deprecated | str | bool | None

A dict or callable to provide extra JSON schema properties.

Type: JsonDict | Callable[[JsonDict], None] | None

Whether the field is frozen.

Type: bool | None

Whether to validate the default value of the field.

Type: bool | None

Whether to include the field in representation of the model.

Type: bool

Whether the field should be included in the constructor of the dataclass.

Type: bool | None

Whether the field should only be included in the constructor of the dataclass, and not stored.

Type: bool | None

Whether the field should be a keyword-only argument in the constructor of the dataclass.

Type: bool | None

The metadata list. Contains all the data that isn’t expressed as direct FieldInfo attributes, including:

• Type-specific constraints, such as gt or min_length (these are converted to metadata classes such as annotated_types.Gt).
• Any other arbitrary object used within Annotated metadata (e.g. custom types handlers or any object not recognized by Pydantic).

Type: list[Any]

The deprecation message to be emitted, or None if not set.

Type: str | None

Whether the provided default factory callable has a validated data parameter.

Returns None if no default factory is set.

Type: bool | None

@classmethod

def _construct(cls, metadata: list[Any], **attr_overrides: Any) -> Self

Construct the final FieldInfo instance, by merging the possibly existing FieldInfo instances from the metadata.

With the following example:

class Model(BaseModel):
    f: Annotated[int, Gt(1), Field(description='desc', lt=2)]

metadata refers to the metadata elements of the Annotated form. This metadata is iterated over from left to right:

• If the element is a Field() function (which is itself a FieldInfo instance), the field attributes (such as description) are saved to be set on the final FieldInfo instance. On the other hand, some kwargs (such as lt) are stored as metadata (see FieldInfo.__init__(), calling FieldInfo._collect_metadata()). In this case, the final metadata list is extended with the one from this instance.
• Else, the element is considered as a single metadata object, and is appended to the final metadata list.

Self — The final merged FieldInfo instance.

metadata : list[Any]

The list of metadata elements to merge together. If the FieldInfo instance to be constructed is for a field with an assigned Field(), this Field() assignment should be added as the last element of the provided metadata.

**attr_overrides : Any Default: {}

Extra attributes that should be set on the final merged FieldInfo instance.

@staticmethod

def _from_dataclass_field(dc_field: DataclassField[Any]) -> FieldInfo

Return a new FieldInfo instance from a dataclasses.Field instance.

FieldInfo — The corresponding FieldInfo instance.

dc_field : DataclassField[Any]

The dataclasses.Field instance to convert.

• TypeError — If any of the FieldInfo kwargs does not match the dataclass.Field kwargs.

@staticmethod

def _collect_metadata(kwargs: dict[str, Any]) -> list[Any]

Collect annotations from kwargs.

list[Any] — A list of metadata objects - a combination of annotated_types.BaseMetadata and PydanticMetadata.

kwargs : dict[str, Any]

Keyword arguments passed to the function.

def get_default(
    *,
    call_default_factory: Literal[True],
    validated_data: dict[str, Any] | None = None,
) -> Any
def get_default(*, call_default_factory: Literal[False] = ...) -> 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).

Any — The default value, calling the default factory if requested or PydanticUndefined if not set.

call_default_factory : bool Default: False

Whether to call the default factory or not.

validated_data : dict[str, Any] | None Default: None

The already validated data to be passed to the default factory.

def is_required() -> bool

Check if the field is required (i.e., does not have a default value or factory).

bool — True if the field is required, False otherwise.

def asdict() -> _FieldInfoAsDict

Return a dictionary representation of the FieldInfo instance.

The returned value is a dictionary with three items:

• annotation: The type annotation of the field.
• metadata: The metadata list.
• attributes: A mapping of the remaining FieldInfo attributes to their values (e.g. alias, title).

_FieldInfoAsDict

def _copy() -> Self

Return a copy of the FieldInfo instance.

Self

Bases: Representation

A descriptor for private attributes in class models.

The default value of the attribute if not provided.

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 validated data (the model’s __dict__) and the already initialized private attributes.

Whether the provided default factory callable has a validated data parameter.

Returns None if no default factory is set.

Type: bool | None

def __getattr__(item: str) -> Any

This function improves compatibility with custom descriptors by ensuring delegation happens as expected when the default value of a private attribute is a descriptor.

Any

def __set_name__(cls: type[Any], name: str) -> None

Preserve __set_name__ protocol defined in https://peps.python.org/pep-0487.

None

def get_default(
    *,
    call_default_factory: Literal[True],
    validated_data: dict[str, Any] | None = None,
) -> Any
def get_default(*, call_default_factory: Literal[False] = ...) -> 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).

Any — The default value, calling the default factory if requested or None if not set.

call_default_factory : bool Default: False

Whether to call the default factory or not.

validated_data : dict[str, Any] | None Default: None

The already validated data to be passed to the default factory.

A container for data from @computed_field so that we can access it while building the pydantic-core schema.

A class variable representing the decorator string, ‘@computed_field’.

Type: str

The wrapped computed field property.

Type: property

The type of the computed field property’s return value.

Type: Any

The alias of the property to be used during serialization.

Type: str | None

The priority of the alias. This affects whether an alias generator is used.

Type: int | None

Title of the computed field to include in the serialization JSON schema.

Type: str | None

A callable that takes a field name and returns title for it.

Type: Callable[[str, ComputedFieldInfo], str] | None

Description of the computed field to include in the serialization JSON schema.

Type: str | None

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.

Type: Deprecated | str | bool | None

Example values of the computed field to include in the serialization JSON schema.

Type: list[Any] | None

A dict or callable to provide extra JSON schema properties.

Type: JsonDict | Callable[[JsonDict], None] | None

A boolean indicating whether to include the field in the repr output.

Type: bool

The deprecation message to be emitted, or None if not set.

Type: str | None

def _update_from_config(config_wrapper: ConfigWrapper, name: str) -> None

Update the instance from the configuration set on the class this computed field belongs to.

None

def _apply_alias_generator(
    alias_generator: Callable[[str], str] | AliasGenerator,
    name: str,
) -> None

Apply an alias generator to aliases if appropriate.

None

alias_generator : Callable[[str], str] | AliasGenerator

A callable that takes a string and returns a string, or an AliasGenerator instance.

name : str

The name of the computed field from which to generate the alias.

def 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,
    exclude_if: Callable[[Any], 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 | re.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
def Field(
    default: Any,
    *,
    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,
    exclude_if: Callable[[Any], 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: Literal[True],
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | re.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
def 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,
    exclude_if: Callable[[Any], 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: Literal[False] = ...,
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | re.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],
) -> _T
def Field(
    *,
    default_factory: Callable[[], Any] | Callable[[dict[str, Any]], Any],
    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,
    exclude_if: Callable[[Any], 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: Literal[True],
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | re.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
def 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,
    exclude_if: Callable[[Any], 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: Literal[False] | None = _Unset,
    repr: bool = _Unset,
    init: bool | None = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | re.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],
) -> _T
def 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,
    exclude_if: Callable[[Any], 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 | re.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

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.

Any — A new FieldInfo. The return annotation is Any so Field can be used on type-annotated fields without causing a type error.

default : Any Default: PydanticUndefined

Default value if the field is not set.

default_factory : Callable[[], Any] | Callable[[dict[str, Any]], Any] | None Default: _Unset

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 : str | None Default: _Unset

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 : int | None Default: _Unset

Priority of the alias. This affects whether an alias generator is used.

validation_alias : str | AliasPath | AliasChoices | None Default: _Unset

Like alias, but only affects validation, not serialization.

serialization_alias : str | None Default: _Unset

Like alias, but only affects serialization, not validation.

title : str | None Default: _Unset

Human-readable title.

field_title_generator : Callable[[str, FieldInfo], str] | None Default: _Unset

A callable that takes a field name and returns title for it.

description : str | None Default: _Unset

Human-readable description.

examples : list[Any] | None Default: _Unset

Example values for this field.

exclude : bool | None Default: _Unset

Whether to exclude the field from the model serialization.

exclude_if : Callable[[Any], bool] | None Default: _Unset

A callable that determines whether to exclude a field during serialization based on its value.

discriminator : str | types.Discriminator | None Default: _Unset

Field name or Discriminator for discriminating the type in a tagged union.

deprecated : Deprecated | str | bool | None Default: _Unset

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 : JsonDict | Callable[[JsonDict], None] | None Default: _Unset

A dict or callable to provide extra JSON schema properties.

frozen : bool | None Default: _Unset

Whether the field is frozen. If true, attempts to change the value on an instance will raise an error.

validate_default : bool | None Default: _Unset

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 : bool Default: _Unset

A boolean indicating whether to include the field in the __repr__ output.

init : bool | None Default: _Unset

Whether the field should be included in the constructor of the dataclass. (Only applies to dataclasses.)

init_var : bool | None Default: _Unset

Whether the field should only be included in the constructor of the dataclass. (Only applies to dataclasses.)

kw_only : bool | None Default: _Unset

Whether the field should be a keyword-only argument in the constructor of the dataclass. (Only applies to dataclasses.)

coerce_numbers_to_str : bool | None Default: _Unset

Whether to enable coercion of any Number type to str (not applicable in strict mode).

strict : bool | None Default: _Unset

If True, strict validation is applied to the field. See Strict Mode for details.

gt : annotated_types.SupportsGt | None Default: _Unset

Greater than. If set, value must be greater than this. Only applicable to numbers.

ge : annotated_types.SupportsGe | None Default: _Unset

Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers.

lt : annotated_types.SupportsLt | None Default: _Unset

Less than. If set, value must be less than this. Only applicable to numbers.

le : annotated_types.SupportsLe | None Default: _Unset

Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers.

multiple_of : float | None Default: _Unset

Value must be a multiple of this. Only applicable to numbers.

min_length : int | None Default: _Unset

Minimum length for iterables.

max_length : int | None Default: _Unset

Maximum length for iterables.

pattern : str | re.Pattern[str] | None Default: _Unset

Pattern for strings (a regular expression).

allow_inf_nan : bool | None Default: _Unset

Allow inf, -inf, nan. Only applicable to float and Decimal numbers.

max_digits : int | None Default: _Unset

Maximum number of allow digits for strings.

decimal_places : int | None Default: _Unset

Maximum number of decimal places allowed for numbers.

union_mode : Literal[‘smart’, ‘left_to_right’] Default: _Unset

The strategy to apply when validating a union. Can be smart (the default), or left_to_right. See Union Mode for details.

fail_fast : bool | None Default: _Unset

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 : Unpack[_EmptyKwargs] Default: {}

(Deprecated) Extra fields that will be included in the JSON schema.

def PrivateAttr(default: _T, *, init: Literal[False] = False) -> _T
def PrivateAttr(
    *,
    default_factory: Callable[[], _T] | Callable[[dict[str, Any]], _T],
    init: Literal[False] = False,
) -> _T
def PrivateAttr(*, init: Literal[False] = False) -> Any

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.

Any — An instance of ModelPrivateAttr class.

default : Any Default: PydanticUndefined

The attribute’s default value. Defaults to Undefined.

default_factory : Callable[[], Any] | Callable[[dict[str, Any]], Any] | None Default: None

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 validated data (the model’s __dict__) and the already initialized private attributes. If both default and default_factory are set, an error will be raised.

init : Literal[False] Default: False

Whether the attribute should be included in the constructor of the dataclass. Always False.

• ValueError — If both default and default_factory are set.

def computed_field(func: PropertyT, /) -> PropertyT
def computed_field(
    *,
    alias: str | None = None,
    alias_priority: int | None = None,
    exclude_if: Callable[[Any], bool] | 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]

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.

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.

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}

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.

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)

PropertyT | Callable[[PropertyT], PropertyT] — A proxy wrapper for the property.

func : PropertyT | None Default: None

the function to wrap.

alias : str | None Default: None

alias to use when serializing this computed field, only used when by_alias=True

alias_priority : int | None Default: None

priority of the alias. This affects whether an alias generator is used

exclude_if : Callable[[Any], bool] | None Default: None

A callable that determines whether to exclude this computed field during serialization based on its value.

title : str | None Default: None

Title to use when including this computed field in JSON Schema

field_title_generator : Callable[[str, ComputedFieldInfo], str] | None Default: None

A callable that takes a field name and returns title for it.

description : str | None Default: None

Description to use when including this computed field in JSON Schema, defaults to the function’s docstring

deprecated : Deprecated | str | bool | None Default: None

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 : list[Any] | None Default: None

Example values to use when including this computed field in JSON Schema

json_schema_extra : JsonDict | Callable[[JsonDict], None] | None Default: None

A dict or callable to provide extra JSON schema properties.

repr : bool | None Default: None

whether to include this computed field in model repr. Default is False for private properties and True for public properties.

return_type : Any Default: PydanticUndefined

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.

Was this page helpful?