Cattrs

- _cattrs_ now uses the CalVer versioning convention.
- _cattrs_ now has a detailed validation mode, which is enabled by default. Learn more [here](https://cattrs.readthedocs.io/en/latest/validation.html).
The old behavior can be restored by creating the converter with `detailed_validation=False`.
- _attrs_ and dataclass structuring is now ~25% faster.
- Fix an issue structuring bare `typing.List` s on Pythons lower than 3.9.
([209](https://github.com/python-attrs/cattrs/issues/209))
- Fix structuring of non-parametrized containers like `list/dict/...` on Pythons lower than 3.9.
([218](https://github.com/python-attrs/cattrs/issues/218))
- Fix structuring bare `typing.Tuple` on Pythons lower than 3.9.
([218](https://github.com/python-attrs/cattrs/issues/218))
- Fix a wrong `AttributeError` of an missing `__parameters__` attribute. This could happen
when inheriting certain generic classes – for example `typing.*` classes are affected.
([217](https://github.com/python-attrs/cattrs/issues/217))
- Fix structuring of `enum.Enum` instances in `typing.Literal` types.
([231](https://github.com/python-attrs/cattrs/pull/231))
- Fix unstructuring all tuples - unannotated, variable-length, homogenous and heterogenous - to `list`.
([226](https://github.com/python-attrs/cattrs/issues/226))
- For `forbid_extra_keys` raise custom `ForbiddenExtraKeyError` instead of generic `Exception`.
([225](https://github.com/python-attrs/cattrs/pull/225))
- All preconf converters now support `loads` and `dumps` directly. See an example [here](https://cattrs.readthedocs.io/en/latest/preconf.html).
- Fix mappings with byte keys for the orjson, bson and tomlkit converters.
([241](https://github.com/python-attrs/cattrs/issues/241))

{note}
In this release, _cattrs_ introduces the {mod}`cattrs` package as the main entry point into the library, replacing the `cattr` package.

The `cattr` package is never going away, nor is it technically deprecated.
New functionality will be added only to the `cattrs` package, but there is no need to replace your current imports.

This change mirrors [a similar change in _attrs_](https://www.attrs.org/en/stable/names.html).


- Add [PEP 563 (string annotations)](https://peps.python.org/pep-0563/) support for dataclasses.
([195](https://github.com/python-attrs/cattrs/issues/195))
- Fix handling of dictionaries with string Enum keys for bson, orjson, and tomlkit.
- Rename the {func}`cattrs.gen.make_dict_unstructure_fn` `omit_if_default` parameter to `_cattrs_omit_if_default`, for consistency. The `omit_if_default` parameters to {class}`GenConverter` and {func}`override` are unchanged.
- Following the changes in _attrs_ 21.3.0, add a {mod}`cattrs` package mirroring the existing `cattr` package. Both package names may be used as desired, and the `cattr` package isn't going away.

- Python 3.10 support, including support for the new union syntax (`A | B` vs `Union[A, B]`).
- The `GenConverter` can now properly structure generic classes with generic collection fields.
([149](https://github.com/python-attrs/cattrs/issues/149))
- `omit=True` now also affects generated structuring functions.
([166](https://github.com/python-attrs/cattrs/issues/166))
- `cattr.gen.{make_dict_structure_fn, make_dict_unstructure_fn}` now resolve type annotations automatically when PEP 563 is used.
([169](https://github.com/python-attrs/cattrs/issues/169))
- Protocols are now unstructured as their runtime types.
([177](https://github.com/python-attrs/cattrs/pull/177))
- Fix an issue generating structuring functions with renaming and `_cattrs_forbid_extra_keys=True`.
([190](https://github.com/python-attrs/cattrs/issues/190))

- Fix `GenConverter` mapping structuring for unannotated dicts on Python 3.8.
([151](https://github.com/python-attrs/cattrs/issues/151))
- The source code for generated un/structuring functions is stored in the `linecache` cache, which enables more informative stack traces when un/structuring errors happen using the `GenConverter`. This behavior can optionally be disabled to save memory.
- Support using the attr converter callback during structure.
By default, this is a method of last resort, but it can be elevated to the default by setting `prefer_attrib_converters=True` on `Converter` or `GenConverter`.
([138](https://github.com/python-attrs/cattrs/issues/138))
- Fix structuring recursive classes.
([159](https://github.com/python-attrs/cattrs/issues/159))
- Converters now support un/structuring hook factories. This is the most powerful and complex venue for customizing un/structuring. This had previously been an internal feature.
- The [Common Usage Examples](https://cattrs.readthedocs.io/en/latest/usage.html#using-factory-hooks) documentation page now has a section on advanced hook factory usage.
- `cattr.override` now supports the `omit` parameter, which makes _cattrs_ skip the atribute entirely when unstructuring.
- The `cattr.preconf.bson` module is now tested against the `bson` module bundled with the `pymongo` package, because that package is much more popular than the standalone PyPI `bson` package.

- `Literal` s are not supported on Python 3.9.0 (supported on 3.9.1 and later), so we skip importing them there.
([150](https://github.com/python-attrs/cattrs/issues/150))

- `cattr.global_converter` (which provides `cattr.unstructure`, `cattr.structure` etc.) is now an instance of `cattr.GenConverter`.
- `Literal` s are now supported and validated when structuring.
- Fix dependency metadata information for _attrs_.
([147](https://github.com/python-attrs/cattrs/issues/147))
- Fix `GenConverter` mapping structuring for unannotated dicts.
([148](https://github.com/python-attrs/cattrs/issues/148))