cattrs: Composable Attrs/Dataclass Structuring

26.1.0 · active · verified Sat Mar 28

cattrs is a Python library (version 26.1.0) that provides composable tools for converting between unstructured Python data (like dictionaries) and structured data (like `attrs` classes and `dataclasses`). It excels at recursively structuring and unstructuring data while supporting type hints and offering extensive customization via hooks. Releases are frequent, often including breaking changes across minor versions.

Warnings

breaking As of v25.3.0, abstract sets (`collections.abc.Set`) are now structured into `frozenset` by default, instead of `set`. This might affect code expecting mutable sets.
Fix: If the previous behavior (structuring into `set`) is required, register a custom structure hook for `collections.abc.Set` on your converter instance (e.g., `converter.register_structure_hook(Set, lambda d, t: set(d))`).
breaking As of v25.2.0, sequences (`collections.abc.Sequence`) are now structured into `tuple` by default, instead of `list`. This change provides better immutability and consistency.
Fix: If the previous behavior (structuring into `list`) is required, register a custom structure hook for `collections.abc.Sequence` on your converter instance (e.g., `converter.register_structure_hook(Sequence, lambda d, t: list(d))`).
breaking As of v25.1.0, `StructureHandlerNotFoundError` is raised more eagerly (on hook creation rather than on first use). This helps surface missing hooks sooner.
Fix: Ensure all types intended for structuring have appropriate hooks registered *before* attempting to use the converter. Consult the `cattrs` migration guide for details on customizing `unstructure_hook_fallback_factory` if necessary.
breaking As of v24.1.0, unstructuring hooks for `typing.Any` now consistently use the runtime type of the value. Previously, this behavior was underspecified and inconsistent.
Fix: If your application relied on the previous inconsistent behavior for `typing.Any`, you may need to explicitly register custom `unstructure_hook`s for specific types or `typing.Any` to achieve the desired effect.
gotcha The top-level `cattrs.structure()` and `cattrs.unstructure()` functions operate on a global converter instance. Registering hooks or changing settings on this global converter can lead to unexpected side effects across different parts of an application or in library code.
Fix: For complex applications or when developing libraries, it is strongly recommended to create and manage your own `cattrs.Converter()` instance(s) and register hooks on those private instances to avoid polluting the global state.

Install

pip install cattrs Install latest version

Imports

structure
```
from cattrs import structure
```
unstructure
```
from cattrs import unstructure
```
Converter
```
from cattrs import Converter
```

Quickstart

Demonstrates basic structuring of a dictionary into an `attrs` class instance and unstructuring it back, using the global converter.

from attrs import define
from cattrs import structure, unstructure

@define
class User:
    id: int
    name: str
    email: str

# Unstructured data (e.g., from JSON)
unstructured_data = {"id": 1, "name": "Alice", "email": "alice@example.com"}

# Structure into a User instance
user_instance = structure(unstructured_data, User)
print(f"Structured: {user_instance}")

# Unstructure back to a dictionary
unstructured_output = unstructure(user_instance)
print(f"Unstructured: {unstructured_output}")

view raw JSON →