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 afunction_dispatch
.a registry of structure hooks, backed by a different
singledispatch
andfunction_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 dumpingattrs
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.
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 timestructuring and unstructuring can be customized
support for
attrs
classes with PEP563 (postponed) annotationssupport for generic
attrs
classessupport 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.