pydantic.dataclasses

Provide an enhanced dataclass that performs validation.

ConfigDict

Bases: TypedDict

A dictionary-like class for configuring Pydantic models.

Attributes

title

Type: str | None

str_to_lower

Type: bool

str_to_upper

Type: bool

str_strip_whitespace

Type: bool

str_min_length

Type: int

str_max_length

Type: int | None

extra

Type: ExtraValues | None

frozen

Type: bool

populate_by_name

Type: bool

use_enum_values

Type: bool

validate_assignment

Type: bool

arbitrary_types_allowed

Type: bool

from_attributes

Type: bool

loc_by_alias

Type: bool

alias_generator

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

ignored_types

Type: tuple[type, ...]

allow_inf_nan

Type: bool

json_schema_extra

Type: dict[str, object] | JsonSchemaExtraCallable | None

strict

Type: bool

revalidate_instances

Type: Literal['always', 'never', 'subclass-instances']

ser_json_timedelta

Type: Literal['iso8601', 'float']

ser_json_bytes

Type: Literal['utf8', 'base64']

validate_default

Type: bool

validate_return

Type: bool

protected_namespaces

Type: tuple[str, ...]

hide_input_in_errors

Type: bool

PydanticDataclass

Bases: StandardDataclass, Protocol

A protocol containing attributes only available once a class has been decorated as a Pydantic dataclass.

getattr_migration

def getattr_migration(module: str) -> Callable[[str], Any]

Implement PEP 562 for objects that were either moved or removed on the migration to V2.

Returns

Callable[[str], Any] — A callable that will raise an error if the object is not found.

Parameters

module : str

The module name.

Field

def Field(
    default: Any = PydanticUndefined,
    default_factory: typing.Callable[[], 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,
    description: str | None = _Unset,
    examples: list[Any] | None = _Unset,
    exclude: bool | None = _Unset,
    include: bool | None = _Unset,
    discriminator: str | None = _Unset,
    json_schema_extra: dict[str, Any] | None = _Unset,
    frozen: bool | None = _Unset,
    validate_default: bool | None = _Unset,
    repr: bool = _Unset,
    init_var: bool | None = _Unset,
    kw_only: bool | None = _Unset,
    pattern: str | None = _Unset,
    strict: bool | None = _Unset,
    gt: float | None = _Unset,
    ge: float | None = _Unset,
    lt: float | None = _Unset,
    le: float | 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,
    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.

Returns

Any — The generated FieldInfo object

Parameters

default : Any Default: PydanticUndefined

Default value if the field is not set.

default_factory : typing.Callable[[], Any] | None Default: _Unset

A callable to generate the default value, such as :func:~datetime.utcnow.

alias : str | None Default: _Unset

An alternative name for the attribute.

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

‘Whitelist’ validation step. The field will be the single one allowed by the alias or set of aliases defined.

serialization_alias : str | None Default: _Unset

‘Blacklist’ validation step. The vanilla field will be the single one of the alias’ or set of aliases’ fields and all the other fields will be ignored at serialization time.

title : str | None Default: _Unset

Human-readable title.

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

include : bool | None Default: _Unset

Whether to include the field in the model schema.

discriminator : str | None Default: _Unset

Field name for discriminating the type in a tagged union.

json_schema_extra : dict[str, Any] | None Default: _Unset

Any additional JSON schema data for the schema property.

frozen : bool | None Default: _Unset

Whether the field is frozen.

validate_default : bool | None Default: _Unset

Run validation that isn’t only checking existence of defaults. True by default.

repr : bool Default: _Unset

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

init_var : bool | None Default: _Unset

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

kw_only : bool | None Default: _Unset

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

strict : bool | None Default: _Unset

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

gt : float | None Default: _Unset

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

ge : float | None Default: _Unset

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

lt : float | None Default: _Unset

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

le : float | 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 strings.

max_length : int | None Default: _Unset

Maximum length for strings.

pattern : str | None Default: _Unset

Pattern for strings.

allow_inf_nan : bool | None Default: _Unset

Allow inf, -inf, nan. Only applicable to 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.

extra : Unpack[_EmptyKwargs] Default: \{\}

Include extra fields used by the JSON schema.

dataclass

def dataclass(
    init: Literal[False] = False,
    repr: bool = True,
    eq: bool = True,
    order: bool = False,
    unsafe_hash: bool = False,
    frozen: bool = False,
    config: ConfigDict | type[object] | None = None,
    validate_on_init: bool | None = None,
    kw_only: bool = ...,
    slots: bool = ...,
) -> Callable[[type[_T]], type[PydanticDataclass]]
def dataclass(
    _cls: type[_T],
    init: Literal[False] = False,
    repr: bool = True,
    eq: bool = True,
    order: bool = False,
    unsafe_hash: bool = False,
    frozen: bool = False,
    config: ConfigDict | type[object] | None = None,
    validate_on_init: bool | None = None,
    kw_only: bool = ...,
    slots: bool = ...,
) -> type[PydanticDataclass]
def dataclass(
    init: Literal[False] = False,
    repr: bool = True,
    eq: bool = True,
    order: bool = False,
    unsafe_hash: bool = False,
    frozen: bool = False,
    config: ConfigDict | type[object] | None = None,
    validate_on_init: bool | None = None,
) -> Callable[[type[_T]], type[PydanticDataclass]]
def dataclass(
    _cls: type[_T],
    init: Literal[False] = False,
    repr: bool = True,
    eq: bool = True,
    order: bool = False,
    unsafe_hash: bool = False,
    frozen: bool = False,
    config: ConfigDict | type[object] | None = None,
    validate_on_init: bool | None = None,
) -> type[PydanticDataclass]

A decorator used to create a Pydantic-enhanced dataclass, similar to the standard Python dataclass, but with added validation.

This function should be used similarly to dataclasses.dataclass.

Returns

Callable[[type[_T]], type[PydanticDataclass]] | type[PydanticDataclass] — A decorator that accepts a class as its argument and returns a Pydantic dataclass.

Parameters

_cls : type[_T] | None Default: None

The target dataclass.

init : Literal[False] Default: False

Included for signature compatibility with dataclasses.dataclass, and is passed through to dataclasses.dataclass when appropriate. If specified, must be set to False, as pydantic inserts its own __init__ function.

repr : bool Default: True

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

eq : bool Default: True

Determines if a __eq__ should be generated for the class.

order : bool Default: False

Determines if comparison magic methods should be generated, such as __lt__, but not __eq__.

unsafe_hash : bool Default: False

Determines if an unsafe hashing function should be included in the class.

frozen : bool Default: False

Determines if the generated class should be a ‘frozen’ dataclass, which does not allow its attributes to be modified from its constructor.

config : ConfigDict | type[object] | None Default: None

A configuration for the dataclass generation.

validate_on_init : bool | None Default: None

A deprecated parameter included for backwards compatibility; in V2, all Pydantic dataclasses are validated on init.

kw_only : bool Default: False

Determines if __init__ method parameters must be specified by keyword only. Defaults to False.

slots : bool Default: False

Determines if the generated class should be a ‘slots’ dataclass, which does not allow the addition of new attributes after instantiation.

Raises

AssertionError — Raised if init is not False or validate_on_init is False.

rebuild_dataclass

def rebuild_dataclass(
    cls: type[PydanticDataclass],
    force: bool = False,
    raise_errors: bool = True,
    _parent_namespace_depth: int = 2,
    _types_namespace: dict[str, Any] | None = None,
) -> bool | None

Try to rebuild the pydantic-core schema for the dataclass.

This may be necessary when one of the annotations is a ForwardRef which could not be resolved during the initial attempt to build the schema, and automatic rebuilding fails.

This is analogous to BaseModel.model_rebuild.

Returns

bool | None — Returns None if the schema is already “complete” and rebuilding was not required. bool | None — If rebuilding was required, returns True if rebuilding was successful, otherwise False.

Parameters

cls : type[PydanticDataclass]

The class to build the dataclass core schema for.

force : bool Default: False

Whether to force the rebuilding of the model schema, defaults to False.

raise_errors : bool Default: True

Whether to raise errors, defaults to True.

_parent_namespace_depth : int Default: 2

The depth level of the parent namespace, defaults to 2.

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

The types namespace, defaults to None.