cattrs package#

Subpackages#

Submodules#

cattrs.converters module#

class cattrs.converters.BaseConverter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, prefer_attrib_converters=False, detailed_validation=True)[source]#

Bases: object

Converts between structured and unstructured data.

Parameters:

  • dict_factory (Callable[[], Any]) –

  • unstruct_strat (UnstructureStrategy) –

  • prefer_attrib_converters (bool) –

  • detailed_validation (bool) –

copy(dict_factory=None, unstruct_strat=None, prefer_attrib_converters=None, detailed_validation=None)[source]#
Parameters:

  • dict_factory (Callable[[], Any] | None) –

  • unstruct_strat (UnstructureStrategy | None) –

  • prefer_attrib_converters (bool | None) –

  • detailed_validation (bool | None) –

Return type:

BaseConverter

detailed_validation#
register_structure_hook(cl, func)[source]#

Register a primitive-to-class converter function for a type.

The converter function should take two arguments:

  • a Python object to be converted,

  • the type to convert to

and return the instance of the class. The type may seem redundant, but is sometimes needed (for example, when dealing with generic classes).

Parameters:

  • cl (Any) –

  • func (Callable[[Any, Type[T]], T]) –

Return type:

None

register_structure_hook_factory(predicate, factory)[source]#

Register a hook factory for a given predicate.

A predicate is a function that, given a type, returns whether the factory can produce a hook for that type.

A factory is a callable that, given a type, produces a structuring hook for that type. This structuring hook will be cached.

Parameters:

  • predicate (Callable[[Any], bool]) –

  • factory (Callable[[Any], Callable[[Any, Any], Any]]) –

Return type:

None

register_structure_hook_func(check_func, func)[source]#

Register a class-to-primitive converter function for a class, using a function to check if it’s a match.

Parameters:

  • check_func (Callable[[Type[T]], bool]) –

  • func (Callable[[Any, Type[T]], T]) –

Return type:

None

register_unstructure_hook(cls, func)[source]#

Register a class-to-primitive converter function for a class.

The converter function should take an instance of the class and return its Python equivalent.

Parameters:

  • cls (Any) –

  • func (Callable[[Any], Any]) –

Return type:

None

register_unstructure_hook_factory(predicate, factory)[source]#

Register a hook factory for a given predicate.

A predicate is a function that, given a type, returns whether the factory can produce a hook for that type.

A factory is a callable that, given a type, produces an unstructuring hook for that type. This unstructuring hook will be cached.

Parameters:

  • predicate (Callable[[Any], bool]) –

  • factory (Callable[[Any], Callable[[Any], Any]]) –

Return type:

None

register_unstructure_hook_func(check_func, func)[source]#

Register a class-to-primitive converter function for a class, using a function to check if it’s a match.

Parameters:

  • check_func (Callable[[Any], bool]) –

  • func (Callable[[Any], Any]) –

Return type:

None

structure(obj, cl)[source]#

Convert unstructured Python data structures to structured data.

Parameters:

  • obj (Any) –

  • cl (Type[T]) –

Return type:

T

structure_attrs_fromdict(obj, cl)[source]#

Instantiate an attrs class from a mapping (dict).

Parameters:

  • obj (Mapping[str, Any]) –

  • cl (Type[T]) –

Return type:

T

structure_attrs_fromtuple(obj, cl)[source]#

Load an attrs class from a sequence (tuple).

Parameters:

  • obj (Tuple[Any, ...]) –

  • cl (Type[T]) –

Return type:

T

property unstruct_strat: UnstructureStrategy#

The default way of unstructuring attrs classes.

unstructure(obj, unstructure_as=None)[source]#
Parameters:

  • obj (Any) –

  • unstructure_as (Any | None) –

Return type:

Any

unstructure_attrs_asdict(obj)[source]#

Our version of attrs.asdict, so we can call back to us.

Parameters:

obj (Any) –

Return type:

Dict[str, Any]

unstructure_attrs_astuple(obj)[source]#

Our version of attrs.astuple, so we can call back to us.

Parameters:

obj (Any) –

Return type:

Tuple[Any, …]

class cattrs.converters.Converter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, omit_if_default=False, forbid_extra_keys=False, type_overrides={}, unstruct_collection_overrides={}, prefer_attrib_converters=False, detailed_validation=True)[source]#

Bases: BaseConverter

A converter which generates specialized un/structuring functions.

Parameters:

  • dict_factory (Callable[[], Any]) –

  • unstruct_strat (UnstructureStrategy) –

  • omit_if_default (bool) –

  • forbid_extra_keys (bool) –

  • type_overrides (Mapping[Type, AttributeOverride]) –

  • unstruct_collection_overrides (Mapping[Type, Callable]) –

  • prefer_attrib_converters (bool) –

  • detailed_validation (bool) –

copy(dict_factory=None, unstruct_strat=None, omit_if_default=None, forbid_extra_keys=None, type_overrides=None, unstruct_collection_overrides=None, prefer_attrib_converters=None, detailed_validation=None)[source]#
Parameters:

  • dict_factory (Callable[[], Any] | None) –

  • unstruct_strat (UnstructureStrategy | None) –

  • omit_if_default (bool | None) –

  • forbid_extra_keys (bool | None) –

  • type_overrides (Mapping[Type, AttributeOverride] | None) –

  • unstruct_collection_overrides (Mapping[Type, Callable] | None) –

  • prefer_attrib_converters (bool | None) –

  • detailed_validation (bool | None) –

Return type:

Converter

forbid_extra_keys#
gen_structure_annotated(type)[source]#
gen_structure_attrs_fromdict(cl)[source]#
Parameters:

cl (Type[T]) –

Return type:

Callable[[Mapping[str, Any], Any], T]

gen_structure_counter(cl)[source]#
Parameters:

cl (Any) –

Return type:

Callable[[Mapping[Any, Any], Any], T]

gen_structure_mapping(cl)[source]#
Parameters:

cl (Any) –

Return type:

Callable[[Mapping[Any, Any], Any], T]

gen_structure_typeddict(cl)[source]#

Generate a TypedDict structure function.

Also apply converter-scored modifications.

Parameters:

cl (Any) –

Return type:

Callable[[Dict], Dict]

gen_unstructure_annotated(type)[source]#
gen_unstructure_attrs_fromdict(cl)[source]#
Parameters:

cl (Type[T]) –

Return type:

Callable[[T], Dict[str, Any]]

gen_unstructure_hetero_tuple(cl, unstructure_to=None)[source]#
Parameters:

  • cl (Any) –

  • unstructure_to (Any | None) –

Return type:

Callable[[Tuple[Any, …]], Any]

gen_unstructure_iterable(cl, unstructure_to=None)[source]#
Parameters:

  • cl (Any) –

  • unstructure_to (Any | None) –

Return type:

Callable[[Iterable[Any]], Any]

gen_unstructure_mapping(cl, unstructure_to=None, key_handler=None)[source]#
Parameters:

  • cl (Any) –

  • unstructure_to (Any | None) –

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

Return type:

Callable[[Mapping[Any, Any]], Any]

gen_unstructure_typeddict(cl)[source]#

Generate a TypedDict unstructure function.

Also apply converter-scored modifications.

Parameters:

cl (Any) –

Return type:

Callable[[Dict], Dict]

get_structure_newtype(type)[source]#
Parameters:

type (Type[T]) –

Return type:

Callable[[Any, Any], T]

omit_if_default#
type_overrides#
cattrs.converters.GenConverter#

alias of Converter

class cattrs.converters.UnstructureStrategy(value)[source]#

Bases: Enum

attrs classes unstructuring strategies.

AS_DICT = 'asdict'#
AS_TUPLE = 'astuple'#
cattrs.converters.is_attrs_union(typ)[source]#
Parameters:

typ (Type) –

Return type:

bool

cattrs.converters.is_attrs_union_or_none(typ)[source]#
Parameters:

typ (Type) –

Return type:

bool

cattrs.converters.is_literal_containing_enums(typ)[source]#
Parameters:

typ (Type) –

Return type:

bool

cattrs.converters.is_optional(typ)[source]#
Parameters:

typ (Type) –

Return type:

bool

cattrs.disambiguators module#

Utilities for union (sum type) disambiguation.

cattrs.disambiguators.create_uniq_field_dis_func(*classes)[source]#

Given attr classes, generate a disambiguation function.

The function is based on unique fields.

Parameters:

classes (Type[Any]) –

Return type:

Callable[[Mapping[Any, Any]], Type[Any] | None]

cattrs.dispatch module#

class cattrs.dispatch.FunctionDispatch(handler_pairs=_Nothing.NOTHING)[source]#

Bases: object

FunctionDispatch is similar to functools.singledispatch, but instead dispatches based on functions that take the type of the first argument in the method, and return True or False.

objects that help determine dispatch should be instantiated objects.

Parameters:

handler_pairs (List[Tuple[Callable[[Any], bool], Callable[[Any, Any], Any], bool]]) –

copy_to(other, skip=0)[source]#
Parameters:
dispatch(typ)[source]#

returns the appropriate handler, for the object passed.

Parameters:

typ (Any) –

Return type:

Callable[[Any, Any], Any] | None

get_num_fns()[source]#
Return type:

int

register(can_handle, func, is_generator=False)[source]#
Parameters:

can_handle (Callable[[Any], bool]) –

class cattrs.dispatch.MultiStrategyDispatch(fallback_func)[source]#

Bases: object

MultiStrategyDispatch uses a combination of exact-match dispatch, singledispatch, and FunctionDispatch.

Parameters:

fallback_func (Callable[[Any, Any], Any]) –

clear_cache()[source]#

Clear all caches.

clear_direct()[source]#

Clear the direct dispatch.

copy_to(other, skip=0)[source]#
Parameters:
dispatch#
get_num_fns()[source]#
Return type:

int

register_cls_list(cls_and_handler, direct=False)[source]#

Register a class to direct or singledispatch.

Parameters:

direct (bool) –

Return type:

None

register_func_list(pred_and_handler)[source]#

Register a predicate function to determine if the handle should be used for the type.

Parameters:

pred_and_handler (List[Tuple[Callable[[Any], bool], Any] | Tuple[Callable[[Any], bool], Any, bool]]) –

cattrs.errors module#

class cattrs.errors.AttributeValidationNote(string, name, type)[source]#

Bases: str

Attached as a note to an exception when an attribute fails structuring.

Parameters:

  • string (str) –

  • name (str) –

  • type (Any) –

Return type:

AttributeValidationNote

name: str#
type: Any#
exception cattrs.errors.BaseValidationError(message, excs, cl)[source]#

Bases: ExceptionGroup

Parameters:

cl (Type) –

cl: Type#
derive(excs)[source]#
exception cattrs.errors.ClassValidationError(message, excs, cl)[source]#

Bases: BaseValidationError

Raised when validating a class if any attributes are invalid.

Parameters:

cl (Type) –

group_exceptions()[source]#

Split the exceptions into two groups: with and without validation notes.

Return type:

Tuple[List[Tuple[Exception, AttributeValidationNote]], List[Exception]]

exception cattrs.errors.ForbiddenExtraKeysError(message, cl, extra_fields)[source]#

Bases: Exception

Raised when forbid_extra_keys is activated and such extra keys are detected during structuring.

The attribute extra_fields is a sequence of those extra keys, which were the cause of this error, and cl is the class which was structured with those extra keys.

Parameters:

  • message (str | None) –

  • cl (Type) –

  • extra_fields (Set[str]) –

Return type:

None

exception cattrs.errors.IterableValidationError(message, excs, cl)[source]#

Bases: BaseValidationError

Raised when structuring an iterable.

Parameters:

cl (Type) –

group_exceptions()[source]#

Split the exceptions into two groups: with and without validation notes.

Return type:

Tuple[List[Tuple[Exception, IterableValidationNote]], List[Exception]]

class cattrs.errors.IterableValidationNote(string, index, type)[source]#

Bases: str

Attached as a note to an exception when an iterable element fails structuring.

Parameters:

  • string (str) –

  • index (int | str) –

  • type (Any) –

Return type:

IterableValidationNote

type: Any#
exception cattrs.errors.StructureHandlerNotFoundError(message, type_)[source]#

Bases: Exception

Error raised when structuring cannot find a handler for converting inputs into type_.

Parameters:

  • message (str) –

  • type_ (Type) –

Return type:

None

cattrs.v module#

Cattrs validation.

cattrs.v.format_exception(exc, type)[source]#

The default exception formatter, handling the most common exceptions.

The following exceptions are handled specially: * KeyErrors (required field missing) * ValueErrors (invalid value for type, expected <type> or just invalid value) * TypeErrors (invalid value for type, expected <type> and a couple special

cases for iterables)

  • cattrs.ForbiddenExtraKeysError

  • some AttributeErrors (special cased for structing mappings)

Parameters:

  • exc (BaseException) –

  • type (Type | None) –

Return type:

str

cattrs.v.transform_error(exc, path='$', format_exception=<function format_exception>)[source]#

Transform an exception into a list of error messages.

To get detailed error messages, the exception should be produced by a converter with detailed_validation set.

By default, the error messages are in the form of {description} @ {path}.

While traversing the exception and subexceptions, the path is formed: * by appending .{field_name} for fields in classes * by appending [{int}] for indices in iterables, like lists * by appending [{str}] for keys in mappings, like dictionaries

Parameters:

  • exc (ClassValidationError | IterableValidationError | BaseException) – The exception to transform into error messages.

  • path (str) – The root path to use.

  • format_exception (Callable[[BaseException, Type | None], str]) – A callable to use to transform Exceptions into string descriptions of errors.

Return type:

List[str]

New in version 23.1.0.

Module contents#

class cattrs.AttributeValidationNote(string, name, type)[source]#

Bases: str

Attached as a note to an exception when an attribute fails structuring.

Parameters:

  • string (str) –

  • name (str) –

  • type (Any) –

Return type:

AttributeValidationNote

name: str#
type: Any#
class cattrs.BaseConverter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, prefer_attrib_converters=False, detailed_validation=True)[source]#

Bases: object

Converts between structured and unstructured data.

Parameters:

  • dict_factory (Callable[[], Any]) –

  • unstruct_strat (UnstructureStrategy) –

  • prefer_attrib_converters (bool) –

  • detailed_validation (bool) –

copy(dict_factory=None, unstruct_strat=None, prefer_attrib_converters=None, detailed_validation=None)[source]#
Parameters:

  • dict_factory (Callable[[], Any] | None) –

  • unstruct_strat (UnstructureStrategy | None) –

  • prefer_attrib_converters (bool | None) –

  • detailed_validation (bool | None) –

Return type:

BaseConverter

detailed_validation#
register_structure_hook(cl, func)[source]#

Register a primitive-to-class converter function for a type.

The converter function should take two arguments:

  • a Python object to be converted,

  • the type to convert to

and return the instance of the class. The type may seem redundant, but is sometimes needed (for example, when dealing with generic classes).

Parameters:

  • cl (Any) –

  • func (Callable[[Any, Type[T]], T]) –

Return type:

None

register_structure_hook_factory(predicate, factory)[source]#

Register a hook factory for a given predicate.

A predicate is a function that, given a type, returns whether the factory can produce a hook for that type.

A factory is a callable that, given a type, produces a structuring hook for that type. This structuring hook will be cached.

Parameters:

  • predicate (Callable[[Any], bool]) –

  • factory (Callable[[Any], Callable[[Any, Any], Any]]) –

Return type:

None

register_structure_hook_func(check_func, func)[source]#

Register a class-to-primitive converter function for a class, using a function to check if it’s a match.

Parameters:

  • check_func (Callable[[Type[T]], bool]) –

  • func (Callable[[Any, Type[T]], T]) –

Return type:

None

register_unstructure_hook(cls, func)[source]#

Register a class-to-primitive converter function for a class.

The converter function should take an instance of the class and return its Python equivalent.

Parameters:

  • cls (Any) –

  • func (Callable[[Any], Any]) –

Return type:

None

register_unstructure_hook_factory(predicate, factory)[source]#

Register a hook factory for a given predicate.

A predicate is a function that, given a type, returns whether the factory can produce a hook for that type.

A factory is a callable that, given a type, produces an unstructuring hook for that type. This unstructuring hook will be cached.

Parameters:

  • predicate (Callable[[Any], bool]) –

  • factory (Callable[[Any], Callable[[Any], Any]]) –

Return type:

None

register_unstructure_hook_func(check_func, func)[source]#

Register a class-to-primitive converter function for a class, using a function to check if it’s a match.

Parameters:

  • check_func (Callable[[Any], bool]) –

  • func (Callable[[Any], Any]) –

Return type:

None

structure(obj, cl)[source]#

Convert unstructured Python data structures to structured data.

Parameters:

  • obj (Any) –

  • cl (Type[T]) –

Return type:

T

structure_attrs_fromdict(obj, cl)[source]#

Instantiate an attrs class from a mapping (dict).

Parameters:

  • obj (Mapping[str, Any]) –

  • cl (Type[T]) –

Return type:

T

structure_attrs_fromtuple(obj, cl)[source]#

Load an attrs class from a sequence (tuple).

Parameters:

  • obj (Tuple[Any, ...]) –

  • cl (Type[T]) –

Return type:

T

property unstruct_strat: UnstructureStrategy#

The default way of unstructuring attrs classes.

unstructure(obj, unstructure_as=None)[source]#
Parameters:

  • obj (Any) –

  • unstructure_as (Any | None) –

Return type:

Any

unstructure_attrs_asdict(obj)[source]#

Our version of attrs.asdict, so we can call back to us.

Parameters:

obj (Any) –

Return type:

Dict[str, Any]

unstructure_attrs_astuple(obj)[source]#

Our version of attrs.astuple, so we can call back to us.

Parameters:

obj (Any) –

Return type:

Tuple[Any, …]

exception cattrs.BaseValidationError(message, excs, cl)[source]#

Bases: ExceptionGroup

Parameters:

cl (Type) –

cl: Type#
derive(excs)[source]#
exception cattrs.ClassValidationError(message, excs, cl)[source]#

Bases: BaseValidationError

Raised when validating a class if any attributes are invalid.

Parameters:

cl (Type) –

group_exceptions()[source]#

Split the exceptions into two groups: with and without validation notes.

Return type:

Tuple[List[Tuple[Exception, AttributeValidationNote]], List[Exception]]

class cattrs.Converter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, omit_if_default=False, forbid_extra_keys=False, type_overrides={}, unstruct_collection_overrides={}, prefer_attrib_converters=False, detailed_validation=True)[source]#

Bases: BaseConverter

A converter which generates specialized un/structuring functions.

Parameters:

  • dict_factory (Callable[[], Any]) –

  • unstruct_strat (UnstructureStrategy) –

  • omit_if_default (bool) –

  • forbid_extra_keys (bool) –

  • type_overrides (Mapping[Type, AttributeOverride]) –

  • unstruct_collection_overrides (Mapping[Type, Callable]) –

  • prefer_attrib_converters (bool) –

  • detailed_validation (bool) –

copy(dict_factory=None, unstruct_strat=None, omit_if_default=None, forbid_extra_keys=None, type_overrides=None, unstruct_collection_overrides=None, prefer_attrib_converters=None, detailed_validation=None)[source]#
Parameters:

  • dict_factory (Callable[[], Any] | None) –

  • unstruct_strat (UnstructureStrategy | None) –

  • omit_if_default (bool | None) –

  • forbid_extra_keys (bool | None) –

  • type_overrides (Mapping[Type, AttributeOverride] | None) –

  • unstruct_collection_overrides (Mapping[Type, Callable] | None) –

  • prefer_attrib_converters (bool | None) –

  • detailed_validation (bool | None) –

Return type:

Converter

forbid_extra_keys#
gen_structure_annotated(type)[source]#
gen_structure_attrs_fromdict(cl)[source]#
Parameters:

cl (Type[T]) –

Return type:

Callable[[Mapping[str, Any], Any], T]

gen_structure_counter(cl)[source]#
Parameters:

cl (Any) –

Return type:

Callable[[Mapping[Any, Any], Any], T]

gen_structure_mapping(cl)[source]#
Parameters:

cl (Any) –

Return type:

Callable[[Mapping[Any, Any], Any], T]

gen_structure_typeddict(cl)[source]#

Generate a TypedDict structure function.

Also apply converter-scored modifications.

Parameters:

cl (Any) –

Return type:

Callable[[Dict], Dict]

gen_unstructure_annotated(type)[source]#
gen_unstructure_attrs_fromdict(cl)[source]#
Parameters:

cl (Type[T]) –

Return type:

Callable[[T], Dict[str, Any]]

gen_unstructure_hetero_tuple(cl, unstructure_to=None)[source]#
Parameters:

  • cl (Any) –

  • unstructure_to (Any | None) –

Return type:

Callable[[Tuple[Any, …]], Any]

gen_unstructure_iterable(cl, unstructure_to=None)[source]#
Parameters:

  • cl (Any) –

  • unstructure_to (Any | None) –

Return type:

Callable[[Iterable[Any]], Any]

gen_unstructure_mapping(cl, unstructure_to=None, key_handler=None)[source]#
Parameters:

  • cl (Any) –

  • unstructure_to (Any | None) –

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

Return type:

Callable[[Mapping[Any, Any]], Any]

gen_unstructure_typeddict(cl)[source]#

Generate a TypedDict unstructure function.

Also apply converter-scored modifications.

Parameters:

cl (Any) –

Return type:

Callable[[Dict], Dict]

get_structure_newtype(type)[source]#
Parameters:

type (Type[T]) –

Return type:

Callable[[Any, Any], T]

omit_if_default#
type_overrides#
exception cattrs.ForbiddenExtraKeysError(message, cl, extra_fields)[source]#

Bases: Exception

Raised when forbid_extra_keys is activated and such extra keys are detected during structuring.

The attribute extra_fields is a sequence of those extra keys, which were the cause of this error, and cl is the class which was structured with those extra keys.

Parameters:

  • message (str | None) –

  • cl (Type) –

  • extra_fields (Set[str]) –

Return type:

None

cattrs.GenConverter#

alias of Converter

exception cattrs.IterableValidationError(message, excs, cl)[source]#

Bases: BaseValidationError

Raised when structuring an iterable.

Parameters:

cl (Type) –

group_exceptions()[source]#

Split the exceptions into two groups: with and without validation notes.

Return type:

Tuple[List[Tuple[Exception, IterableValidationNote]], List[Exception]]

class cattrs.IterableValidationNote(string, index, type)[source]#

Bases: str

Attached as a note to an exception when an iterable element fails structuring.

Parameters:

  • string (str) –

  • index (int | str) –

  • type (Any) –

Return type:

IterableValidationNote

type: Any#
exception cattrs.StructureHandlerNotFoundError(message, type_)[source]#

Bases: Exception

Error raised when structuring cannot find a handler for converting inputs into type_.

Parameters:

  • message (str) –

  • type_ (Type) –

Return type:

None

class cattrs.UnstructureStrategy(value)[source]#

Bases: Enum

attrs classes unstructuring strategies.

AS_DICT = 'asdict'#
AS_TUPLE = 'astuple'#
cattrs.override(omit_if_default=None, rename=None, omit=False, struct_hook=None, unstruct_hook=None)[source]#
Parameters:

  • omit_if_default (bool | None) –

  • rename (str | None) –

  • omit (bool) –

  • struct_hook (Callable[[Any, Any], Any] | None) –

  • unstruct_hook (Callable[[Any], Any] | None) –

cattrs.register_structure_hook(cl, func)#

Register a primitive-to-class converter function for a type.

The converter function should take two arguments:

  • a Python object to be converted,

  • the type to convert to

and return the instance of the class. The type may seem redundant, but is sometimes needed (for example, when dealing with generic classes).

Parameters:

  • cl (Any) –

  • func (Callable[[Any, Type[T]], T]) –

Return type:

None

cattrs.register_structure_hook_func(check_func, func)#

Register a class-to-primitive converter function for a class, using a function to check if it’s a match.

Parameters:

  • check_func (Callable[[Type[T]], bool]) –

  • func (Callable[[Any, Type[T]], T]) –

Return type:

None

cattrs.register_unstructure_hook(cls, func)#

Register a class-to-primitive converter function for a class.

The converter function should take an instance of the class and return its Python equivalent.

Parameters:

  • cls (Any) –

  • func (Callable[[Any], Any]) –

Return type:

None

cattrs.register_unstructure_hook_func(check_func, func)#

Register a class-to-primitive converter function for a class, using a function to check if it’s a match.

Parameters:

  • check_func (Callable[[Any], bool]) –

  • func (Callable[[Any], Any]) –

Return type:

None

cattrs.structure(obj, cl)#

Convert unstructured Python data structures to structured data.

Parameters:

  • obj (Any) –

  • cl (Type[T]) –

Return type:

T

cattrs.structure_attrs_fromdict(obj, cl)#

Instantiate an attrs class from a mapping (dict).

Parameters:

  • obj (Mapping[str, Any]) –

  • cl (Type[T]) –

Return type:

T

cattrs.structure_attrs_fromtuple(obj, cl)#

Load an attrs class from a sequence (tuple).

Parameters:

  • obj (Tuple[Any, ...]) –

  • cl (Type[T]) –

Return type:

T

cattrs.transform_error(exc, path='$', format_exception=<function format_exception>)[source]#

Transform an exception into a list of error messages.

To get detailed error messages, the exception should be produced by a converter with detailed_validation set.

By default, the error messages are in the form of {description} @ {path}.

While traversing the exception and subexceptions, the path is formed: * by appending .{field_name} for fields in classes * by appending [{int}] for indices in iterables, like lists * by appending [{str}] for keys in mappings, like dictionaries

Parameters:

  • exc (ClassValidationError | IterableValidationError | BaseException) – The exception to transform into error messages.

  • path (str) – The root path to use.

  • format_exception (Callable[[BaseException, Type | None], str]) – A callable to use to transform Exceptions into string descriptions of errors.

Return type:

List[str]

New in version 23.1.0.

cattrs.unstructure(obj, unstructure_as=None)#
Parameters:

  • obj (Any) –

  • unstructure_as (Any | None) –

Return type:

Any