事前構成されたコンバーター¶
cattrs.preconf パッケージには、特定のシリアライゼーション・ライブラリーに合わせて調整された、事前構成済みのコンバーターのファクトリーが含まれています。
例えば、BSON 用に構成されたコンバーターを取得するには:
>>> from cattrs.preconf.bson import make_converter
>>> converter = make_converter() # Takes the same parameters as the `cattrs.Converter`
この方法で取得したコンバーターは、他のコンバーターと同様に、さらにカスタマイズできます。
これらのコンバーターは、すべてのデフォルト・フックと、構造化と非構造化の両方について、以下の追加クラスと型アノテーションをサポートします:
datetime.datetime、datetime.date
Added in version 22.1.0: すべての preconf コンバーターは、loads メソッドと dumps メソッドを持つようになりました。これらのメソッドは、un/structuring と、基盤となるライブラリーからのデ/シリアライゼーション・ロジックを組み合わせたものです。
>>> from cattrs.preconf.json import make_converter
>>> converter = make_converter()
>>> @define
... class Test:
... a: int
>>> converter.dumps(Test(1))
'{"a": 1}'
特定のライブラリーには、以下に記載されている追加の制約がある場合があります。
サードパーティー・ライブラリーは、インストール中に cattrs のオプション (extra) の依存関係として指定できます。オプションのインストール・ターゲットは、cattrs.preconf モジュールの名前と一致する必要があります。
# Using pip
$ pip install cattrs[ujson]
# Using pdm
$ pdm add cattrs[orjson]
# Using poetry
$ poetry add --extras tomlkit cattrs
標準ライブラリー json¶
cattrs.preconf.json にあります。
バイト列は base 85 文字列としてシリアライズされます。カウンターは辞書としてシリアライズされます。セットはリストとしてシリアライズされ、セットにデシリアライズされます。datetime と date は ISO 8601 文字列としてシリアライズされます。
orjson¶
cattrs.preconf.orjson にあります。
バイト列は base 85 文字列として un/structured されます。セットはリストに unstructured され、セットに structured されます。datetime と date は、orjson 自体によって RFC 3339 に unstructured されるように渡されます。型付き名前付きタプルは、通常のタプルに unstructured され、orjson によって JSON 配列に unstructured されます。
orjson は、-9223372036854775808 未満、および 9223372036854775807 より大きい整数をサポートしていません。orjson は文字列キーを持つマッピングのみをサポートしているため、マッピングはシリアライズ前にキーが文字列化され、デシリアライズ中に非文字列化されます。
msgspec¶
cattrs.preconf.msgspec にあります。現在、JSON 機能のみが利用可能で、msgspec でサポートされている他の形式は将来提供される予定です。
msgspec 構造体 はサポートされていますが、構成可能ではありません。構造体は msgspec に直接渡され、msgspec はそのすべてのフィールドを再帰的に処理します。cattrs は、将来、構造体のより高度な処理を取得する可能性があります。
msgspec strict mode がデフォルトで使用されます。これは、コンバーターの encoder 属性を変更することでカスタマイズできます。
cattrs が unstructuring および structuring と呼ぶものを、msgspec は to_builtins および convert と呼びます。cattrs が dumping および loading と呼ぶものを、msgspec は encoding および decoding と呼びます。
互換性に関する注意:
バイト列は、msgspec 自体によって base 64 文字列として直接 un/structured されます。
msgspec は、特殊な浮動小数点値 (
NaN, Inf, -Inf) をnullとしてエンコードします。datetimeとdateは、msgspec 自体によって RFC 3339 に unstructured されるように渡されます。attrs クラス、dataclass、およびシーケンスは、可能であれば msgspec によって直接処理され、それ以外の場合は通常の cattrs メカニズムによって処理されます。これは、生成される検証エラーが cattrs 検証エラーではなく、msgspec 検証エラーである可能性があることを意味します。
このコンバーターは、get_loads_hook() と get_dumps_hook() をサポートしています。これらは、(unstructuring および structuring とは対照的に) dumping および loading 関数のファクトリーです。これによって返されるフックは、可能な限り多くの作業を 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}'
その複雑さから、このコンバーターは現在 provisional であり、最適な統合パターンが発見されるにつれてわずかに変更される可能性があります。
msgspec は PyPy をサポートしていません。
Added in version 24.1.0.
ujson¶
cattrs.preconf.ujson にあります。
バイト列は base 85 文字列としてシリアライズされます。セットはリストとしてシリアライズされ、セットにデシリアライズされます。datetime と date は ISO 8601 文字列としてシリアライズされます。
ujson は、-9223372036854775808 未満、および 9223372036854775807 より大きい整数をサポートしていません。また、float('inf') もサポートしていません。
msgpack¶
cattrs.preconf.msgpack にあります。
セットはリストとしてシリアライズされ、セットにデシリアライズされます。datetime は UNIX タイムスタンプの浮動小数点値としてシリアライズされます。date は、真夜中にアラインされた UNIX タイムスタンプの浮動小数点値としてシリアライズされます。
msgpack は、-9223372036854775808 未満、および 18446744073709551615 より大きい整数をサポートしていません。
バイト列から msgpack データを解析する場合、ライブラリーに strict_map_key=False を渡して、完全な互換性を得る必要があります。
cbor2¶
cattrs.preconf.cbor2 にあります。
cbor2 は、共有参照、大きな整数、有理数などを処理するためのいくつかの拡張機能を備えた、フル機能の CBOR エンコーダーを実装しています。
セットはシリアライズおよびデシリアライズされてセットになります。タプルはリストとしてシリアライズされます。
datetime は、デフォルトでテキスト文字列としてシリアライズされます (CBOR Tag 0)。キーワード引数 datetime_as_timestamp=True を使用して、UNIX タイムスタンプの整数/浮動小数点としてエンコードします (CBOR Tag 1) 注: これはタイムゾーン情報を UTC として置き換えます。
date は ISO 8601 文字列としてシリアライズされます。
最小のバイナリー出力への効率的なエンコードには、キーワード引数 canonical=True を使用します。
浮動小数点数は、numpy 浮動小数点数にキャスト (および Python 浮動小数点数に戻す) ことにより、低精度の形式にキャストすることで、より小さな出力に強制できます。例: float(np.float32(value)) または float(np.float16(value))
Added in version 23.1.0.
bson¶
cattrs.preconf.bson にあります。スタンドアロンの PyPI bson パッケージではなく、pymongo ライブラリーにバンドルされている bson モジュールに対してテスト済み。
セットはリストとしてシリアライズされ、セットにデシリアライズされます。
bson は、-9223372036854775808 未満または 9223372036854775807 (64 ビット符号付き) より大きい整数をサポートしていません。bson は、マッピング・キーの NULL バイトをサポートしていません。bson は文字列キーを持つマッピングのみをサポートしているため、マッピングはシリアライズ前にキーが文字列化され、デシリアライズ中に非文字列化されます。bson の datetime 表現は、マイクロ秒の精度をサポートしていません。date は ISO 8601 文字列としてシリアライズされます。
エンコードおよびデコードする場合、ライブラリーに codec_options=bson.CodecOptions(tz_aware=True) を渡して、完全な互換性を得る必要があります。
pyyaml¶
cattrs.preconf.pyyaml にあります。
Frozenset はリストとしてシリアライズされ、frozenset にデシリアライズされます。date は ISO 8601 文字列としてシリアライズされます。型付き名前付きタプルは、通常のタプルに unstructured され、pyyaml によって YAML 配列に unstructured されます。
tomlkit¶
cattrs.preconf.tomlkit にあります。
バイト列は base 85 文字列としてシリアライズされます。セットはリストとしてシリアライズされ、セットにデシリアライズされます。タプルはリストとしてシリアライズされ、タプルにデシリアライズされます。tomlkit は文字列キーを持つマッピングのみをサポートしているため、マッピングはシリアライズ前にキーが文字列化され、デシリアライズ中に非文字列化されます。date は ISO 8601 文字列としてシリアライズされます。