# cattr package

## Subpackages

- cattr.preconf package
  - Submodules
  - cattr.preconf.bson module
  - cattr.preconf.json module
  - cattr.preconf.msgpack module
  - cattr.preconf.orjson module
  - cattr.preconf.pyyaml module
  - cattr.preconf.tomlkit module
  - cattr.preconf.ujson module
  - Module contents

## Submodules

## cattr.converters module

class cattr.converters.Converter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, prefer_attrib_converters=False)

  Bases: `object`

  Converts between structured and unstructured data.

  Parameters

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

    - unstruct_strat (cattr.converters.UnstructureStrategy) –

    - prefer_attrib_converters (bool) –

  Return type

    None

  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[cattr.converters.T]], cattr.converters.T]) –

  register_structure_hook_factory(predicate, factory)

    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]]) –

    Return type

      None

  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[cattr.converters.T]], bool]) –

      - func (Callable[[Any, Type[cattr.converters.T]], cattr.converters.T]) –

  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[[cattr.converters.T], Any]) –

    Return type

      None

  register_unstructure_hook_factory(predicate, factory)

    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)

    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[[cattr.converters.T], Any]) –

  structure(obj, cl)

    Convert unstructured Python data structures to structured data.

    Parameters

      - obj (Any) –

      - cl (Type[cattr.converters.T]) –

    Return type

      cattr.converters.T

  structure_attrs_fromdict(obj, cl)

    Instantiate an attrs class from a mapping (dict).

    Parameters

      - obj (collections.abc.Mapping[str, Any]) –

      - cl (Type[cattr.converters.T]) –

    Return type

      cattr.converters.T

  structure_attrs_fromtuple(obj, cl)

    Load an attrs class from a sequence (tuple).

    Parameters

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

      - cl (Type[cattr.converters.T]) –

    Return type

      cattr.converters.T

  property unstruct_strat: cattr.converters.UnstructureStrategy

    The default way of unstructuring `attrs` classes.

  unstructure(obj, unstructure_as=None)
    Parameters

      obj (Any) –

    Return type

      Any

  unstructure_attrs_asdict(obj)

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

    Return type

      Dict[str, Any]

  unstructure_attrs_astuple(obj)

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

    Return type

      Tuple[Any, …]

class cattr.converters.GenConverter(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)

  Bases: `cattr.converters.Converter`

  A converter which generates specialized un/structuring functions.

  Parameters

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

    - unstruct_strat (cattr.converters.UnstructureStrategy) –

    - omit_if_default (bool) –

    - forbid_extra_keys (bool) –

    - type_overrides (collections.abc.Mapping[Type, cattr.gen.AttributeOverride]) –

    - unstruct_collection_overrides (collections.abc.Mapping[Type, Callable]) –

    - prefer_attrib_converters (bool) –

  forbid_extra_keys
  gen_structure_annotated(type)
  gen_structure_attrs_fromdict(cl)
    Parameters

      cl (Type[cattr.converters.T]) –

    Return type

      cattr.converters.T

  gen_structure_counter(cl)
    Parameters

      cl (Any) –

  gen_structure_mapping(cl)
    Parameters

      cl (Any) –

  gen_unstructure_annotated(type)
  gen_unstructure_attrs_fromdict(cl)
    Parameters

      cl (Type[cattr.converters.T]) –

    Return type

      Dict[str, Any]

  gen_unstructure_hetero_tuple(cl, unstructure_to=None)
    Parameters

      cl (Any) –

  gen_unstructure_iterable(cl, unstructure_to=None)
    Parameters

      cl (Any) –

  gen_unstructure_mapping(cl, unstructure_to=None, key_handler=None)
    Parameters

      cl (Any) –

  omit_if_default
  type_overrides

class cattr.converters.UnstructureStrategy(value)

  Bases: `enum.Enum`

  attrs classes unstructuring strategies.

  AS_DICT = 'asdict'
  AS_TUPLE = 'astuple'

cattr.converters.is_attrs_union(typ)

cattr.converters.is_attrs_union_or_none(typ)

cattr.converters.is_optional(typ)

## cattr.disambiguators module

Utilities for union (sum type) disambiguation.

cattr.disambiguators.create_uniq_field_dis_func(*classes)

  Given attr classes, generate a disambiguation function.

  The function is based on unique fields.

  Parameters

    classes (Type) –

  Return type

    Callable

## cattr.dispatch module

class cattr.dispatch.FunctionDispatch(handler_pairs=NOTHING)

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

  Return type

    None

  dispatch(typ)

    returns the appropriate handler, for the object passed.

  register(can_handle, func, is_generator=False)
    Parameters

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

class cattr.dispatch.MultiStrategyDispatch(fallback_func)

  Bases: `object`

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

  clear_cache()

    Clear all caches.

  clear_direct()

    Clear the direct dispatch.

  dispatch
  register_cls_list(cls_and_handler, direct=False)

    register a class to direct or singledispatch

    Parameters

      direct (bool) –

  register_func_list(func_and_handler)

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

    Parameters

      func_and_handler (List[Union[Tuple[Callable[[Any], bool], Any], Tuple[Callable[[Any], bool], Any, bool]]]) –

## cattr.errors module

exception cattr.errors.StructureHandlerNotFoundError(message, type_)

  Bases: `Exception`

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

  Parameters

    - message (str) –

    - type_ (Type) –

  Return type

    None

## cattr.gen module

class cattr.gen.AttributeOverride(omit_if_default=None, rename=None, omit=False)

  Bases: `object`

  Parameters

    - omit_if_default (Optional[bool]) –

    - rename (Optional[str]) –

    - omit (bool) –

  Return type

    None

  omit: bool
  omit_if_default: Optional[bool]
  rename: Optional[str]

cattr.gen.make_dict_structure_fn(cl, converter, _cattrs_forbid_extra_keys=False, _cattrs_use_linecache=True, _cattrs_prefer_attrib_converters=False, **kwargs)

  Generate a specialized dict structuring function for an attrs class.

  Parameters

    - cl (Type[cattr.gen.T]) –

    - converter (Converter) –

    - _cattrs_forbid_extra_keys (bool) –

    - _cattrs_use_linecache (bool) –

    - _cattrs_prefer_attrib_converters (bool) –

  Return type

    Callable[[Mapping[str, Any]], cattr.gen.T]

cattr.gen.make_dict_unstructure_fn(cl, converter, _cattrs_omit_if_default=False, _cattrs_use_linecache=True, **kwargs)

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

  Parameters

    - _cattrs_omit_if_default (bool) –

    - _cattrs_use_linecache (bool) –

cattr.gen.make_hetero_tuple_unstructure_fn(cl, converter, unstructure_to=None)

  Generate a specialized unstructure function for a heterogenous tuple.

  Parameters

    cl (Any) –

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

  Generate a specialized unstructure function for an iterable.

  Parameters

    cl (Any) –

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

  Generate a specialized unstructure function for a mapping.

  Parameters

    cl (Any) –

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

  Generate a specialized unstructure function for a mapping.

  Parameters

    cl (Any) –

cattr.gen.override(omit_if_default=None, rename=None, omit=False)
  Parameters

    omit (bool) –

## Module contents

class cattr.Converter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, prefer_attrib_converters=False)

  Bases: `object`

  Converts between structured and unstructured data.

  Parameters

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

    - unstruct_strat (cattr.converters.UnstructureStrategy) –

    - prefer_attrib_converters (bool) –

  Return type

    None

  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[cattr.converters.T]], cattr.converters.T]) –

  register_structure_hook_factory(predicate, factory)

    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]]) –

    Return type

      None

  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[cattr.converters.T]], bool]) –

      - func (Callable[[Any, Type[cattr.converters.T]], cattr.converters.T]) –

  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[[cattr.converters.T], Any]) –

    Return type

      None

  register_unstructure_hook_factory(predicate, factory)

    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)

    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[[cattr.converters.T], Any]) –

  structure(obj, cl)

    Convert unstructured Python data structures to structured data.

    Parameters

      - obj (Any) –

      - cl (Type[cattr.converters.T]) –

    Return type

      cattr.converters.T

  structure_attrs_fromdict(obj, cl)

    Instantiate an attrs class from a mapping (dict).

    Parameters

      - obj (collections.abc.Mapping[str, Any]) –

      - cl (Type[cattr.converters.T]) –

    Return type

      cattr.converters.T

  structure_attrs_fromtuple(obj, cl)

    Load an attrs class from a sequence (tuple).

    Parameters

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

      - cl (Type[cattr.converters.T]) –

    Return type

      cattr.converters.T

  property unstruct_strat: cattr.converters.UnstructureStrategy

    The default way of unstructuring `attrs` classes.

  unstructure(obj, unstructure_as=None)
    Parameters

      obj (Any) –

    Return type

      Any

  unstructure_attrs_asdict(obj)

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

    Return type

      Dict[str, Any]

  unstructure_attrs_astuple(obj)

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

    Return type

      Tuple[Any, …]

class cattr.GenConverter(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)

  Bases: `cattr.converters.Converter`

  A converter which generates specialized un/structuring functions.

  Parameters

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

    - unstruct_strat (cattr.converters.UnstructureStrategy) –

    - omit_if_default (bool) –

    - forbid_extra_keys (bool) –

    - type_overrides (collections.abc.Mapping[Type, cattr.gen.AttributeOverride]) –

    - unstruct_collection_overrides (collections.abc.Mapping[Type, Callable]) –

    - prefer_attrib_converters (bool) –

  forbid_extra_keys
  gen_structure_annotated(type)
  gen_structure_attrs_fromdict(cl)
    Parameters

      cl (Type[cattr.converters.T]) –

    Return type

      cattr.converters.T

  gen_structure_counter(cl)
    Parameters

      cl (Any) –

  gen_structure_mapping(cl)
    Parameters

      cl (Any) –

  gen_unstructure_annotated(type)
  gen_unstructure_attrs_fromdict(cl)
    Parameters

      cl (Type[cattr.converters.T]) –

    Return type

      Dict[str, Any]

  gen_unstructure_hetero_tuple(cl, unstructure_to=None)
    Parameters

      cl (Any) –

  gen_unstructure_iterable(cl, unstructure_to=None)
    Parameters

      cl (Any) –

  gen_unstructure_mapping(cl, unstructure_to=None, key_handler=None)
    Parameters

      cl (Any) –

  omit_if_default
  type_overrides

class cattr.UnstructureStrategy(value)

  Bases: `enum.Enum`

  attrs classes unstructuring strategies.

  AS_DICT = 'asdict'
  AS_TUPLE = 'astuple'

cattr.override(omit_if_default=None, rename=None, omit=False)
  Parameters

    omit (bool) –

cattr.structure(obj, cl)

  Convert unstructured Python data structures to structured data.

  Parameters

    - obj (Any) –

    - cl (Type[cattr.converters.T]) –

  Return type

    cattr.converters.T

cattr.structure_attrs_fromdict(obj, cl)

  Instantiate an attrs class from a mapping (dict).

  Parameters

    - obj (collections.abc.Mapping[str, Any]) –

    - cl (Type[cattr.converters.T]) –

  Return type

    cattr.converters.T

cattr.structure_attrs_fromtuple(obj, cl)

  Load an attrs class from a sequence (tuple).

  Parameters

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

    - cl (Type[cattr.converters.T]) –

  Return type

    cattr.converters.T

cattr.unstructure(obj, unstructure_as=None)
  Parameters

    obj (Any) –

  Return type

    Any