cattrs: Flexible Object Serialization and Validation
Because validation belongs to the edges.
cattrs is a Swiss Army knife for (un)structuring and validating data in Python. In practice, that means it converts unstructured dictionaries into proper classes and back, while validating their contents.
Example
cattrs works best with attrs classes, and dataclasses where simple (un-)structuring works out of the box, even for nested data, without polluting your data model with serialization details:
>>> from attrs import define
>>> from cattrs import structure, unstructure
>>> @define
... class C:
... a: int
... b: list[str]
>>> instance = structure({'a': 1, 'b': ['x', 'y']}, C)
>>> instance
C(a=1, b=['x', 'y'])
>>> unstructure(instance)
{'a': 1, 'b': ['x', 'y']}
Have a look at Why cattrs? for more examples!
Features
Recursive Unstructuring
- attrs classes and dataclasses are converted into dictionaries in a way similar to
attrs.asdict(), or into tuples in a way similar toattrs.astuple(). - Enumeration instances are converted to their values.
- Other types are let through without conversion. This includes types such as integers, dictionaries, lists and instances of non-attrs classes.
- Custom converters for any type can be registered using
register_unstructure_hook.
Recursive Structuring
Converts unstructured data into structured data, recursively, according to your specification given as a type. The following types are supported:
typing.Optional[T]and its 3.10+ form,T | None.list[T],typing.List[T],typing.MutableSequence[T],typing.Sequence[T]convert to lists.tupleandtyping.Tuple(both variants,tuple[T, ...]andtuple[X, Y, Z]).set[T],typing.MutableSet[T], andtyping.Set[T]convert to sets.frozenset[T], andtyping.FrozenSet[T]convert to frozensets.dict[K, V],typing.Dict[K, V],typing.MutableMapping[K, V], andtyping.Mapping[K, V]convert to dictionaries.typing.TypedDict, both ordinary and generic.typing.NewType- PEP 695 type aliases on 3.12+
- attrs classes with simple attributes and the usual
__init__1. - All attrs classes and dataclasses with the usual
__init__, if their complex attributes have type metadata. - Unions of supported attrs classes, given that all of the classes have a unique field.
- Unions of anything, if you provide a disambiguation function for it.
- Custom converters for any type can be registered using
register_structure_hook.
Batteries Included
cattrs comes with pre-configured converters for a number of serialization libraries, including JSON (standard library, orjson, UltraJSON), msgpack, cbor2, bson, PyYAML, tomlkit and msgspec (supports only JSON at this time).
For details, see the cattrs.preconf package.
Design Decisions
cattrs is based on a few fundamental design decisions:
- Un/structuring rules are separate from the models.
This allows models to have a one-to-many relationship with un/structuring rules, and to create un/structuring rules for models which you do not own and you cannot change.
(cattrs can be configured to use un/structuring rules from models using the
use_class_methodsstrategy.) - Invent as little as possible; reuse existing ordinary Python instead.
For example, cattrs did not have a custom exception type to group exceptions until the sanctioned Python
exceptiongroups. A side-effect of this design decision is that, in a lot of cases, when you're solving cattrs problems you're actually learning Python instead of learning cattrs. - Resist the temptation to guess. If there are two ways of solving a problem, cattrs should refuse to guess and let the user configure it themselves.
A foolish consistency is the hobgoblin of little minds, so these decisions can and are sometimes broken, but they have proven to be a good foundation.
Credits
Major credits to Hynek Schlawack for creating attrs and its predecessor, characteristic.
cattrs is tested with Hypothesis, by David R. MacIver.
cattrs is benchmarked using perf and pytest-benchmark.
This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.
-
Simple attributes are attributes that can be assigned unstructured data, like numbers, strings, and collections of unstructured data. ↩
1 maintainer
Release files for cattrs 26.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cattrs-26.2.1.tar.gz | 525.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cattrs-26.2.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 600.5 kB
Release files / cattrs-26.2.1.tar.gz
| Download URL | cattrs-26.2.1.tar.gz |
|---|---|
| Size | 525.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
679132bfdc225c5ee40c024fc42519954767c387f950dc6751946c586bccdc6d
|
|
BLAKE2b-256 checksum How to use checksums |
2375e72b839c3dc869c990b4842f3dba730bdcdf5215f68fc7955edf849a1792
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / cattrs-26.2.1-py3-none-any.whl
| Download URL | cattrs-26.2.1-py3-none-any.whl |
|---|---|
| Size | 74.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a12aaa3453dc8f633a815293179f08b7421ed18d2575c459c3c736f840beac24
|
|
BLAKE2b-256 checksum How to use checksums |
e8cf22794a399d99480486120e26e879ef008e21f5e85274c2ed591d568bb326
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency log
