Migrations

cattrs sometimes changes in backwards-incompatible ways. This page contains guidance for changes and workarounds for restoring legacy behavior.

26.2.0

Naive datetimes unstructuring as UTC in the msgpack and cbor2 converters

The msgpack and cbor2 converters unstructure datetime s into UNIX timestamps using datetime.timestamp, which reads a naive datetime as local time. The serialized value therefore depended on the timezone of the machine doing the unstructuring, while the structure hooks read timestamps back as UTC. From this version on, naive datetime s are assumed to be UTC when unstructuring, so both ends of the round-trip agree and the payload no longer depends on the host.

Aware datetime s are unaffected.

The old behavior can be restored by registering datetime.timestamp directly on a converter.

>>> from datetime import datetime

>>> converter.register_unstructure_hook(datetime, datetime.timestamp)

25.3.0

Abstract sets structuring into frozensets

From this version on, abstract sets (collection.abc.Set) structure into frozensets.

The old behavior can be restored by registering the BaseConverter._structure_set method using the is_abstract_set predicate on a converter.

>>> from cattrs.cols import is_abstract_set

>>> converter.register_structure_hook_func(is_abstract_set, converter._structure_set)

25.2.0

Sequences structuring into tuples

Sequences were changed to structure into tuples instead of lists.

The old behavior can be restored by registering the list_structure_factory using the is_sequence predicate on a converter.

>>> from cattrs.cols import is_sequence, list_structure_factory

>>> converter.register_structure_hook_factory(is_sequence, list_structure_factory)

25.1.0

The default structure hook fallback factory

The default structure hook fallback factory was changed to more eagerly raise errors for missing hooks.

The old behavior can be restored by explicitly passing in the old hook fallback factory when instantiating the converter.

>>> from cattrs.fns import raise_error

>>> c = Converter(structure_fallback_factory=lambda _: raise_error)
# Or
>>> c = BaseConverter(structure_fallback_factory=lambda _: raise_error)

cattrs.gen.MappingStructureFn and cattrs.gen.DictStructureFn removal

The internal cattrs.gen.MappingStructureFn and cattrs.gen.DictStructureFn types were replaced by a more general type, cattrs.SimpleStructureHook[In, T]. If you were using MappingStructureFn, use SimpleStructureHook[Mapping[Any, Any], T] instead. If you were using DictStructureFn, use SimpleStructureHook[Mapping[str, Any], T] instead.