# 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.