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:
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 cattrs.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 creatingdicts
when dumping attrs classes usingAS_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 and dataclasses.
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
The Converter
used to be called GenConverter
, and that alias is still present for backwards compatibility reasons.
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.