Cattrs

- **Potentially breaking**: The converters raise {class}`StructureHandlerNotFoundError` more eagerly (on hook creation, instead of on hook use).
This helps surfacing problems with missing hooks sooner.
See [Migrations](https://catt.rs/en/latest/migrations.html#the-default-structure-hook-fallback-factory) for steps to restore legacy behavior.
([577](https://github.com/python-attrs/cattrs/pull/577))
- Add a [Migrations](https://catt.rs/en/latest/migrations.html) page, with instructions on migrating changed behavior for each version.
([577](https://github.com/python-attrs/cattrs/pull/577))
- [`typing.Self`](https://docs.python.org/3/library/typing.html#typing.Self) is now supported in _attrs_ classes, dataclasses, TypedDicts and the dict NamedTuple factories.
See [`typing.Self`](https://catt.rs/en/latest/defaulthooks.html#typing-self) for details.
([299](https://github.com/python-attrs/cattrs/issues/299) [#627](https://github.com/python-attrs/cattrs/pull/627))
- Expose {func}`cattrs.cols.mapping_unstructure_factory` through {mod}`cattrs.cols`.
- Some `defaultdicts` are now [supported by default](https://catt.rs/en/latest/defaulthooks.html#defaultdicts), and
{func}`cattrs.cols.is_defaultdict` and {func}`cattrs.cols.defaultdict_structure_factory` are exposed through {mod}`cattrs.cols`.
([519](https://github.com/python-attrs/cattrs/issues/519) [#588](https://github.com/python-attrs/cattrs/pull/588))
- Generic PEP 695 type aliases are now supported.
([611](https://github.com/python-attrs/cattrs/issues/611) [#618](https://github.com/python-attrs/cattrs/pull/618))
- Many preconf converters (_bson_, stdlib JSON, _cbor2_, _msgpack_, _msgspec_, _orjson_, _ujson_) skip unstructuring `int` and `str` enums,
leaving them to the underlying libraries to handle with greater efficiency.
([598](https://github.com/python-attrs/cattrs/pull/598))
- The {class}`msgspec JSON preconf converter <cattrs.preconf.msgspec.MsgspecJsonConverter>` now handles dataclasses with private attributes more efficiently.
([624](https://github.com/python-attrs/cattrs/pull/624))
- Literals containing enums are now unstructured properly, and their unstructuring is greatly optimized in the _bson_, stdlib JSON, _cbor2_, _msgpack_, _msgspec_, _orjson_ and _ujson_ preconf converters.
([598](https://github.com/python-attrs/cattrs/pull/598))
- Preconf converters now handle dictionaries with literal keys properly.
([599](https://github.com/python-attrs/cattrs/pull/599))
- Structuring TypedDicts from invalid inputs now properly raises a {class}`ClassValidationError`.
([615](https://github.com/python-attrs/cattrs/issues/615) [#616](https://github.com/python-attrs/cattrs/pull/616))
- Replace `cattrs.gen.MappingStructureFn` with {class}`cattrs.SimpleStructureHook`.
- Python 3.13 is now supported.
([543](https://github.com/python-attrs/cattrs/pull/543) [#547](https://github.com/python-attrs/cattrs/issues/547))
- Python 3.8 is no longer supported, as it is end-of-life. Use previous versions on this Python version.
([591](https://github.com/python-attrs/cattrs/pull/591))
- Change type of `Converter.__init__.unstruct_collection_overrides` from `Callable` to `Mapping[type, UnstructureHook]`
([594](https://github.com/python-attrs/cattrs/pull/594)).
- Adopt the Contributor Covenant Code of Conduct (just like _attrs_).

- Fix structuring of keyword-only dataclass fields when not using detailed validation.
([637](https://github.com/python-attrs/cattrs/issues/637) [#638](https://github.com/python-attrs/cattrs/pull/638))

- Fix {meth}`BaseConverter.register_structure_hook` and {meth}`BaseConverter.register_unstructure_hook` type hints.
([581](https://github.com/python-attrs/cattrs/issues/581) [#582](https://github.com/python-attrs/cattrs/pull/582))

- Fix {meth}`BaseConverter.register_structure_hook_factory` and {meth}`BaseConverter.register_unstructure_hook_factory` type hints.
([578](https://github.com/python-attrs/cattrs/issues/578) [#579](https://github.com/python-attrs/cattrs/pull/579))

- **Potentially breaking**: Unstructuring hooks for `typing.Any` are consistent now: values are unstructured using their runtime type.
Previously this behavior was underspecified and inconsistent, but followed this rule in the majority of cases.
Reverting old behavior is very dependent on the actual case; ask on the issue tracker if in doubt.
([473](https://github.com/python-attrs/cattrs/pull/473))
- **Minor change**: Heterogeneous tuples are now unstructured into tuples instead of lists by default; this is significantly faster and widely supported by serialization libraries.
([486](https://github.com/python-attrs/cattrs/pull/486))
- **Minor change**: {func}`cattrs.gen.make_dict_structure_fn` will use the value for the `prefer_attrib_converters` parameter from the given converter by default now.
If you're using this function directly, the old behavior can be restored by passing in the desired values explicitly.
([527](https://github.com/python-attrs/cattrs/issues/527) [#528](https://github.com/python-attrs/cattrs/pull/528))
- Introduce {meth}`BaseConverter.get_structure_hook` and {meth}`BaseConverter.get_unstructure_hook` methods.
([432](https://github.com/python-attrs/cattrs/issues/432) [#472](https://github.com/python-attrs/cattrs/pull/472))
- {meth}`BaseConverter.register_structure_hook`, {meth}`BaseConverter.register_unstructure_hook`,
{meth}`BaseConverter.register_unstructure_hook_factory` and {meth}`BaseConverter.register_structure_hook_factory`
can now be used as decorators and have gained new features.
See [here](https://catt.rs/en/latest/customizing.html#use-as-decorators) and [here](https://catt.rs/en/latest/customizing.html#id1) for more details.
([487](https://github.com/python-attrs/cattrs/pull/487))
- Introduce and [document](https://catt.rs/en/latest/customizing.html#customizing-collections) the {mod}`cattrs.cols` module for better collection customizations.
([504](https://github.com/python-attrs/cattrs/issues/504) [#540](https://github.com/python-attrs/cattrs/pull/540))
- Enhance the {func}`cattrs.cols.is_mapping` predicate function to also cover virtual subclasses of `abc.Mapping`.
This enables map classes from libraries such as _immutables_ or _sortedcontainers_ to structure out-of-the-box.
([555](https://github.com/python-attrs/cattrs/issues/555) [#556](https://github.com/python-attrs/cattrs/pull/556))
- Introduce the [_msgspec_](https://jcristharif.com/msgspec/) {mod}`preconf converter <cattrs.preconf.msgspec>`.
Only JSON is supported for now, with other formats supported by _msgspec_ to come later.
([481](https://github.com/python-attrs/cattrs/pull/481))
- The default union handler now properly takes renamed fields into account.
([472](https://github.com/python-attrs/cattrs/pull/472))
- The default union handler now also handles dataclasses.
([426](https://github.com/python-attrs/cattrs/issues/426) [#477](https://github.com/python-attrs/cattrs/pull/477))
- Add support for [PEP 695](https://peps.python.org/pep-0695/) type aliases.
([452](https://github.com/python-attrs/cattrs/pull/452))
- Add support for [PEP 696](https://peps.python.org/pep-0696/) `TypeVar`s with defaults.
([512](https://github.com/python-attrs/cattrs/pull/512))
- Add support for named tuples with type metadata ([`typing.NamedTuple`](https://docs.python.org/3/library/typing.html#typing.NamedTuple)).
([425](https://github.com/python-attrs/cattrs/issues/425) [#491](https://github.com/python-attrs/cattrs/pull/491))
- Add support for optionally un/unstructuring named tuples using dictionaries.
([425](https://github.com/python-attrs/cattrs/issues/425) [#549](https://github.com/python-attrs/cattrs/pull/549))
- The `include_subclasses` strategy now fetches the member hooks from the converter (making use of converter defaults) if overrides are not provided, instead of generating new hooks with no overrides.
([429](https://github.com/python-attrs/cattrs/issues/429) [#472](https://github.com/python-attrs/cattrs/pull/472))
- The preconf `make_converter` factories are now correctly typed.
([481](https://github.com/python-attrs/cattrs/pull/481))
- The {class}`orjson preconf converter <cattrs.preconf.orjson.OrjsonConverter>` now passes through dates and datetimes to orjson while unstructuring, greatly improving speed.
([463](https://github.com/python-attrs/cattrs/pull/463))
- {mod}`cattrs.gen` generators now attach metadata to the generated functions, making them introspectable.
([472](https://github.com/python-attrs/cattrs/pull/472))
- Structure hook factories in {mod}`cattrs.gen` now handle recursive classes better.
([540](https://github.com/python-attrs/cattrs/pull/540))
- The [tagged union strategy](https://catt.rs/en/stable/strategies.html#tagged-unions-strategy) now leaves the tags in the payload unless `forbid_extra_keys` is set.
([533](https://github.com/python-attrs/cattrs/issues/533) [#534](https://github.com/python-attrs/cattrs/pull/534))
- More robust support for `Annotated` and `NotRequired` in TypedDicts.
([450](https://github.com/python-attrs/cattrs/pull/450))
- `typing_extensions.Literal` is now automatically structured, just like `typing.Literal`.
([460](https://github.com/python-attrs/cattrs/issues/460) [#467](https://github.com/python-attrs/cattrs/pull/467))
- `typing_extensions.Any` is now supported and handled like `typing.Any`.
([488](https://github.com/python-attrs/cattrs/issues/488) [#490](https://github.com/python-attrs/cattrs/pull/490))
- `Optional` types can now be consistently customized using `register_structure_hook` and `register_unstructure_hook`.
([529](https://github.com/python-attrs/cattrs/issues/529) [#530](https://github.com/python-attrs/cattrs/pull/530))
- The BaseConverter now properly generates detailed validation errors for mappings.
([496](https://github.com/python-attrs/cattrs/pull/496))
- [PEP 695](https://peps.python.org/pep-0695/) generics are now tested.
([452](https://github.com/python-attrs/cattrs/pull/452))
- Imports are now sorted using Ruff.
- Tests are run with the pytest-xdist plugin by default.
- Rework the introductory parts of the documentation, introducing the Basics section.
([472](https://github.com/python-attrs/cattrs/pull/472))
- The documentation has been significantly reworked.
([473](https://github.com/python-attrs/cattrs/pull/473))
- The docs now use the Inter font.
- Make type annotations for `include_subclasses` and `tagged_union` strategies more lenient.
([431](https://github.com/python-attrs/cattrs/pull/431))

- Fix a regression when unstructuring dictionary values typed as `Any`.
([453](https://github.com/python-attrs/cattrs/issues/453) [#462](https://github.com/python-attrs/cattrs/pull/462))
- Fix a regression when unstructuring unspecialized generic classes.
([465](https://github.com/python-attrs/cattrs/issues/465) [#466](https://github.com/python-attrs/cattrs/pull/466))
- Optimize function source code caching.
([445](https://github.com/python-attrs/cattrs/issues/445) [#464](https://github.com/python-attrs/cattrs/pull/464))
- Generate unique files only in case of linecache enabled.
([445](https://github.com/python-attrs/cattrs/issues/445) [#441](https://github.com/python-attrs/cattrs/pull/461))