cattr package

Subpackages

Submodules

cattr.converters module

class cattr.converters.Converter(dict_factory: Callable[[], Any] = <class 'dict'>, unstruct_strat: cattr.converters.UnstructureStrategy = UnstructureStrategy.AS_DICT, prefer_attrib_converters: bool = False)[source]

Bases: object

Converts between structured and unstructured data.

register_structure_hook(cl: Any, func: Callable[[Any, Type[cattr.converters.T]], cattr.converters.T])[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).

register_structure_hook_factory(predicate: Callable[[Any], bool], factory: Callable[[Any], Callable[[Any], Any]]) None[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.

register_structure_hook_func(check_func: Callable[[Type[cattr.converters.T]], bool], func: Callable[[Any, Type[cattr.converters.T]], cattr.converters.T])[source]

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

register_unstructure_hook(cls: Any, func: Callable[[cattr.converters.T], Any]) None[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.

register_unstructure_hook_factory(predicate: Callable[[Any], bool], factory: Callable[[Any], Callable[[Any], Any]]) None[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.

register_unstructure_hook_func(check_func: Callable[[Any], bool], func: Callable[[cattr.converters.T], Any])[source]

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

structure(obj: Any, cl: Type[cattr.converters.T]) cattr.converters.T[source]

Convert unstructured Python data structures to structured data.

structure_attrs_fromdict(obj: collections.abc.Mapping[str, Any], cl: Type[cattr.converters.T]) cattr.converters.T[source]

Instantiate an attrs class from a mapping (dict).

structure_attrs_fromtuple(obj: Tuple[Any, ...], cl: Type[cattr.converters.T]) cattr.converters.T[source]

Load an attrs class from a sequence (tuple).

property unstruct_strat: cattr.converters.UnstructureStrategy

The default way of unstructuring attrs classes.

unstructure(obj: Any, unstructure_as=None) Any[source]
unstructure_attrs_asdict(obj) Dict[str, Any][source]

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

unstructure_attrs_astuple(obj) Tuple[Any, ...][source]

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

class cattr.converters.GenConverter(dict_factory: Callable[[], Any] = <class 'dict'>, unstruct_strat: cattr.converters.UnstructureStrategy = UnstructureStrategy.AS_DICT, omit_if_default: bool = False, forbid_extra_keys: bool = False, type_overrides: collections.abc.Mapping[Type, cattr.gen.AttributeOverride] = {}, unstruct_collection_overrides: collections.abc.Mapping[Type, Callable] = {}, prefer_attrib_converters: bool = False)[source]

Bases: cattr.converters.Converter

A converter which generates specialized un/structuring functions.

forbid_extra_keys
gen_structure_annotated(type)[source]
gen_structure_attrs_fromdict(cl: Type[cattr.converters.T]) cattr.converters.T[source]
gen_structure_counter(cl: Any)[source]
gen_structure_mapping(cl: Any)[source]
gen_unstructure_annotated(type)[source]
gen_unstructure_attrs_fromdict(cl: Type[cattr.converters.T]) Dict[str, Any][source]
gen_unstructure_hetero_tuple(cl: Any, unstructure_to=None)[source]
gen_unstructure_iterable(cl: Any, unstructure_to=None)[source]
gen_unstructure_mapping(cl: Any, unstructure_to=None, key_handler=None)[source]
omit_if_default
type_overrides
class cattr.converters.UnstructureStrategy(value)[source]

Bases: enum.Enum

attrs classes unstructuring strategies.

AS_DICT = 'asdict'
AS_TUPLE = 'astuple'
cattr.converters.is_attrs_union(typ)[source]
cattr.converters.is_attrs_union_or_none(typ)[source]
cattr.converters.is_optional(typ)[source]

cattr.disambiguators module

Utilities for union (sum type) disambiguation.

cattr.disambiguators.create_uniq_field_dis_func(*classes: Type) Callable[source]

Given attr classes, generate a disambiguation function.

The function is based on unique fields.

cattr.dispatch module

class cattr.dispatch.FunctionDispatch(handler_pairs: list = 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.

dispatch(typ)[source]

returns the appropriate handler, for the object passed.

register(can_handle: Callable[[Any], bool], func, is_generator=False)[source]
class cattr.dispatch.MultiStrategyDispatch(fallback_func)[source]

Bases: object

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

clear_cache()[source]

Clear all caches.

clear_direct()[source]

Clear the direct dispatch.

dispatch
register_cls_list(cls_and_handler, direct: bool = False)[source]

register a class to direct or singledispatch

register_func_list(func_and_handler: List[Union[Tuple[Callable[[Any], bool], Any], Tuple[Callable[[Any], bool], Any, bool]]])[source]

register a function to determine if the handle should be used for the type

cattr.errors module

exception cattr.errors.StructureHandlerNotFoundError(message: str, type_: Type)[source]

Bases: Exception

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

cattr.gen module

class cattr.gen.AttributeOverride(omit_if_default: Optional[bool] = None, rename: Optional[str] = None, omit: bool = False)[source]

Bases: object

omit: bool
omit_if_default: Optional[bool]
rename: Optional[str]
cattr.gen.make_dict_structure_fn(cl: Type[cattr.gen.T], converter: Converter, _cattrs_forbid_extra_keys: bool = False, _cattrs_use_linecache: bool = True, _cattrs_prefer_attrib_converters: bool = False, **kwargs) Callable[[Mapping[str, Any]], cattr.gen.T][source]

Generate a specialized dict structuring function for an attrs class.

cattr.gen.make_dict_unstructure_fn(cl, converter, omit_if_default: bool = False, _cattrs_use_linecache: bool = True, **kwargs)[source]

Generate a specialized dict unstructuring function for an attrs class.

cattr.gen.make_hetero_tuple_unstructure_fn(cl: Any, converter, unstructure_to=None)[source]

Generate a specialized unstructure function for a heterogenous tuple.

cattr.gen.make_iterable_unstructure_fn(cl: Any, converter, unstructure_to=None)[source]

Generate a specialized unstructure function for an iterable.

cattr.gen.make_mapping_structure_fn(cl: Any, converter, structure_to=<class 'dict'>, key_type=NOTHING, val_type=NOTHING)[source]

Generate a specialized unstructure function for a mapping.

cattr.gen.make_mapping_unstructure_fn(cl: Any, converter, unstructure_to=None, key_handler=None)[source]

Generate a specialized unstructure function for a mapping.

cattr.gen.override(omit_if_default=None, rename=None, omit: bool = False)[source]

Module contents

class cattr.Converter(dict_factory: Callable[[], Any] = <class 'dict'>, unstruct_strat: cattr.converters.UnstructureStrategy = UnstructureStrategy.AS_DICT, prefer_attrib_converters: bool = False)[source]

Bases: object

Converts between structured and unstructured data.

register_structure_hook(cl: Any, func: Callable[[Any, Type[cattr.converters.T]], cattr.converters.T])[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).

register_structure_hook_factory(predicate: Callable[[Any], bool], factory: Callable[[Any], Callable[[Any], Any]]) None[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.

register_structure_hook_func(check_func: Callable[[Type[cattr.converters.T]], bool], func: Callable[[Any, Type[cattr.converters.T]], cattr.converters.T])[source]

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

register_unstructure_hook(cls: Any, func: Callable[[cattr.converters.T], Any]) None[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.

register_unstructure_hook_factory(predicate: Callable[[Any], bool], factory: Callable[[Any], Callable[[Any], Any]]) None[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.

register_unstructure_hook_func(check_func: Callable[[Any], bool], func: Callable[[cattr.converters.T], Any])[source]

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

structure(obj: Any, cl: Type[cattr.converters.T]) cattr.converters.T[source]

Convert unstructured Python data structures to structured data.

structure_attrs_fromdict(obj: collections.abc.Mapping[str, Any], cl: Type[cattr.converters.T]) cattr.converters.T[source]

Instantiate an attrs class from a mapping (dict).

structure_attrs_fromtuple(obj: Tuple[Any, ...], cl: Type[cattr.converters.T]) cattr.converters.T[source]

Load an attrs class from a sequence (tuple).

property unstruct_strat: cattr.converters.UnstructureStrategy

The default way of unstructuring attrs classes.

unstructure(obj: Any, unstructure_as=None) Any[source]
unstructure_attrs_asdict(obj) Dict[str, Any][source]

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

unstructure_attrs_astuple(obj) Tuple[Any, ...][source]

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

class cattr.GenConverter(dict_factory: Callable[[], Any] = <class 'dict'>, unstruct_strat: cattr.converters.UnstructureStrategy = UnstructureStrategy.AS_DICT, omit_if_default: bool = False, forbid_extra_keys: bool = False, type_overrides: collections.abc.Mapping[Type, cattr.gen.AttributeOverride] = {}, unstruct_collection_overrides: collections.abc.Mapping[Type, Callable] = {}, prefer_attrib_converters: bool = False)[source]

Bases: cattr.converters.Converter

A converter which generates specialized un/structuring functions.

forbid_extra_keys
gen_structure_annotated(type)[source]
gen_structure_attrs_fromdict(cl: Type[cattr.converters.T]) cattr.converters.T[source]
gen_structure_counter(cl: Any)[source]
gen_structure_mapping(cl: Any)[source]
gen_unstructure_annotated(type)[source]
gen_unstructure_attrs_fromdict(cl: Type[cattr.converters.T]) Dict[str, Any][source]
gen_unstructure_hetero_tuple(cl: Any, unstructure_to=None)[source]
gen_unstructure_iterable(cl: Any, unstructure_to=None)[source]
gen_unstructure_mapping(cl: Any, unstructure_to=None, key_handler=None)[source]
omit_if_default
type_overrides
class cattr.UnstructureStrategy(value)[source]

Bases: enum.Enum

attrs classes unstructuring strategies.

AS_DICT = 'asdict'
AS_TUPLE = 'astuple'
cattr.override(omit_if_default=None, rename=None, omit: bool = False)[source]
cattr.structure(obj: Any, cl: Type[cattr.converters.T]) cattr.converters.T

Convert unstructured Python data structures to structured data.

cattr.structure_attrs_fromdict(obj: collections.abc.Mapping[str, Any], cl: Type[cattr.converters.T]) cattr.converters.T

Instantiate an attrs class from a mapping (dict).

cattr.structure_attrs_fromtuple(obj: Tuple[Any, ...], cl: Type[cattr.converters.T]) cattr.converters.T

Load an attrs class from a sequence (tuple).

cattr.unstructure(obj: Any, unstructure_as=None) Any