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)

v23.2.1

23.2.1 (2023-11-18)

• Fix unnecessary typing_extensions import on Python 3.11.
  (#446 #447)

For the v23.2.0 release notes, see here.

v23.2.0

23.2.0 (2023-11-17)

Welcome to cattrs 23.2.0! Thanks to all our wonderful contributors, this release happens to have the largest changelog so far.

Here are some of the noteworthy additions, see below for the entire changelog.

More Powerful Unions in preconf

Courtesy of the union passthrough strategy, the following class (and others like it, this is just a complex example) will work out-of-the-box on any preconf converter:

@define
class MyClass:
    my_field: str | Literal[1] | MyOtherClass

The strategy has been preapplied to all preconf converters, but it can be manually applied to any converter.

Default Disambiguation via Literals

When structuring a union of attrs classes, cattrs will default to the default union strategy.

This strategy works by finding required unique fields in the given classes.
It has been enhanced with support for matching on fields annotated as Literals.

from typing import Literal

@define
class ClassA:
    field_one: Literal["one"]

@define
class ClassB:
    field_one: Literal["two"] = "two"

Un/structuring Hooks on Classes

cattrs defaults to having un/structuring hooks separate from the models.
With the use class methods strategy, you are free to defy this design decision and configure a converter to look for hooks on the models themselves.

The Complete Changelog

• Potentially breaking: skip attrs fields marked as init=False by default. This change is potentially breaking for unstructuring.
  See here for instructions on how to restore the old behavior.
  (#40 #395)
• Potentially breaking: cattrs.gen.make_dict_structure_fn and cattrs.gen.typeddicts.make_dict_structure_fn will use the values for the detailed_validation and forbid_extra_keys parameters 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 values directly.
  (#410 #411)
• Potentially breaking: The default union structuring strategy will also use fields annotated as typing.Literal to help guide structuring.
  See here for instructions on how to restore the old behavior.
  (#391)
• Python 3.12 is now supported. Python 3.7 is no longer supported; use older releases there.
  (#424)
• Implement the union passthrough strategy, enabling much richer union handling for preconfigured converters. Learn more here.
• Introduce the use_class_methods strategy. Learn more here.
  (#405)
• The omit parameter of cattrs.override is now of type bool | None (from bool).
  None is the new default and means to apply default cattrs handling to the attribute, which is to omit the attribute if it's marked as init=False, and keep it otherwise.
• Converters can now be initialized with custom fallback hook factories for un/structuring.
  (#331 #441)
• Add support for date to preconfigured converters.
  (#420)
• Add support for datetime.dates to the PyYAML preconfigured converter.
  (#393)
• Fix format_exception() parameter working for recursive calls to transform_error().
  (#389)
• attrs aliases are now supported, although aliased fields still map to their attribute name instead of their alias by default when un/structuring.
  (#322 #391)
• Fix TypedDicts with periods in their field names.
  (#376 #377)
• Optimize and improve unstructuring of Optional (unions of one type and None).
  (#380 #381)
• Fix format_exception and transform_error type annotations.
• Improve the implementation of cattrs._compat.is_typeddict. The implementation is now simpler, and relies on fewer private implementation details from typing and typing_extensions.
  (#384)
• Improve handling of TypedDicts with forward references.
• Speed up generated attrs and TypedDict structuring functions by changing their signature slightly.
  (#388)
• Fix copying of converters with function hooks.
  (#398 #399)
• Broaden cattrs.preconf.orjson.OrjsonConverter.loads type definition for the preconf orjson converter.
  (#400)
• AttributeValidationNote and IterableValidationNote are now picklable.
  (#408)
• Fix structuring Final lists.
  (#412)
• Fix certain cases of structuring Annotated types.
  (#418)
• Fix the tagged union strategy to work with forbid_extra_keys.
  (#402 #443)
• Use PDM instead of Poetry.
• cattrs is now linted with Ruff.
• Remove some unused lines in the unstructuring code.
  (#416)
• Fix handling classes inheriting from non-generic protocols.
  (#374 #436)
• The documentation Makefile now supports the htmlview and htmllive targets. (#442)
• cattrs is now published using PyPI Trusted Publishers, and main branch commits are automatically deployed to Test PyPI.