Converters

All cattrs functionality is exposed through a cattrs.Converter object. Global cattrs functions, such as cattrs.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 cattrs.global_converter. The following functions implicitly use this global converter:

• cattrs.structure

• cattrs.unstructure

• cattrs.structure_attrs_fromtuple

• cattrs.structure_attrs_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 cattrs.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.

Converters may be cloned using the cattrs.Converter.copy method. The new copy may be changed through the copy arguments, but will retain all manually registered hooks from the original.

cattrs.Converter

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

Converter differs from the cattrs.BaseConverter 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

cattrs.BaseConverter

The BaseConverter is a simpler and slower Converter variant. It does no code generation, so it may be faster on first-use which can be useful in specific cases, like CLI applications where startup time is more important than throughput.