# 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 ``Converter``

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

These converters support the following classes and type annotations, both for structuring and unstructuring:

- `str`, `bytes`, `int`, `float`, int enums, string enums

- `attrs` classes and `dataclasses`

- lists, homogenous tuples, heterogenous tuples, dictionaries, counters, sets, frozensets

- optionals

- sequences, mutable sequences, mappings, mutable mappings, sets, mutable sets

- `datetime.datetime`

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.

## 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 are serialized as ISO 8601 strings.

## `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 are serialized as ISO 8601 strings.

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

## `orjson`

Found at `cattrs.preconf.orjson`.

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

`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.

## `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.

`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.

## `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.

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.

## `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.