Fields

Defining fields on models.

FieldInfo

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.

Caution

The FieldInfo class is meant to expose information about a field in a Pydantic model or dataclass. FieldInfo instances shouldn’t be instantiated directly, nor mutated.

If you need to derive a new model from another one and are willing to alter FieldInfo instances, refer to this dynamic model example.

Attributes

annotation

The type annotation of the field.

Type: type[Any] | None

default

The default value of the field.

Type: Any

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.

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

alias

The alias name of the field.

Type: str | None

alias_priority

The priority of the field’s alias.

Type: int | None

validation_alias

The validation alias of the field.

Type: str | AliasPath | AliasChoices | None

serialization_alias

The serialization alias of the field.

Type: str | None

title

The title of the field.

Type: str | None

field_title_generator

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

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

description

The description of the field.

Type: str | None

examples

List of examples of the field.

Type: list[Any] | None

exclude

Whether to exclude the field from the model serialization.

Type: bool | None

exclude_if

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

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

discriminator

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

Type: str | types.Discriminator | None

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.

Type: Deprecated | str | bool | None

json_schema_extra

A dict or callable to provide extra JSON schema properties.

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

frozen

Whether the field is frozen.

Type: bool | None

validate_default

Whether to validate the default value of the field.

Type: bool | None

repr

Whether to include the field in representation of the model.

Type: bool

init

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

Type: bool | None

init_var

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

Type: bool | None

kw_only

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

Type: bool | None

metadata

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]

Methods

_construct

@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.

Returns

Self — The final merged FieldInfo instance.

Parameters

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.

_from_dataclass_field

@staticmethod

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

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

Returns

FieldInfo — The corresponding FieldInfo instance.

Parameters

dc_field : DataclassField[Any]

The dataclasses.Field instance to convert.

Raises

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

_collect_metadata

@staticmethod

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

Collect annotations from kwargs.

Returns

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

Parameters

kwargs : dict[str, Any]

Keyword arguments passed to the function.

get_default

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).

Returns

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

Parameters

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.

is_required

def is_required() -> bool

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

Returns

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

asdict

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).

Returns

_FieldInfoAsDict

_copy

def _copy() -> Self

Return a copy of the FieldInfo instance.

Returns

Self

ModelPrivateAttr

Bases: Representation

A descriptor for private attributes in class models.

Caution

You generally shouldn’t be creating ModelPrivateAttr instances directly, instead use pydantic.fields.PrivateAttr. (This is similar to FieldInfo vs. Field.)

Attributes

default

The default value of the attribute if not provided.

default_factory

A callable function that generates the default value of the attribute if not provided.

Methods

__getattr__

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.

Returns

Any

__set_name__

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

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

Returns

None

get_default

def get_default() -> 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

Any — The default value of the object.

ComputedFieldInfo

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

Attributes

decorator_repr

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

Type: str

wrapped_property

The wrapped computed field property.

Type: property

return_type

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

Type: Any

alias

The alias of the property to be used during serialization.

Type: str | None

alias_priority

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

Type: int | None

title

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

Type: str | None

field_title_generator

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

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

description

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

Type: str | None

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.

Type: Deprecated | str | bool | None

examples

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

Type: list[Any] | None

json_schema_extra

A dict or callable to provide extra JSON schema properties.

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

repr

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

Type: bool

Methods

_update_from_config

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.

Returns

None

_apply_alias_generator

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

Apply an alias generator to aliases if appropriate.

Returns

None

Parameters

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.

Field

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

Usage Documentation

Fields

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.

Returns

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

Parameters

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.

Deprecated

The extra kwargs is deprecated. Use json_schema_extra instead.

PrivateAttr

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

Usage Documentation

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.

Returns

Any — An instance of ModelPrivateAttr class.

Parameters

default : Any Default: PydanticUndefined

The attribute’s default value. Defaults to Undefined.

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

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 : Literal[False] Default: False

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

Raises

• ValueError — If both default and default_factory are set.

computed_field

def computed_field(func: PropertyT) -> PropertyT
def 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]

Usage Documentation

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.

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.

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, for more information. To avoid this error message, add # type: ignore[prop-decorator] to the @computed_field line.

pyright supports @computed_field without error.

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}

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:

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)

Returns

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

Parameters

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

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.