Preconfigured Converters#

The cattrs.preconf package contains factories for preconfigured converters, specifically adjusted for particular serialization libraries.

For example, to get a converter configured for BSON:

>>> from cattrs.preconf.bson import make_converter

>>> converter = make_converter() # Takes the same parameters as the `cattrs.Converter`

Converters obtained this way can be customized further, just like any other converter.

These converters support all default hooks and the following additional classes and type annotations, both for structuring and unstructuring:

  • datetime.datetime, datetime.date

New in version 22.1.0: All preconf converters now have loads and dumps methods, which combine un/structuring and the de/serialization logic from their underlying libraries.

>>> from cattrs.preconf.json import make_converter

>>> converter = make_converter()

>>> @define
... class Test:
...     a: int

>>> converter.dumps(Test(1))
'{"a": 1}'

Particular libraries may have additional constraints documented below.

Third-party libraries can be specified as optional (extra) dependencies on cattrs during installation. Optional install targets should match the name of the cattrs.preconf modules.

# Using pip
$ pip install cattrs[ujson]

# Using pdm
$ pdm add cattrs[orjson]

# Using poetry
$ poetry add --extras tomlkit cattrs

Standard Library json#

Found at cattrs.preconf.json.

Bytes are serialized as base 85 strings. Counters are serialized as dictionaries. Sets are serialized as lists, and deserialized back into sets. datetime s and date s are serialized as ISO 8601 strings.

orjson#

Found at cattrs.preconf.orjson.

Bytes are un/structured as base 85 strings. Sets are unstructured into lists, and structured back into sets. datetime s and date s are passed through to be unstructured into RFC 3339 by orjson itself. Typed named tuples are unstructured into ordinary tuples, and then into JSON arrays by orjson.

orjson doesn’t support integers less than -9223372036854775808, and greater than 9223372036854775807. orjson only supports mappings with string keys so mappings will have their keys stringified before serialization, and destringified during deserialization.

msgspec#

Found at cattrs.preconf.msgspec. Only JSON functionality is currently available, other formats supported by msgspec to follow in the future.

msgspec structs are supported, but not composable - a struct will be handed over to msgspec directly, and msgspec will handle and all of its fields, recursively. cattrs may get more sophisticated handling of structs in the future.

msgspec strict mode is used by default. This can be customized by changing the encoder attribute on the converter.

What cattrs calls unstructuring and structuring, msgspec calls to_builtins and convert. What cattrs refers to as dumping and loading, msgspec refers to as encoding and decoding.

Compatibility notes:

  • Bytes are un/structured as base 64 strings directly by msgspec itself.

  • msgspec encodes special float values (NaN, Inf, -Inf) as null.

  • datetime s and date s are passed through to be unstructured into RFC 3339 by msgspec itself.

  • attrs classes, dataclasses and sequences are handled directly by msgspec if possible, otherwise by the normal cattrs machinery. This means it’s possible the validation errors produced may be msgspec validation errors instead of cattrs validation errors.

This converter supports get_loads_hook() and get_dumps_hook(). These are factories for dumping and loading functions (as opposed to unstructuring and structuring); the hooks returned by this may be further optimized to offload as much work as possible to msgspec.

>>> from cattrs.preconf.msgspec import make_converter

>>> @define
... class Test:
...     a: int

>>> converter = make_converter()
>>> dumps = converter.get_dumps_hook(A)

>>> dumps(Test(1))  # Will use msgspec directly.
b'{"a":1}'

Due to its complexity, this converter is currently provisional and may slightly change as the best integration patterns are discovered.

msgspec doesn’t support PyPy.

New in version 24.1.0.

ujson#

Found at cattrs.preconf.ujson.

Bytes are serialized as base 85 strings. Sets are serialized as lists, and deserialized back into sets. datetime s and date s are serialized as ISO 8601 strings.

ujson doesn’t support integers less than -9223372036854775808, and greater than 9223372036854775807, nor does it support float('inf').

msgpack#

Found at cattrs.preconf.msgpack.

Sets are serialized as lists, and deserialized back into sets. datetime s are serialized as UNIX timestamp float values. date s are serialized as midnight-aligned UNIX timestamp float values.

msgpack doesn’t support integers less than -9223372036854775808, and greater than 18446744073709551615.

When parsing msgpack data from bytes, the library needs to be passed strict_map_key=False to get the full range of compatibility.

cbor2#

Found at cattrs.preconf.cbor2.

cbor2 implements a fully featured CBOR encoder with several extensions for handling shared references, big integers, rational numbers and so on.

Sets are serialized and deserialized to sets. Tuples are serialized as lists.

datetime s are serialized as a text string by default (CBOR Tag 0). Use keyword argument datetime_as_timestamp=True to encode as UNIX timestamp integer/float (CBOR Tag 1) note: this replaces timezone information as UTC.

date s are serialized as ISO 8601 strings.

Use keyword argument canonical=True for efficient encoding to the smallest binary output.

Floats can be forced to smaller output by casting to lower-precision formats by casting to numpy floats (and back to Python floats). Example: float(np.float32(value)) or float(np.float16(value))

New in version 23.1.0.

bson#

Found at cattrs.preconf.bson. Tested against the bson module bundled with the pymongo library, not the standalone PyPI bson package.

Sets are serialized as lists, and deserialized back into sets.

bson doesn’t support integers less than -9223372036854775808 or greater than 9223372036854775807 (64-bit signed). bson does not support null bytes in mapping keys. bson only supports mappings with string keys so mappings will have their keys stringified before serialization, and destringified during deserialization. The bson datetime representation doesn’t support microsecond accuracy. date s are serialized as ISO 8601 strings.

When encoding and decoding, the library needs to be passed codec_options=bson.CodecOptions(tz_aware=True) to get the full range of compatibility.

pyyaml#

Found at cattrs.preconf.pyyaml.

Frozensets are serialized as lists, and deserialized back into frozensets. date s are serialized as ISO 8601 strings. Typed named tuples are unstructured into ordinary tuples, and then into YAML arrays by pyyaml.

tomlkit#

Found at cattrs.preconf.tomlkit.

Bytes are serialized as base 85 strings. Sets are serialized as lists, and deserialized back into sets. Tuples are serialized as lists, and deserialized back into tuples. tomlkit only supports mappings with string keys so mappings will have their keys stringified before serialization, and destringified during deserialization. date s are serialized as ISO 8601 strings.