Converters

All cattrs functionality is exposed through a cattr.Converter object. Global cattrs functions, such as cattr.unstructure(), use a single global converter. Changes done to this global converter, such as registering new structure and unstructure hooks, affect all code using the global functions.

Global converter

A global converter is provided for convenience as cattr.global_converter. The following functions implicitly use this global converter:

• cattr.structure
• cattr.unstructure
• cattr.structure_attr_fromtuple
• cattr.structure_attr_fromdict

Changes made to the global converter will affect the behavior of these functions.

Larger applications are strongly encouraged to create and customize a different, private instance of Converter.

Converter objects

To create a private converter, simply instantiate a cattr.Converter. Currently, a converter contains the following state:

• a registry of unstructure hooks, backed by a singledispatch and a function_dispatch.
• a registry of structure hooks, backed by a different singledispatch and function_dispatch.
• a LRU cache of union disambiguation functions.
• a reference to an unstructuring strategy (either AS_DICT or AS_TUPLE).
• a dict_factory callable, used for creating dicts when dumping attrs classes using AS_DICT.

cattr.GenConverter

The GenConverter is a converter subclass that automatically generates, compiles and caches specialized structuring and unstructuring hooks for attrs classes.

GenConverter differs from the old cattr.Converter in the following ways:

• structuring and unstructuring of attrs classes is slower the first time, but faster every subsequent time
• structuring and unstructuring can be customized
• support for attrs classes with PEP563 (postponed) annotations
• support for generic attrs classes
• support for easy overriding collection unstructuring

The GenConverter will become the default converter type in a later release.