========== 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_attrs_fromtuple`` * ``cattr.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 ``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