コンバーターの詳細

コンバーターは、関数合成を実行し、非構造化/構造化関数を生成するために cattrs が使用するルールのレジストリです。

現在、コンバーターには次の状態が含まれています:

  • 非構造化フックのレジストリ。 singledispatch と、キャッシュでラップされたFunctionDispatchによってサポートされています。

  • 構造化フックのレジストリ。別の singledispatch と FunctionDispatch、および別のキャッシュによってサポートされています。

  • detailed_validation フラグ (デフォルトは true)。コンバーターが詳細な検証を使用するかどうかを決定します。

  • 非構造化戦略 (AS_DICT または AS_TUPLE)への参照。

  • prefer_attrib_converters フラグ (デフォルトは false)。attrs クラスを構造化する際に、通常の cattrs メカニズムよりも attrs コンバーターを優先するかどうかを決定します。

  • dict_factory 呼び出し可能オブジェクト。AS_DICT を使用して attrs クラスをダンプするときに dicts を作成するために使用されるレガシーパラメーター。

コンバーターは、Converter.copy() メソッドを使用して複製できます。新しいコピーは copy 引数を通じて変更できますが、元の手動で登録されたすべてのフックが保持されます。

コレクションの非構造化のカスタマイズ

重要

この機能は、Python 3.9 以降でサポートされています。

Tip

コレクション処理をカスタマイズする、より現代的で強力な方法については、Customizing Collections を参照してください。

一般的な方法でコレクションの非構造化をオーバーライドすることは、非常に便利な機能です。一般的な例としては、セットをサポートしていないが、代わりにリストとタプルを予期する JSON ライブラリを使用することがあります。

このために通常の非構造化フックを使用することは、singledispatch のセマンティクスにより扱いにくいです。つまり、使用しているすべての特定のタイプのセット (set[int]、set[float]、set[str]...) に対してフックを登録する必要がありますが、これは役に立ちません。

関数ベースのフックを代わりに使用できますが、独自の課題があります。効率的に記述するのが複雑です。

Converter は、unstruct_collection_overrides パラメーターを使用して、コレクションの非構造化の簡単なカスタマイズをサポートしています。たとえば、すべてのセットをリストに非構造化するには、次のようにします:

>>> from collections.abc import Set
>>> converter = cattrs.Converter(unstruct_collection_overrides={Set: list})

>>> converter.unstructure({1, 2, 3})
[1, 2, 3]

さらに、Converter には、一般性の高い順に、次の Python 型をサポートするヒューリスティクスが含まれています:

  • typing.Sequence、typing.MutableSequence、list、deque、tuple

  • typing.Set、frozenset、typing.MutableSet、set

  • typing.Mapping、typing.MutableMapping、dict、defaultdict、collections.OrderedDict、collections.Counter

たとえば、Sequence の非構造化タイプをオーバーライドしても、MutableSequence、list、または tuple の非構造化タイプをオーバーライドしない場合、オーバーライドはこれらのタイプにも影響します。ルールを覚える簡単な方法は次のとおりです:

  • すべての MutableSequence は Sequence であるため、オーバーライドが適用されます

  • すべての list は MutableSequence であるため、オーバーライドが適用されます

  • すべての tuple は Sequence であるため、オーバーライドが適用されます

ただし、MutableSequence のみをオーバーライドする場合、Sequence として注釈が付けられたフィールドは影響を受けません (すべてのシーケンスが可変シーケンスであるとは限らないため)。また、タプルとして注釈が付けられたフィールドも影響を受けません (タプルはそもそも可変シーケンスではないため)。

同様のロジックが、セットとマッピングの階層に適用されます。

Python 3.9 以降では collections.abc の型を使用し、古い Python バージョンでは typing の型を使用していることを確認してください。

フォールバックフックファクトリ

デフォルトでは、コンバーター が型を処理できない場合、次のようになります:

これらの動作は、コンバーターの作成時にカスタムフックファクトリを提供することでカスタマイズできます。

>>> from pickle import dumps

>>> class Unsupported:
...     """An artisinal (non-attrs) class, unsupported by default."""

>>> converter = Converter(unstructure_fallback_factory=lambda _: dumps)
>>> instance = Unsupported()
>>> converter.unstructure(instance)
b'\x80\x04\x95\x18\x00\x00\x00\x00\x00\x00\x00\x8c\x08__main__\x94\x8c\x04Test\x94\x93\x94)\x81\x94.'

これにより、コンバーターをチェーン化することもできます。

>>> parent = Converter()

>>> child = Converter(
...     unstructure_fallback_factory=parent.get_unstructure_hook,
...     structure_fallback_factory=parent.get_structure_hook,
... )

Added in version 23.2.0.

cattrs.Converter

Converter は、attrs クラス、dataclass、および TypedDict のための特殊な構造化フックと非構造化フックを自動的に生成、コンパイル、およびキャッシュするコンバーターバリアントです。

Converter は、次の点で cattrs.BaseConverter と異なります:

  • attrs クラスの構造化と非構造化は、最初は遅くなりますが、それ以降は毎回速くなります

  • 構造化と非構造化はカスタマイズできます

  • PEP563 (延期) アノテーションを持つ attrs クラスのサポート

  • ジェネリック attrs クラスのサポート

  • コレクションの非構造化を簡単にオーバーライドするためのサポート

Converter は以前は GenConverter と呼ばれていましたが、下位互換性のためにそのエイリアスはまだ存在します。

cattrs.BaseConverter

BaseConverter は、よりシンプルで低速なコンバーターバリアントです。コード生成を行わないため、最初の使用時に高速になる可能性があり、これは、起動時間がスループットよりも重要な CLI アプリケーションなどの特定のケースで役立ちます。