組み込みフック

cattrs コンバーターには、 多数の構造化/非構造化フックが組み込まれています。 常にそうであるように、 複雑なフックはより単純なものと組み合わされます。

プリミティブ値

int 、 float 、 str 、 bytes

構造化する際、 これらの型のいずれかを使用して、 オブジェクトをその型に強制します。

>>> cattrs.structure(1, str)
'1'
>>> cattrs.structure("1", float)
1.0

変換が不可能な場合、 予期される例外が伝播されます。 特定の例外は、 直接強制変換しようとした場合と同じです。

>>> cattrs.structure("not-an-int", int)
Traceback (most recent call last):
...
ValueError: invalid literal for int() with base 10: 'not-an-int'

強制は、 パフォーマンスと互換性の理由から実行されます。 代わりに純粋な検証が必要な場合は、 これらのフックのいずれかをオーバーライドできます。

>>> c = Converter()

>>> @c.register_structure_hook
... def validate(value, type) -> int:
...     if not isinstance(value, type):
...         raise ValueError(f'{value!r} not an instance of {type}')

>>> c.structure("1", int)
Traceback (most recent call last):
...
ValueError: '1' not an instance of <class 'int'>

非構造化する場合、 これらの型は変更されずに渡されます。

列挙型

列挙型は、 それらの値によって構造化され、 それらの値に非構造化されます。 これは、 タプルのような複雑な値でも機能します。

>>> @unique
... class CatBreed(Enum):
...    SIAMESE = "siamese"
...    MAINE_COON = "maine_coon"
...    SACRED_BIRMAN = "birman"

>>> cattrs.structure("siamese", CatBreed)
<CatBreed.SIAMESE: 'siamese'>

>>> cattrs.unstructure(CatBreed.SIAMESE)
'siamese'

繰り返しになりますが、 エラーが発生した場合、 予期される例外が発生します。

pathlib.Path

pathlib.Path オブジェクトは、 それらの文字列値を使用して構造化され、 それらの文字列値に非構造化されます。

>>> from pathlib import Path

>>> cattrs.structure("/root", Path)
PosixPath('/root')

>>> cattrs.unstructure(Path("/root"))
'/root'

変換が不可能な場合、 結果の例外が伝播されます。

Added in version 23.1.0.

コレクションと関連するジェネリクス

オプション

Optional プリミティブとコレクションは、 デフォルトでサポートされています。 PEP 604 オプション ( T | None ) は、 Python 3.10 以降でもサポートされています。

>>> cattrs.structure(None, int)
Traceback (most recent call last):
...
TypeError: int() argument must be a string, a bytes-like object or a number, not 'NoneType'

>>> print(cattrs.structure(None, int | None))
None

ベア Optional (パラメーター化されていない、 単なる Optional 、 Optional[str] とは対照的) はサポートされていません。 代わりに Optional[Any] を使用する必要があります。

Optionals の処理は、 register_structure_hook() および register_unstructure_hook() を使用してカスタマイズできます。

>>> converter = Converter()

>>> @converter.register_structure_hook
... def hook(val: Any, type: Any) -> str | None:
...     if val in ("", None):
...         return None
...     return str(val)
...

>>> print(converter.structure("", str | None))
None

リスト

リストは、 任意の反復可能オブジェクトから構造化できます。 リストに変換する型は次のとおりです:

• typing.Sequence[T]

• typing.MutableSequence[T]

• typing.List[T]

• list[T]

すべての場合において、 新しいリストが返されるため、 この操作を使用して、 反復可能オブジェクトをリストにコピーできます。 ベア型 (たとえば、 Sequence[int] の代わりに Sequence ) は、 Sequence[Any] と同等です。

>>> cattrs.structure((1, 2, 3), MutableSequence[int])
[1, 2, 3]

非構造化する場合、 リストはコピーされ、 その内容は内部型に従って処理されます。 コレクションを非構造化する有用なユースケースは、 複雑なコレクションまたは再帰的なコレクションのディープコピーを作成することです。

辞書

辞書は、 他のマッピングオブジェクトから生成できます。 より正確には、 非構造化オブジェクトは、 キーと値のタプルの反復可能オブジェクトを生成する items() メソッドを公開し、 引数として dict コンストラクターに渡すことができる必要があります。 辞書に変換する型は次のとおりです:

• dict[K, V] および typing.Dict[K, V]

• collections.abc.MutableMapping[K, V] および typing.MutableMapping[K, V]

• collections.abc.Mapping[K, V] および typing.Mapping[K, V]

すべての場合において、 新しい辞書が返されるため、 この操作を使用して、 マッピングを辞書にコピーできます。 typing.Any に設定された型パラメーターは、 変換されずに渡されます。 両方の型パラメーターがない場合、 それらは Any としても扱われます。

>>> from collections import OrderedDict
>>> cattrs.structure(OrderedDict([(1, 2), (3, 4)]), dict)
{1: 2, 3: 4}

キーと値の両方が変換されます。

>>> cattrs.structure({1: None, 2: 2.0}, dict[str, Optional[int]])
{'1': None, '2': 2}

abc.Mapping および abc.MutableMapping の仮想サブクラス

クラスが collections.abc.Mapping または collections.abc.MutableMapping の仮想サブクラスであると宣言し、 その初期化子が辞書を受け入れる場合、 cattrs はデフォルトでそれを構造化できます。

同種および異種タプル

同種および異種のタプルは、 反復可能オブジェクトから構造化できます。 異種タプルは、 型パラメーターの数と完全に一致する要素数を持つ反復可能オブジェクトを必要とします。

使用:

• Tuple[A, B, C, D]

• tuple[A, B, C, D]

同種タプルは以下を使用します:

• Tuple[T, ...]

• tuple[T, ...]

すべての場合において、 タプルが生成されます。 typing.Any に設定された型パラメーターは、 変換されずに渡されます。

>>> cattrs.structure([1, 2, 3], tuple[int, str, float])
(1, '2', 3.0)

非構造化する場合、 異種タプルはタプルに非構造化されます。 これは、 より高速であり、 ほとんどすべてのシリアル化ライブラリがネイティブでタプルをサポートしているためです。

参考

typing.NamedTuple のサポート。

注釈

異種タプルの構造化は、 BaseConverter ではサポートされていません。

デキュー

デキューは、 任意の反復可能オブジェクトから構造化できます。 デキューに変換する型は次のとおりです:

• typing.Deque[T]

• collections.deque[T]

すべての場合において、 新しい 非有界 デキュー ( maxlen=None ) が生成されるため、 この操作を使用して、 反復可能オブジェクトをデキューにコピーできます。 有界 deque に変換する場合は、 カスタム構造化フックを登録するのが良い方法です。

>>> from collections import deque
>>> cattrs.structure((1, 2, 3), deque[int])
deque([1, 2, 3])

デキューは、 リストに非構造化されるか、 BaseConverter を使用する場合はデキューに非構造化されます。

Added in version 23.1.0.

セットとフローズンセット

セットとフローズンセットは、 任意の反復可能オブジェクトから構造化できます。 セットに変換する型は次のとおりです:

• typing.Set[T]

• typing.MutableSet[T]

• set[T]

フローズンセットに変換する型は次のとおりです:

• typing.FrozenSet[T]

• frozenset[T]

すべての場合において、 新しいセットまたはフローズンセットが返されます。 ベア型 (たとえば、 MutableSet[int] の代わりに MutableSet ) は、 MutableSet[Any] と同等です。

>>> cattrs.structure([1, 2, 3, 4], set)
{1, 2, 3, 4}

セットとフローズンセットは、 同じクラスに非構造化されます。

型付き辞書

TypedDicts は、 マッピングオブジェクト (通常は辞書) から構造化できます。

>>> from typing import TypedDict

>>> class MyTypedDict(TypedDict):
...    a: int

>>> cattrs.structure({"a": "1"}, MyTypedDict)
{'a': 1}

total および non-total の TypedDicts の両方がサポートされており、 任意の組み合わせ間の継承が機能します (ただし、 typing.TypedDict が使用されている 3.8 を除く、 下記参照)。 ジェネリック TypedDicts は、 Python 3.11 以降で動作します。 これは、 それらを一般的にサポートする最初の Python バージョンであるためです。

typing.Required および typing.NotRequired がサポートされています。

Python 3.8 では、 typing_extensions.TypedDict を使用することをお勧めします。 typing.TypedDict は必要な機能をすべてサポートしているわけではないため、 サブクラス化、 totality 、 typing.Required の特定の組み合わせは機能しません。

attrs クラスと同様に 、 構造化/非構造化は、 cattrs.gen.typeddicts.make_dict_structure_fn() および cattrs.gen.typeddicts.make_dict_unstructure_fn() を使用してカスタマイズできます。

>>> from typing import TypedDict
>>> from cattrs import Converter
>>> from cattrs.gen import override
>>> from cattrs.gen.typeddicts import make_dict_structure_fn

>>> class MyTypedDict(TypedDict):
...     a: int
...     b: int

>>> c = Converter()
>>> c.register_structure_hook(
...     MyTypedDict,
...     make_dict_structure_fn(
...         MyTypedDict,
...         c,
...         a=override(rename="a-with-dash")
...     )
... )

>>> c.structure({"a-with-dash": 1, "b": 2}, MyTypedDict)
{'b': 2, 'a': 1}

TypedDicts は辞書に非構造化され、 (正確なフィールド型と登録されたフックに応じて) 変更されない可能性があります。

>>> from typing import TypedDict
>>> from datetime import datetime, timezone
>>> from cattrs import Converter

>>> class MyTypedDict(TypedDict):
...    a: datetime

>>> c = Converter()
>>> c.register_unstructure_hook(datetime, lambda d: d.timestamp())

>>> c.unstructure({"a": datetime(1970, 1, 1, tzinfo=timezone.utc)}, unstructure_as=MyTypedDict)
{'a': 0.0}

Added in version 23.1.0.

attrs クラスとデータクラス

attrs クラスとデータクラスは、 デフォルトで動作します。 フィールドには型注釈が必要です (静的型チェックが使用されていない場合でも)。 そうでない場合、 それらは typing.Any として扱われます。

構造化する場合、 マッピング d とクラス A が与えられた場合、 cattrs は d をアンパックして A をインスタンス化します。

>>> @define
... class A:
...     a: int
...     b: int

>>> cattrs.structure({'a': 1, 'b': '2'}, A)
A(a=1, b=2)

タプルは、 structure_attrs_fromtuple() ( attrs.astuple および BaseConverter.unstructure_attrs_astuple() の反対の意味での fromtuple ) を使用してクラスに構造化できます。

>>> @define
... class A:
...     a: str
...     b: int

>>> cattrs.structure_attrs_fromtuple(['string', '2'], A)
A(a='string', b=2)

タプルからのロードは、 unstruct_strat=cattr.UnstructureStrategy.AS_TUPLE を持つ新しい Converter を作成することでデフォルトにできます。

>>> converter = cattrs.Converter(unstruct_strat=cattr.UnstructureStrategy.AS_TUPLE)
>>> @define
... class A:
...     a: str
...     b: int

>>> converter.structure(['string', '2'], A)
A(a='string', b=2)

タプルからの構造化は、 通常の方法でフックを登録することによってのみ、 特定のクラスのデフォルトにすることもできます。

>>> converter = cattrs.Converter()

>>> @define
... class A:
...     a: str
...     b: int

>>> converter.register_structure_hook(A, converter.structure_attrs_fromtuple)

ジェネリクス

ジェネリック attrs クラスとデータクラスは、 typing.Generic と PEP 695 の両方を使用して完全にサポートされています。

>>> @define
... class A[T]:
...    a: T

>>> cattrs.structure({"a": "1"}, A[int])
A(a=1)

属性の型とコンバーターの使用

デフォルトでは、 structure() は、 register_structure_hook() を使用して登録されたフックを使用して、 値を属性の型に変換し、 field を持つ属性に登録されたコンバーターの呼び出しに進みます。

>>> from ipaddress import IPv4Address, ip_address
>>> converter = cattrs.Converter()

# Note: register_structure_hook has not been called, so this will fallback to 'ip_address'
>>> @define
... class A:
...     a: IPv4Address = field(converter=ip_address)

>>> converter.structure({'a': '127.0.0.1'}, A)
A(a=IPv4Address('127.0.0.1'))

優先度は、 register_structure_hook() で登録されたフックに引き続き与えられますが、 prefer_attrib_converters を True に設定することで、 この優先度を反転させることができます。

>>> converter = cattrs.Converter(prefer_attrib_converters=True)

>>> @define
... class A:
...     a: int = field(converter=lambda v: int(v) + 5)

>>> converter.structure({'a': '10'}, A)
A(a=15)

参考

attrs クラスまたはデータクラスが継承を使用し、 そのため 1 つまたは複数のサブクラスを持つ場合、 サブクラスを含める 戦略を使用することで、 正確なサブタイプに自動的に構造化できます。

ユニオン

NoneType と単一の他の型 (オプションとしても知られている) のユニオンは、 特別なケース によってサポートされています。

自動曖昧性解消

cattrs には、 attrs クラスのユニオンを自動的に処理するための意見のある戦略が含まれています。 詳細については、 Default Union Strategy を参照してください。

これらの種類のユニオンを非構造化する場合、 各ユニオンメンバーは、 その型のフックに従って非構造化されます。

単純型のユニオン

cattrs には Union Passthrough が付属しており、 コンバーターは多くのプリミティブ型とリテラルのユニオンを構造化できます。 この戦略は任意のコンバーターに適用でき、 基になるプロトコルに従って、 すべての preconf コンバーターに事前に適用されます。

特別な型付け形式

typing.Any

構造化する場合、 構造化しているオブジェクトに変換を適用しないようにするには、 typing.Any を使用します。 それは単に渡されます。

>>> cattrs.structure(1, Any)
1
>>> d = {1: 1}
>>> cattrs.structure(d, Any) is d
True

非構造化する場合、 typing.Any は、 値を実行時クラスに従って非構造化します。

バージョン 24.1.0 で変更: 以前は、 Any の非構造化ルールは十分に指定されておらず、 一貫性のない動作につながっていました。

バージョン 24.1.0 で変更: typing_extensions.Any もサポートされるようになりました。

typing.Literal

構造化する場合、 PEP 586 リテラルは、 許可された値のセットに含まれていることが検証されます。

>>> from typing import Literal

>>> cattrs.structure(1, Literal[1, 2])
1

非構造化する場合、 リテラルは渡されます。

Added in version 1.7.0.

typing.NamedTuple

型ヒント付きの名前付きタプル ( typing.NamedTuple から作成) がサポートされています。 名前付きタプルは、 デフォルトでタプルまたはリストを使用して構造化/非構造化されます。

cattrs.cols モジュールには、 代わりに辞書を使用して名前付きタプルを構造化/非構造化するためのフックファクトリが含まれています。 詳細については、 こちらをご覧ください 。

Added in version 24.1.0.

typing.Final

PEP 591 Final 属性型 ( Final[int] ) がサポートされており、 内部型 (この場合は int ) に従って処理されます。

Added in version 23.1.0.

typing.Annotated

PEP 593 アノテーション ( typing.Annotated[type, ...] ) がサポートされており、 アノテーション付きの型に存在する最初の型を使用して処理されます。

Added in version 1.4.0.

型エイリアス

型エイリアス は、 Python 3.12 以降でサポートされており、 基になる型のルールに従って処理されます。 それらのフックは、 Predicate Hooks を使用してオーバーライドすることもできます。

警告

typing.TypeAlias を使用する型エイリアスは、 実行時にそれらを基になる型と区別する方法がないため、 サポートされていません。

>>> from datetime import datetime, UTC

>>> type IsoDate = datetime

>>> converter = cattrs.Converter()
>>> converter.register_structure_hook_func(
...     lambda t: t is IsoDate, lambda v, _: datetime.fromisoformat(v)
... )
>>> converter.register_unstructure_hook_func(
...     lambda t: t is IsoDate, lambda v: v.isoformat()
... )

>>> converter.structure("2022-01-01", IsoDate)
datetime.datetime(2022, 1, 1, 0, 0)
>>> converter.unstructure(datetime.now(UTC), unstructure_as=IsoDate)
'2023-11-20T23:10:46.728394+00:00'

Added in version 24.1.0.

typing.NewType

NewTypes がサポートされており、 基になる型のルールに従って処理されます。 それらのフックは、 Converter.register_structure_hook() を使用してオーバーライドすることもできます。

>>> from typing import NewType
>>> from datetime import datetime

>>> IsoDate = NewType("IsoDate", datetime)

>>> converter = cattrs.Converter()
>>> converter.register_structure_hook(IsoDate, lambda v, _: datetime.fromisoformat(v))

>>> converter.structure("2022-01-01", IsoDate)
datetime.datetime(2022, 1, 1, 0, 0)

Added in version 22.2.0.

typing.Protocol

プロトコル は、 デフォルトで構造化できず、 カスタムフックが必要です。

プロトコルは、 値の実際の実行時型に従って非構造化されます。

Added in version 1.9.0.