Cattrs

- _Potentially breaking_: `cattrs.Converter` has been renamed to `cattrs.BaseConverter`, and `cattrs.GenConverter` to `cattrs.Converter`.
The `GenConverter` name is still available for backwards compatibility, but is deprecated.
If you were depending on functionality specific to the old `Converter`, change your import to `from cattrs import BaseConverter`.
- [NewTypes](https://docs.python.org/3/library/typing.html#newtype) are now supported by the `cattrs.Converter`.
([255](https://github.com/python-attrs/cattrs/pull/255) [#94](https://github.com/python-attrs/cattrs/issues/94) [#297](https://github.com/python-attrs/cattrs/issues/297))
- `cattrs.Converter` and `cattrs.BaseConverter` can now copy themselves using the `copy` method.
([284](https://github.com/python-attrs/cattrs/pull/284))
- Python 3.11 support.
- cattrs now supports un/structuring `kw_only` fields on attrs classes into/from dictionaries.
([247](https://github.com/python-attrs/cattrs/pull/247))
- PyPy support (and tests, using a minimal Hypothesis profile) restored.
([253](https://github.com/python-attrs/cattrs/issues/253))
- Fix propagating the `detailed_validation` flag to mapping and counter structuring generators.
- Fix `typing.Set` applying too broadly when used with the `GenConverter.unstruct_collection_overrides` parameter on Python versions below 3.9. Switch to `typing.AbstractSet` on those versions to restore the old behavior.
([264](https://github.com/python-attrs/cattrs/issues/264))
- Uncap the required Python version, to avoid problems detailed [here](https://iscinumpy.dev/post/bound-version-constraints/#pinning-the-python-version-is-special)
([275](https://github.com/python-attrs/cattrs/issues/275))
- Fix `Converter.register_structure_hook_factory` and `cattrs.gen.make_dict_unstructure_fn` type annotations.
([281](https://github.com/python-attrs/cattrs/issues/281))
- Expose all error classes in the `cattr.errors` namespace. Note that it is deprecated, just use `cattrs.errors`.
([252](https://github.com/python-attrs/cattrs/issues/252))
- Fix generating structuring functions for types with quotes in the name.
([291](https://github.com/python-attrs/cattrs/issues/291) [#277](https://github.com/python-attrs/cattrs/issues/277))
- Fix usage of notes for the final version of [PEP 678](https://peps.python.org/pep-0678/), supported since `exceptiongroup>=1.0.0rc4`.
([303](https://github.com/python-attrs/cattrs/pull/303))

- _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))