cattrs.gen package

cattrs.gen.make_dict_structure_fn(cl, converter, _cattrs_forbid_extra_keys='from_converter', _cattrs_use_linecache=True, _cattrs_prefer_attrib_converters='from_converter', _cattrs_detailed_validation='from_converter', _cattrs_use_alias='from_converter', _cattrs_include_init_false=False, **kwargs)

Generate a specialized dict structuring function for an attrs class or dataclass.

Any provided overrides are attached to the generated function under the overrides attribute.

Parameters:

• _cattrs_forbid_extra_keys (bool | Literal['from_converter']) – Whether the structuring function should raise a ForbiddenExtraKeysError if unknown keys are encountered.

• _cattrs_use_linecache (bool) – Whether to store the source code in the Python linecache.

• _cattrs_prefer_attrib_converters (bool | Literal['from_converter']) – If an _attrs_ converter is present on a field, use it instead of processing the field normally.

• _cattrs_detailed_validation (bool | Literal['from_converter']) – Whether to use a slower mode that produces more detailed errors.

• _cattrs_use_alias (bool | Literal['from_converter']) – If true, the attribute alias will be used as the dictionary key by default.

• _cattrs_include_init_false (bool) – If true, _attrs_ fields marked as init=False will be included.

• cl (type[T])

• converter (BaseConverter)

• kwargs (AttributeOverride)

Return type:

SimpleStructureHook[Mapping[str, Any], T]

Added in version 23.2.0: _cattrs_use_alias

Added in version 23.2.0: _cattrs_include_init_false

Changed in version 23.2.0: The _cattrs_forbid_extra_keys and _cattrs_detailed_validation parameters take their values from the given converter by default.

Changed in version 24.1.0: The _cattrs_prefer_attrib_converters parameter takes its value from the given converter by default.

Changed in version 25.2.0: The _cattrs_use_alias parameter takes its value from the given converter by default.

Changed in version 26.1.0: typing.Annotated[T, override()] is now recognized and can be used to customize unstructuring.

cattrs.gen.make_dict_structure_fn_from_attrs(attrs, cl, converter, typevar_map={}, _cattrs_forbid_extra_keys='from_converter', _cattrs_use_linecache=True, _cattrs_prefer_attrib_converters='from_converter', _cattrs_detailed_validation='from_converter', _cattrs_use_alias='from_converter', _cattrs_include_init_false=False, **kwargs)

Generate a specialized dict structuring function for a list of attributes.

Usually used as a building block by more specialized hook factories.

Any provided overrides are attached to the generated function under the overrides attribute.

Parameters:

• _cattrs_forbid_extra_keys (bool | Literal['from_converter']) – Whether the structuring function should raise a ForbiddenExtraKeysError if unknown keys are encountered.

• _cattrs_use_linecache (bool) – Whether to store the source code in the Python linecache.

• _cattrs_prefer_attrib_converters (bool | Literal['from_converter']) – If an _attrs_ converter is present on a field, use it instead of processing the field normally.

• _cattrs_detailed_validation (bool | Literal['from_converter']) – Whether to use a slower mode that produces more detailed errors.

• _cattrs_use_alias (bool | Literal['from_converter']) – If true, the attribute alias will be used as the dictionary key by default.

• _cattrs_include_init_false (bool) – If true, _attrs_ fields marked as init=False will be included.

• attrs (list[Attribute])

• cl (type[T])

• converter (BaseConverter)

• typevar_map (dict[str, Any])

• kwargs (AttributeOverride)

Return type:

SimpleStructureHook[Mapping[str, Any], T]

Added in version 24.1.0.

Changed in version 25.2.0: The _cattrs_use_alias parameter takes its value from the given converter by default.

Changed in version 26.1.0: typing.Annotated[T, override()] is now recognized and can be used to customize unstructuring.

cattrs.gen.make_dict_unstructure_fn(cl, converter, _cattrs_omit_if_default=False, _cattrs_use_linecache=True, _cattrs_use_alias='from_converter', _cattrs_include_init_false=False, **kwargs)

Generate a specialized dict unstructuring function for an attrs class or a dataclass.

Any provided overrides are attached to the generated function under the overrides attribute.

Parameters:

• _cattrs_omit_if_default (bool) – if true, attributes equal to their default values will be omitted in the result dictionary.

• _cattrs_use_alias (bool | Literal['from_converter']) – If true, the attribute alias will be used as the dictionary key by default.

• _cattrs_include_init_false (bool) – If true, _attrs_ fields marked as init=False will be included.

• cl (type[T])

• converter (BaseConverter)

• _cattrs_use_linecache (bool)

• kwargs (AttributeOverride)

Return type:

Callable[[T], dict[str, Any]]

Added in version 23.2.0: _cattrs_use_alias

Added in version 23.2.0: _cattrs_include_init_false

Changed in version 25.2.0: The _cattrs_use_alias parameter takes its value from the given converter by default.

Changed in version 26.1.0: typing.Annotated[T, override()] is now recognized and can be used to customize unstructuring.

cattrs.gen.make_dict_unstructure_fn_from_attrs(attrs, cl, converter, typevar_map={}, _cattrs_omit_if_default=False, _cattrs_use_linecache=True, _cattrs_use_alias='from_converter', _cattrs_include_init_false=False, **kwargs)

Generate a specialized dict unstructuring function for a list of attributes.

Usually used as a building block by more specialized hook factories.

Any provided overrides are attached to the generated function under the overrides attribute.

Parameters:

• cl (type[T]) – The class for which the function is generated; used mostly for its name, module name and qualname.

• _cattrs_omit_if_default (bool) – if true, attributes equal to their default values will be omitted in the result dictionary.

• _cattrs_use_alias (bool | Literal['from_converter']) – If true, the attribute alias will be used as the dictionary key by default.

• _cattrs_include_init_false (bool) – If true, _attrs_ fields marked as init=False will be included.

• attrs (list[Attribute])

• converter (BaseConverter)

• typevar_map (dict[str, Any])

• _cattrs_use_linecache (bool)

• kwargs (AttributeOverride)

Return type:

Callable[[T], dict[str, Any]]

Added in version 24.1.0.

Changed in version 25.2.0: The _cattrs_use_alias parameter takes its value from the given converter by default.

Changed in version 26.1.0: typing.Annotated[T, override()] is now recognized and can be used to customize unstructuring.

Changed in version 26.1.0: When _cattrs_omit_if_default is true and the attribute has an attrs converter specified, the converter is applied to the default value before checking if it is equal to the attribute’s value.

cattrs.gen.make_hetero_tuple_unstructure_fn(cl, converter, unstructure_to=None, type_args=None)

Generate a specialized unstructure function for a heterogenous tuple.

Parameters:

• type_args (tuple | None) – If provided, override the type arguments.

• cl (Any)

• converter (BaseConverter)

• unstructure_to (Any)

Return type:

HeteroTupleUnstructureFn

cattrs.gen.make_iterable_unstructure_fn(cl, converter, unstructure_to=None)

A hook factory for unstructuring iterables.

Parameters:

• unstructure_to (Any) – Force unstructuring to this type, if provided.

• cl (Any)

• converter (BaseConverter)

Return type:

UnstructureHook

Changed in version 24.2.0: typing.NoDefault is now correctly handled as Any.

cattrs.gen.make_mapping_structure_fn(cl, converter, structure_to=<class 'dict'>, key_type=NOTHING, val_type=NOTHING, detailed_validation='from_converter')

Generate a specialized structure function for a mapping.

Parameters:

• cl (type[T])

• converter (BaseConverter)

• structure_to (type)

• detailed_validation (bool | Literal['from_converter'])

Return type:

SimpleStructureHook[Mapping[Any, Any], T]

cattrs.gen.make_mapping_unstructure_fn(cl, converter, unstructure_to=None, key_handler=None)

Generate a specialized unstructure function for a mapping.

Parameters:

• unstructure_to (Any) – The class to unstructure to; defaults to the same class as the mapping being unstructured.

• cl (Any)

• converter (BaseConverter)

• key_handler (Callable[[Any, Any | None], Any] | None)

Return type:

MappingUnstructureFn

Submodules

cattrs.gen.typeddicts module

cattrs.gen.typeddicts.make_dict_structure_fn(cl, converter, _cattrs_forbid_extra_keys='from_converter', _cattrs_use_linecache=True, _cattrs_detailed_validation='from_converter', **kwargs)

Generate a specialized dict structuring function for typed dicts.

Parameters:

• cl (Any) – A TypedDict class.

• converter (BaseConverter) – A Converter instance to use for structuring nested fields.

• kwargs (AttributeOverride) – A mapping of field names to an AttributeOverride, for customization.

• _cattrs_detailed_validation (bool | Literal['from_converter']) – Whether to use a slower mode that produces more detailed errors.

• _cattrs_forbid_extra_keys (bool | Literal['from_converter']) – Whether the structuring function should raise a ForbiddenExtraKeysError if unknown keys are encountered.

• _cattrs_detailed_validation – Whether to store the generated code in the _linecache_, for easier debugging and better stack traces.

• _cattrs_use_linecache (bool)

Return type:

Callable[[dict, Any], Any]

Changed in version 23.2.0: The _cattrs_forbid_extra_keys and _cattrs_detailed_validation parameters take their values from the given converter by default.

cattrs.gen.typeddicts.make_dict_unstructure_fn(cl, converter, _cattrs_use_linecache=True, **kwargs)

Generate a specialized dict unstructuring function for a TypedDict.

Parameters:

• cl (type[T]) – A TypedDict class.

• converter (BaseConverter) – A Converter instance to use for unstructuring nested fields.

• kwargs (AttributeOverride) – A mapping of field names to an AttributeOverride, for customization.

• _cattrs_detailed_validation – Whether to store the generated code in the _linecache_, for easier debugging and better stack traces.

• _cattrs_use_linecache (bool)

Return type:

Callable[[T], dict[str, Any]]