All cattrs functionality is exposed through a
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.
A global converter is provided for convenience as
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
To create a private converter, simply instantiate a
Currently, a converter contains the following state:
a registry of unstructure hooks, backed by a singledispatch and a
a registry of structure hooks, backed by a different singledispatch and
a LRU cache of union disambiguation functions.
a reference to an unstructuring strategy (either AS_DICT or AS_TUPLE).
dict_factorycallable, used for creating
dictswhen dumping attrs classes using
Converters may be cloned using the
The new copy may be changed through the
copy arguments, but will retain all manually registered hooks from the original.
Fallback Hook Factories#
By default, when a
converter cannot handle a type it will:
when unstructuring, pass the value through unchanged
when structuring, raise a
cattrs.errors.StructureHandlerNotFoundErrorasking the user to add configuration
These behaviors can be customized by providing custom hook factories when creating the converter.
>>> from pickle import dumps >>> class Unsupported: ... """An artisinal (non-attrs) class, unsupported by default.""" >>> converter = Converter(unstructure_fallback_factory=lambda _: dumps) >>> instance = Unsupported() >>> converter.unstructure(instance) b'\x80\x04\x95\x18\x00\x00\x00\x00\x00\x00\x00\x8c\x08__main__\x94\x8c\x04Test\x94\x93\x94)\x81\x94.'
This also enables converters to be chained.
>>> parent = Converter() >>> child = Converter( ... unstructure_fallback_factory=parent._unstructure_func.dispatch, ... structure_fallback_factory=parent._structure_func.dispatch, ... )
Converter._unstructure_func.dispatch are slated to become public APIs in a future release.
New in version 23.2.0.
Converter is a converter variant that automatically generates, compiles and caches specialized structuring and unstructuring hooks for attrs classes, dataclasses and TypedDicts.
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
Converter used to be called
GenConverter, and that alias is still present for backwards compatibility reasons.
BaseConverter is a simpler and slower
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.