v25.3.0

• Potentially breaking: Abstract sets are now structured into frozensets.
  This allows hashability, better immutability and is more consistent with the collections.abc.Set type.
  See Migrations for steps to restore legacy behavior. (#686)
• Python 3.14 is now supported and part of the test matrix. (#653)
• Fix unstructuring NewTypes with the {class}BaseConverter. (#684)
• Make some Hypothesis tests more robust. (#684)
• {func}cattrs.strategies.include_subclasses now works with generic parent classes and the tagged union strategy. (#683)

New Contributors

• @danarmak made their first contribution in #683

Full Changelog: v25.2.0...v25.3.0

v25.2.0

• Potentially breaking: Sequences are now structured into tuples.
  This allows hashability, better immutability and is more consistent with the collections.abc.Sequence type. See Migrations for steps to restore legacy behavior. (#663)
• Add a use_alias parameter to cattrs.Converter.
  cattrs.gen.make_dict_unstructure_fn_from_attrs, cattrs.gen.make_dict_unstructure_fn,
  cattrs.gen.make_dict_structure_fn_from_attrs, cattrs.gen.make_dict_structure_fn
  and cattrs.gen.typeddicts.make_dict_structure_fn will use the value for the use_alias parameter from the given converter by default now. If you're using these functions directly, the old behavior can be restored by passing in the desired value directly. (#596 #660)
• The union passthrough strategy now by default accepts ints for unions that contain floats but not ints,
  when configured to be able to handle both ints and floats. This more closely matches the current typing behavior. (#656 #668)
• Fix unstructuring of generic classes with stringified annotations. (#661 #662)
• For cattrs.errors.StructureHandlerNotFoundError and cattrs.errors.ForbiddenExtraKeysError
  correctly set BaseException.args in super() and hence make them pickable. (#666)
• The default disambiguation hook factory is now only enabled for converters with unstructure_strat=AS_DICT (the default).
  Since the strategy doesn't support tuples, it is skipped for unstructure_strat=AS_TUPLE converters. (#673)
• Switch to uv and just in lieu of PDM, tox and Make. See the Contributing section for new workflow instructions. (#671)

New Contributors

• @hoodmane made their first contribution in #665
• @carltongibson made their first contribution in #677

Full Changelog: v25.1.1...v25.2.0

v25.1.1

• Fixed AttributeError: no attribute '__parameters__' while structuring attrs classes that inherit from parametrized generic aliases from collections.abc.
  (#654 #655)

v25.1.0

• Potentially breaking: The converters raise StructureHandlerNotFoundError more eagerly (on hook creation, instead of on hook use). This helps surfacing problems with missing hooks sooner. See Migrations for steps to restore legacy behavior.
  (#577)
• Add a Migrations page, with instructions on migrating changed behavior for each version.
  (#577)
• typing.Self is now supported in attrs classes, dataclasses, TypedDicts and the dict NamedTuple factories. See typing.Self for details.
  (#299 #627)
• PEP 695 type aliases can now be used with BaseConverter.register_structure_hook and BaseConverter.register_unstructure_hook. Previously, they required the use of BaseConverter.register_structure_hook_func (which is still supported).
  (#647)
• Expose cattrs.cols.mapping_unstructure_factory through cattrs.cols.
• Some defaultdicts are now supported by default, and
  cattrs.cols.is_defaultdict and cattrs.cols.defaultdict_structure_factory are exposed through cattrs.cols.
  (#519 #588)
• Generic PEP 695 type aliases are now supported.
  (#611 #618)
• The tagged union strategy now also supports type aliases of unions.
  (#649)
• Converter.copy and BaseConverter.copy are correctly annotated as returning Self.
  (#644)
• 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)
• The msgspec JSON preconf converter now handles dataclasses with private attributes more efficiently.
  (#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)
• Preconf converters now handle dictionaries with literal keys properly.
  (#599)
• Structuring TypedDicts from invalid inputs now properly raises a ClassValidationError.
  (#615 #616)
• cattrs.strategies.include_subclasses now properly works with generic parent classes.
  (#649)
• Replace cattrs.gen.MappingStructureFn with cattrs.SimpleStructureHook.
• Python 3.13 is now supported.
  (#543 #547)
• Python 3.8 is no longer supported, as it is end-of-life. Use previous versions on this Python version.
  (#591)
• Change type of Converter.__init__.unstruct_collection_overrides from Callable to Mapping[type, UnstructureHook]
  (#594).
• Adopt the Contributor Covenant Code of Conduct (just like attrs).

v24.1.3

• Fix structuring of keyword-only dataclass fields when not using detailed validation.
  (#637 #638)

v24.1.2

• Fix BaseConverter.register_structure_hook and BaseConverter.register_unstructure_hook type hints.
  (#581 #582)

24.1.1

24.1.1 (2024-09-11)

• Fix BaseConverter.register_structure_hook_factory and BaseConverter.register_unstructure_hook_factory type hints.
  (#578 #579)

24.1.0

• 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)
• 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)
• Minor change: 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 #528)
• Introduce BaseConverter.get_structure_hook and BaseConverter.get_unstructure_hook methods.
  (#432 #472)
• BaseConverter.register_structure_hook, BaseConverter.register_unstructure_hook,
  BaseConverter.register_unstructure_hook_factory and BaseConverter.register_structure_hook_factory
  can now be used as decorators and have gained new features.
  See here and here for more details.
  (#487)
• Introduce and document the cattrs.cols module for better collection customizations.
  (#504 #540)
• Enhance the 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 #556)
• Introduce the msgspec preconf converter <cattrs.preconf.msgspec>.
  Only JSON is supported for now, with other formats supported by msgspec to come later.
  (#481)
• The default union handler now properly takes renamed fields into account.
  (#472)
• The default union handler now also handles dataclasses.
  (#426 #477)
• Add support for PEP 695 type aliases.
  (#452)
• Add support for PEP 696 TypeVars with defaults.
  (#512)
• Add support for named tuples with type metadata (typing.NamedTuple).
  (#425 #491)
• Add support for optionally un/unstructuring named tuples using dictionaries.
  (#425 #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 #472)
• The preconf make_converter factories are now correctly typed.
  (#481)
• The orjson preconf converter now passes through dates and datetimes to orjson while unstructuring, greatly improving speed.
  (#463)
• cattrs.gen generators now attach metadata to the generated functions, making them introspectable.
  (#472)
• Structure hook factories in cattrs.gen now handle recursive classes better.
  (#540)
• The tagged union strategy now leaves the tags in the payload unless forbid_extra_keys is set.
  (#533 #534)
• More robust support for Annotated and NotRequired in TypedDicts.
  (#450)
• typing_extensions.Literal is now automatically structured, just like typing.Literal.
  (#460 #467)
• typing_extensions.Any is now supported and handled like typing.Any.
  (#488 #490)
• Optional types can now be consistently customized using register_structure_hook and register_unstructure_hook.
  (#529 #530)
• The BaseConverter now properly generates detailed validation errors for mappings.
  (#496)
• PEP 695 generics are now tested.
  (#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)
• The documentation has been significantly reworked.
  (#473)
• The docs now use the Inter font.
• Make type annotations for include_subclasses and tagged_union strategies more lenient.
  (#431)

v23.2.3

• Fix a regression when unstructuring dictionary values typed as Any.
  (#453 #462)
• Fix a regression when unstructuring unspecialized generic classes.
  (#465 #466)
• Optimize function source code caching.
  (#445 #464)
• Generate unique files only in case of linecache enabled.
  (#445 #441)

v23.2.2

• Fix a regression when unstructuring Any | None.
  (#453)