cattrs パッケージ

cattrs.structure(obj, cl)

構造化されていない Python のデータ構造を構造化データに変換します。

パラメータ:

  • obj (Any)

  • cl (type[T])

戻り値の型:

T

cattrs.unstructure(obj, unstructure_as=None)
パラメータ:

  • obj (Any)

  • unstructure_as (Any)

戻り値の型:

Any

cattrs.get_structure_hook(type, cache_result=True)

指定された型の構造フックを取得します。

このフックは手動で呼び出すか、他の関数と組み合わせて再登録できます。

フックが登録されていない場合、コンバーターの構造フォールバックファクトリを使用してフックが生成されます。

パラメータ:

  • cache -- 返されたフックをキャッシュするかどうか。

  • type (Any)

  • cache_result (bool)

戻り値の型:

Callable[[Any, Any], Any]

Added in version 24.1.0.

cattrs.get_unstructure_hook(type, cache_result=True)

指定された型の非構造化フックを取得します。

このフックは手動で呼び出すか、他の関数と組み合わせて再登録できます。

フックが登録されていない場合、コンバーターの非構造化フォールバックファクトリを使用してフックが生成されます。

パラメータ:

  • cache -- 返されたフックをキャッシュするかどうか。

  • type (Any)

  • cache_result (bool)

戻り値の型:

Callable[[Any], Any]

Added in version 24.1.0.

cattrs.register_structure_hook_func(check_func, func)

クラスが一致するかどうかを関数で確認し、クラスからプリミティブへのコンバーター関数をクラスに登録します。

パラメータ:

  • check_func (Callable[[Any], bool])

  • func (Callable[[Any, Any], Any])

戻り値の型:

None

cattrs.register_structure_hook(cl, func=None)

型に対して、プリミティブからクラスへのコンバーター関数を登録します。

コンバーター関数は、次の 2 つの引数を受け取る必要があります:

  • 変換される Python オブジェクト

  • 変換先の型

そして、クラスのインスタンスを返します。型は冗長に見えるかもしれませんが、(たとえば、ジェネリッククラスを扱う場合など) 必要な場合があります。

このメソッドはデコレーターとして使用できます。この場合、装飾されたフックは戻り値の型注釈を持つ必要があり、この注釈はフックの型として使用されます。

バージョン 24.1.0 で変更: このメソッドはデコレーターとして使用できるようになりました。

パラメータ:

  • cl (Any)

  • func (Callable[[Any, Any], Any] | None)

戻り値の型:

None

cattrs.register_unstructure_hook_func(check_func, func)

クラスが一致するかどうかを関数で確認し、クラスからプリミティブへのコンバーター関数をクラスに登録します。

パラメータ:

  • check_func (Callable[[Any], bool])

  • func (Callable[[Any], Any])

戻り値の型:

None

cattrs.register_unstructure_hook(cls=None, func=None)

クラスからプリミティブへのコンバーター関数をクラスに登録します。

コンバーター関数は、クラスのインスタンスを受け取り、それに対応する Python の値を返す必要があります。

デコレーターとして使用することもできます。デコレーターとして使用する場合、装飾された関数の最初の引数の注釈が、フックを登録する型として使用されます。

バージョン 24.1.0 で変更: このメソッドはデコレーターとして使用できるようになりました。

パラメータ:

  • cls (Any)

  • func (UnstructureHook | None)

戻り値の型:

Callable[[UnstructureHook]] | None

cattrs.structure_attrs_fromdict(obj, cl)

マッピング (dict) から attrs クラスをインスタンス化します。

パラメータ:

  • obj (Mapping[str, Any])

  • cl (type[T])

戻り値の型:

T

cattrs.structure_attrs_fromtuple(obj, cl)

シーケンス (タプル) から attrs クラスをロードします。

パラメータ:

  • obj (tuple[Any, ...])

  • cl (type[T])

戻り値の型:

T

cattrs.global_converter: Final = <cattrs.converters.Converter object>

グローバルコンバーター。カスタマイズが必要な場合は、独自のコンバーターを作成することをお勧めします。

class cattrs.BaseConverter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, prefer_attrib_converters=False, detailed_validation=True, unstructure_fallback_factory=<function BaseConverter.<lambda>>, structure_fallback_factory=<function BaseConverter.<lambda>>)[ソース]

ベースクラス: object

構造化データと非構造化データを変換します。

パラメータ:

  • detailed_validation (bool) -- 詳細な検証エラーのために、わずかに遅いモードを使用するかどうか。

  • unstructure_fallback_factory (HookFactory[UnstructureHook]) -- 登録されている非構造化フックが一致しない場合に呼び出されるフックファクトリ。

  • structure_fallback_factory (HookFactory[StructureHook]) -- 登録されている構造化フックが一致しない場合に呼び出されるフックファクトリ。

  • dict_factory (Callable[[], Any])

  • unstruct_strat (UnstructureStrategy)

  • prefer_attrib_converters (bool)

Added in version 23.2.0: unstructure_fallback_factory

Added in version 23.2.0: structure_fallback_factory

detailed_validation
copy(dict_factory=None, unstruct_strat=None, prefer_attrib_converters=None, detailed_validation=None)[ソース]

既存のカスタムフックをすべて保持して、コンバーターのコピーを作成します。

パラメータ:

  • detailed_validation (bool | None) -- 詳細な検証エラーのために、わずかに遅いモードを使用するかどうか。

  • dict_factory (Callable[[], Any] | None)

  • unstruct_strat (UnstructureStrategy | None)

  • prefer_attrib_converters (bool | None)

戻り値の型:

BaseConverter

get_structure_hook(type, cache_result=True)[ソース]

指定された型の構造フックを取得します。

このフックは手動で呼び出すか、他の関数と組み合わせて再登録できます。

フックが登録されていない場合、コンバーターの構造フォールバックファクトリを使用してフックが生成されます。

パラメータ:

  • cache -- 返されたフックをキャッシュするかどうか。

  • type (Any)

  • cache_result (bool)

戻り値の型:

Callable[[Any, Any], Any]

Added in version 24.1.0.

get_unstructure_hook(type, cache_result=True)[ソース]

指定された型の非構造化フックを取得します。

このフックは手動で呼び出すか、他の関数と組み合わせて再登録できます。

フックが登録されていない場合、コンバーターの非構造化フォールバックファクトリを使用してフックが生成されます。

パラメータ:

  • cache -- 返されたフックをキャッシュするかどうか。

  • type (Any)

  • cache_result (bool)

戻り値の型:

Callable[[Any], Any]

Added in version 24.1.0.

register_structure_hook(cl, func=None)[ソース]

型に対して、プリミティブからクラスへのコンバーター関数を登録します。

コンバーター関数は、次の 2 つの引数を受け取る必要があります:

  • 変換される Python オブジェクト

  • 変換先の型

そして、クラスのインスタンスを返します。型は冗長に見えるかもしれませんが、(たとえば、ジェネリッククラスを扱う場合など) 必要な場合があります。

このメソッドはデコレーターとして使用できます。この場合、装飾されたフックは戻り値の型注釈を持つ必要があり、この注釈はフックの型として使用されます。

バージョン 24.1.0 で変更: このメソッドはデコレーターとして使用できるようになりました。

パラメータ:

  • cl (Any)

  • func (Callable[[Any, Any], Any] | None)

戻り値の型:

None

register_structure_hook_factory(predicate, factory=None)[ソース]

指定された述語のフックファクトリを登録します。

フックファクトリは、追加の必須パラメータを公開する場合があります。この場合、現在のコンバーターは、そのパラメータとしてフックファクトリに提供されます。

デコレーターとして使用することもできます。

パラメータ:

  • predicate -- 型を指定すると、ファクトリがその型のフックを生成できるかどうかを返す関数。

  • factory -- 型を指定すると、その型の構造化フックを生成する呼び出し可能オブジェクト。この構造化フックはキャッシュされます。

バージョン 24.1.0 で変更: このメソッドはデコレーターとして使用できるようになりました。ファクトリは、2 番目の必須引数としてコンバーターを受け取ることもできます。

register_structure_hook_func(check_func, func)[ソース]

クラスが一致するかどうかを関数で確認し、クラスからプリミティブへのコンバーター関数をクラスに登録します。

パラメータ:

  • check_func (Callable[[Any], bool])

  • func (Callable[[Any, Any], Any])

戻り値の型:

None

register_unstructure_hook(cls=None, func=None)[ソース]

クラスからプリミティブへのコンバーター関数をクラスに登録します。

コンバーター関数は、クラスのインスタンスを受け取り、それに対応する Python の値を返す必要があります。

デコレーターとして使用することもできます。デコレーターとして使用する場合、装飾された関数の最初の引数の注釈が、フックを登録する型として使用されます。

バージョン 24.1.0 で変更: このメソッドはデコレーターとして使用できるようになりました。

パラメータ:

  • cls (Any)

  • func (UnstructureHook | None)

戻り値の型:

Callable[[UnstructureHook]] | None

register_unstructure_hook_factory(predicate, factory=None)[ソース]

指定された述語のフックファクトリを登録します。

フックファクトリは、追加の必須パラメータを公開する場合があります。この場合、現在のコンバーターは、そのパラメータとしてフックファクトリに提供されます。

デコレーターとして使用することもできます。

パラメータ:

  • predicate -- 型を指定すると、ファクトリがその型のフックを生成できるかどうかを返す関数。

  • factory -- 型を指定すると、その型の非構造化フックを生成する呼び出し可能オブジェクト。この非構造化フックはキャッシュされます。

バージョン 24.1.0 で変更: このメソッドはデコレーターとして使用できるようになりました。ファクトリは、2 番目の必須引数としてコンバーターを受け取ることもできます。

register_unstructure_hook_func(check_func, func)[ソース]

クラスが一致するかどうかを関数で確認し、クラスからプリミティブへのコンバーター関数をクラスに登録します。

パラメータ:

  • check_func (Callable[[Any], bool])

  • func (Callable[[Any], Any])

戻り値の型:

None

structure(obj, cl)[ソース]

構造化されていない Python のデータ構造を構造化データに変換します。

パラメータ:

  • obj (Any)

  • cl (type[T])

戻り値の型:

T

structure_attrs_fromdict(obj, cl)[ソース]

マッピング (dict) から attrs クラスをインスタンス化します。

パラメータ:

  • obj (Mapping[str, Any])

  • cl (type[T])

戻り値の型:

T

structure_attrs_fromtuple(obj, cl)[ソース]

シーケンス (タプル) から attrs クラスをロードします。

パラメータ:

  • obj (tuple[Any, ...])

  • cl (type[T])

戻り値の型:

T

property unstruct_strat: UnstructureStrategy

attrs クラスを非構造化するデフォルトの方法。

unstructure(obj, unstructure_as=None)[ソース]
パラメータ:

  • obj (Any)

  • unstructure_as (Any)

戻り値の型:

Any

unstructure_attrs_asdict(obj)[ソース]

attrs.asdict のバージョン。これにより、コールバックできます。

パラメータ:

obj (Any)

戻り値の型:

dict[str, Any]

unstructure_attrs_astuple(obj)[ソース]

attrs.astuple のバージョン。これにより、コールバックできます。

パラメータ:

obj (Any)

戻り値の型:

tuple[Any, ...]

class cattrs.Converter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, omit_if_default=False, forbid_extra_keys=False, type_overrides={}, unstruct_collection_overrides={}, prefer_attrib_converters=False, detailed_validation=True, unstructure_fallback_factory=<function Converter.<lambda>>, structure_fallback_factory=<function Converter.<lambda>>)[ソース]

ベースクラス: BaseConverter

特殊化された非構造化/構造化関数を生成するコンバーター。

パラメータ:

  • detailed_validation (bool) -- 詳細な検証エラーのために、わずかに遅いモードを使用するかどうか。

  • unstructure_fallback_factory (HookFactory[UnstructureHook]) -- 登録されている非構造化フックが一致しない場合に呼び出されるフックファクトリ。

  • structure_fallback_factory (HookFactory[StructureHook]) -- 登録されている構造化フックが一致しない場合に呼び出されるフックファクトリ。

  • dict_factory (Callable[[], Any])

  • unstruct_strat (UnstructureStrategy)

  • omit_if_default (bool)

  • forbid_extra_keys (bool)

  • type_overrides (Mapping[type, AttributeOverride])

  • unstruct_collection_overrides (Mapping[type, Callable])

  • prefer_attrib_converters (bool)

Added in version 23.2.0: unstructure_fallback_factory

Added in version 23.2.0: structure_fallback_factory

omit_if_default
forbid_extra_keys
type_overrides
copy(dict_factory=None, unstruct_strat=None, omit_if_default=None, forbid_extra_keys=None, type_overrides=None, unstruct_collection_overrides=None, prefer_attrib_converters=None, detailed_validation=None)[ソース]

既存のカスタムフックをすべて保持して、コンバーターのコピーを作成します。

パラメータ:

  • detailed_validation (bool | None) -- 詳細な検証エラーのために、わずかに遅いモードを使用するかどうか。

  • dict_factory (Callable[[], Any] | None)

  • unstruct_strat (UnstructureStrategy | None)

  • omit_if_default (bool | None)

  • forbid_extra_keys (bool | None)

  • type_overrides (Mapping[type, AttributeOverride] | None)

  • unstruct_collection_overrides (Mapping[type, Callable] | None)

  • prefer_attrib_converters (bool | None)

戻り値の型:

Converter

gen_structure_annotated(type)[ソース]

注釈付きの型のフックファクトリ。

戻り値の型:

Callable

gen_structure_attrs_fromdict(cl)[ソース]
パラメータ:

cl (type[T])

戻り値の型:

Callable[[Mapping[str, Any], Any], T]

gen_structure_counter(cl)[ソース]
パラメータ:

cl (Any)

戻り値の型:

Callable[[Mapping[Any, Any], Any], T]

gen_structure_mapping(cl)[ソース]
パラメータ:

cl (Any)

戻り値の型:

Callable[[Mapping[Any, Any], Any], T]

gen_structure_typeddict(cl)[ソース]

TypedDict 構造関数を生成します。

コンバータースコアの変更も適用します。

パラメータ:

cl (Any)

戻り値の型:

Callable[[dict, Any], dict]

gen_unstructure_annotated(type)[ソース]
gen_unstructure_attrs_fromdict(cl)[ソース]
パラメータ:

cl (type[T])

戻り値の型:

Callable[[T], dict[str, Any]]

gen_unstructure_hetero_tuple(cl, unstructure_to=None)[ソース]
パラメータ:

  • cl (Any)

  • unstructure_to (Any)

戻り値の型:

Callable[[Tuple[Any, ...]], Any]

gen_unstructure_iterable(cl, unstructure_to=None)[ソース]
パラメータ:

  • cl (Any)

  • unstructure_to (Any)

戻り値の型:

Callable[[Iterable[Any]], Any]

gen_unstructure_mapping(cl, unstructure_to=None, key_handler=None)[ソース]
パラメータ:

  • cl (Any)

  • unstructure_to (Any)

  • key_handler (Callable[[Any, Any | None], Any] | None)

戻り値の型:

Callable[[Mapping[Any, Any]], Any]

gen_unstructure_optional(cl)[ソース]

オプションの型の非構造化フックを生成します。

パラメータ:

cl (type[T])

戻り値の型:

Callable[[T], Any]

gen_unstructure_typeddict(cl)[ソース]

TypedDict 非構造化関数を生成します。

コンバータースコアの変更も適用します。

パラメータ:

cl (Any)

戻り値の型:

Callable[[dict], dict]

get_structure_newtype(type)[ソース]
パラメータ:

type (type[T])

戻り値の型:

Callable[[Any, Any], T]

register_structure_hook_factory(predicate, factory=None)[ソース]

指定された述語のフックファクトリを登録します。

フックファクトリは、追加の必須パラメータを公開する場合があります。この場合、現在のコンバーターは、そのパラメータとしてフックファクトリに提供されます。

デコレーターとして使用することもできます。

パラメータ:

  • predicate -- 型を指定すると、ファクトリがその型のフックを生成できるかどうかを返す関数。

  • factory -- 型を指定すると、その型の構造化フックを生成する呼び出し可能オブジェクト。この構造化フックはキャッシュされます。

バージョン 24.1.0 で変更: このメソッドはデコレーターとして使用できるようになりました。ファクトリは、2 番目の必須引数としてコンバーターを受け取ることもできます。

register_unstructure_hook_factory(predicate, factory=None)[ソース]

指定された述語のフックファクトリを登録します。

フックファクトリは、追加の必須パラメータを公開する場合があります。この場合、現在のコンバーターは、そのパラメータとしてフックファクトリに提供されます。

デコレーターとして使用することもできます。

パラメータ:

  • predicate -- 型を指定すると、ファクトリがその型のフックを生成できるかどうかを返す関数。

  • factory -- 型を指定すると、その型の非構造化フックを生成する呼び出し可能オブジェクト。この非構造化フックはキャッシュされます。

バージョン 24.1.0 で変更: このメソッドはデコレーターとして使用できるようになりました。ファクトリは、2 番目の必須引数としてコンバーターを受け取ることもできます。

class cattrs.AttributeValidationNote(string, name, type)[ソース]

ベースクラス: str

属性の構造化に失敗した場合、例外への注釈として添付されます。

パラメータ:

  • string (str)

  • name (str)

  • type (Any)

戻り値の型:

AttributeValidationNote

name: str
type: Any
exception cattrs.BaseValidationError(message, excs, cl)[ソース]

ベースクラス: ExceptionGroup

パラメータ:

cl (Type)

derive(excs)[ソース]
cl: Type
exception cattrs.ClassValidationError(message, excs, cl)[ソース]

ベースクラス: BaseValidationError

属性が無効な場合にクラスを検証すると発生します。

パラメータ:

cl (Type)

group_exceptions()[ソース]

例外を、検証ノートの有無にかかわらず、2 つのグループに分割します。

戻り値の型:

Tuple[List[Tuple[Exception, AttributeValidationNote]], List[Exception]]

exception cattrs.ForbiddenExtraKeysError(message, cl, extra_fields)[ソース]

ベースクラス: Exception

forbid_extra_keys がアクティブ化され、構造化中にそのような余分なキーが検出された場合に発生します。

属性 extra_fields は、このエラーの原因となった余分なキーのシーケンスであり、cl は、それらの余分なキーで構造化されたクラスです。

パラメータ:

  • message (str | None)

  • cl (Type)

  • extra_fields (Set[str])

戻り値の型:

None

cattrs.GenConverter

:py:class:`~cattrs.converters.Converter`の別名です。

exception cattrs.IterableValidationError(message, excs, cl)[ソース]

ベースクラス: BaseValidationError

iterable を構造化する際に発生します。

パラメータ:

cl (Type)

group_exceptions()[ソース]

例外を、検証ノートの有無にかかわらず、2 つのグループに分割します。

戻り値の型:

Tuple[List[Tuple[Exception, IterableValidationNote]], List[Exception]]

class cattrs.IterableValidationNote(string, index, type)[ソース]

ベースクラス: str

iterable 要素の構造化に失敗した場合、例外への注釈として添付されます。

パラメータ:

  • string (str)

  • index (int | str)

  • type (Any)

戻り値の型:

IterableValidationNote

type: Any
cattrs.override(omit_if_default=None, rename=None, omit=None, struct_hook=None, unstruct_hook=None)[ソース]

特定のフィールドの処理方法をオーバーライドします。

パラメータ:

  • omit (bool | None) -- フィールドをスキップするかどうか。None は、デフォルトの処理を適用することを意味します。

  • omit_if_default (bool | None)

  • rename (str | None)

  • struct_hook (Callable[[Any, Any], Any] | None)

  • unstruct_hook (Callable[[Any], Any] | None)

戻り値の型:

AttributeOverride

exception cattrs.StructureHandlerNotFoundError(message, type_)[ソース]

ベースクラス: Exception

構造化が、入力を type_ に変換するためのハンドラーを見つけられない場合に発生するエラー。

パラメータ:

  • message (str)

  • type_ (Type)

戻り値の型:

None

cattrs.transform_error(exc, path='$', format_exception=<function format_exception>)[ソース]

例外をエラーメッセージのリストに変換します。

詳細なエラーメッセージを取得するには、例外は detailed_validation が設定されたコンバーターによって生成される必要があります。

デフォルトでは、エラーメッセージは {description} @ {path} の形式です。

例外とサブ例外をトラバースする間、パスは次のように形成されます:

  • クラスのフィールドには .{field_name} を追加します

  • リストのような iterable のインデックスには [{int}] を追加します

  • 辞書のようなマッピングのキーには [{str}] を追加します

パラメータ:

  • exc (ClassValidationError | IterableValidationError | BaseException) -- エラーメッセージに変換する例外。

  • path (str) -- 使用するルートパス。

  • format_exception (Callable[[BaseException, type | None], str]) -- Exceptions をエラーの文字列記述に変換するために使用する呼び出し可能オブジェクト。

戻り値の型:

List[str]

Added in version 23.1.0.

class cattrs.UnstructureStrategy(*values)[ソース]

ベースクラス: Enum

attrs クラスの非構造化戦略。

AS_DICT = 'asdict'
AS_TUPLE = 'astuple'

サブパッケージ

サブモジュール

cattrs.cols モジュール

コレクションのユーティリティ関数。

cattrs.cols.is_any_set(type)[ソース]

ミュータブルセットとフローズンセットの両方の述語関数。

戻り値の型:

bool

cattrs.cols.is_frozenset(type)[ソース]

フローズンセットの述語関数。

組み込みのフローズンセットと typing モジュールのフローズンセットに一致します。

パラメータ:

type (Any)

戻り値の型:

bool

cattrs.cols.is_namedtuple(type)[ソース]

名前付きタプルの述語関数。

パラメータ:

type (Any)

戻り値の型:

bool

cattrs.cols.is_mapping(type)[ソース]

マッピングの述語関数。

パラメータ:

type (Any)

戻り値の型:

bool

cattrs.cols.is_set(type)

(ミュータブル) セットの述語関数。

組み込みのセットと typing モジュールのセットに一致します。

パラメータ:

type (Any)

戻り値の型:

bool

cattrs.cols.is_sequence(type)[ソース]

シーケンスの述語関数。

リスト、シーケンス、ミュータブルシーケンス、deque、および同種のタプルに一致します。

パラメータ:

type (Any)

戻り値の型:

bool

cattrs.cols.iterable_unstructure_factory(cl, converter, unstructure_to=None)[ソース]

iterable を非構造化するためのフックファクトリ。

パラメータ:

  • unstructure_to (Any) -- 提供されている場合、この型への非構造化を強制します。

  • cl (Any)

  • converter (BaseConverter)

戻り値の型:

UnstructureHook

cattrs.cols.list_structure_factory(type, converter)[ソース]

リストを構造化するためのフックファクトリ。

指定された iterable をリストに変換します。

パラメータ:
戻り値の型:

StructureHook

cattrs.cols.namedtuple_structure_factory(cl, converter)[ソース]

iterable から namedtuple を構造化するためのフックファクトリ。

パラメータ:
戻り値の型:

StructureHook

cattrs.cols.namedtuple_unstructure_factory(cl, converter, unstructure_to=None)[ソース]

namedtuple を非構造化するためのフックファクトリ。

パラメータ:

  • unstructure_to (Any) -- 提供されている場合、この型への非構造化を強制します。

  • cl (type[tuple])

  • converter (BaseConverter)

戻り値の型:

UnstructureHook

cattrs.cols.namedtuple_dict_structure_factory(cl, converter, detailed_validation='from_converter', forbid_extra_keys=False, use_linecache=True, /, **kwargs)[ソース]

辞書から namedtuple を構造化するフックのフックファクトリ。

パラメータ:

  • forbid_extra_keys (bool) -- 不明なキーが発生した場合、フックが ForbiddenExtraKeysError を発生させるかどうか。

  • use_linecache (bool) -- ソースコードを Python の linecache に保存するかどうか。

  • cl (type[tuple])

  • converter (BaseConverter)

  • detailed_validation (bool | Literal['from_converter'])

  • kwargs (AttributeOverride)

戻り値の型:

StructureHook

Added in version 24.1.0.

cattrs.cols.namedtuple_dict_unstructure_factory(cl, converter, omit_if_default=False, use_linecache=True, /, **kwargs)[ソース]

namedtuple を辞書に非構造化するフックのフックファクトリ。

パラメータ:

  • omit_if_default (bool) -- true の場合、デフォルト値と等しい属性は結果の辞書で省略されます。

  • use_linecache (bool) -- ソースコードを Python の linecache に保存するかどうか。

  • cl (type[tuple])

  • converter (BaseConverter)

  • kwargs (AttributeOverride)

戻り値の型:

UnstructureHook

Added in version 24.1.0.

cattrs.cols.mapping_structure_factory(cl, converter, structure_to=<class 'dict'>, key_type=NOTHING, val_type=NOTHING, detailed_validation=True)[ソース]

マッピングの特殊化された構造関数を生成します。

パラメータ:

  • cl (type[T])

  • converter (BaseConverter)

  • structure_to (type)

  • detailed_validation (bool)

戻り値の型:

MappingStructureFn[T]

cattrs.disambiguators モジュール

共用体 (sum 型) の曖昧さ回避のためのユーティリティ。

cattrs.disambiguators.is_supported_union(typ)[ソース]

型が attrs クラスの共用体であるかどうか。

パラメータ:

typ (Any)

戻り値の型:

bool

cattrs.disambiguators.create_default_dis_func(converter, *classes, use_literals=True, overrides='from_converter')[ソース]

attrs クラスまたは dataclass が与えられた場合、曖昧さ回避関数を生成します。

この関数は、デフォルトまたは一意の値を持たない一意のフィールドに基づいています。

パラメータ:

  • use_literals (bool) -- リテラルとして注釈が付けられたフィールドを曖昧さ回避に使用するかどうかを試します。

  • overrides (dict[str, AttributeOverride] | Literal['from_converter']) -- 適用する属性のオーバーライド。

  • converter (BaseConverter)

  • classes (type[AttrsInstance])

戻り値の型:

Callable[[Mapping[Any, Any]], type[Any] | None]

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

cattrs.dispatch モジュール

class cattrs.dispatch.FunctionDispatch(converter, handler_pairs=NOTHING)[ソース]

ベースクラス: object

FunctionDispatch は functools.singledispatch に似ていますが、メソッドの最初の引数の型を受け取り、True または False を返す関数に基づいてディスパッチします。

ディスパッチの決定に役立つオブジェクトは、インスタンス化されたオブジェクトである必要があります。

パラメータ:

  • converter (BaseConverter) -- コンバーターを必要とするファクトリに使用されるコンバーター。

  • handler_pairs (list[tuple[Predicate, Callable[[Any, Any], Any], bool, bool]])

バージョン 24.1.0 で変更: コンバーターを必要とするファクトリのサポート。したがって、これを作成するときにコンバーターが必要です。

クラス FunctionDispatch の attrs によって生成されたメソッド。

register(predicate, func, is_generator=False, takes_converter=False)[ソース]
パラメータ:

  • predicate (Callable[[Any], bool])

  • func (Callable[[...], Any])

戻り値の型:

None

dispatch(typ)[ソース]

渡されたオブジェクトの適切なハンドラーを返します。

パラメータ:

typ (Any)

戻り値の型:

Callable[[...], Any] | None

get_num_fns()[ソース]
戻り値の型:

int

copy_to(other, skip=0)[ソース]
パラメータ:
戻り値の型:

None

class cattrs.dispatch.MultiStrategyDispatch(fallback_factory, converter)[ソース]

ベースクラス: Generic[Hook]

MultiStrategyDispatch は、完全一致ディスパッチ、singledispatch、および FunctionDispatch の組み合わせを使用します。

パラメータ:

  • converter (BaseConverter) -- コンバーターを必要とするファクトリに使用されるコンバーター。

  • fallback_factory (HookFactory[Hook]) -- フックを生成できない場合に呼び出されるフックファクトリ。

バージョン 23.2.0 で変更: フォールバックはファクトリになりました。

バージョン 24.1.0 で変更: コンバーターを必要とするファクトリのサポート。したがって、これを作成するときにコンバーターが必要です。

dispatch: Callable[[TargetType, BaseConverter], Hook]
dispatch_without_caching(typ)[ソース]

型に基づいてディスパッチしますが、結果はキャッシュしません。

パラメータ:

typ (Any)

戻り値の型:

Hook

register_cls_list(cls_and_handler, direct=False)[ソース]

クラスを登録して、直接ディスパッチまたは singledispatch を行います。

パラメータ:

direct (bool)

戻り値の型:

None

register_func_list(pred_and_handler)[ソース]

述語関数を登録して、その型に対してハンドラーを使用する必要があるかどうかを判断します。

パラメータ:

pred_and_handler (list[tuple[Predicate, Any] | tuple[Predicate, Any, bool] | tuple[Predicate, Callable[[Any, BaseConverter], Any], Literal['extended']]]) -- 述語のリストとそれに関連付けられたハンドラー。ハンドラーが extended モードで登録されている場合、それはコンバーターを必要とするファクトリーです。

clear_direct()[ソース]

直接ディスパッチをクリアします。

戻り値の型:

None

clear_cache()[ソース]

すべてのキャッシュをクリアします。

戻り値の型:

None

get_num_fns()[ソース]
戻り値の型:

int

copy_to(other, skip=0)[ソース]
パラメータ:
戻り値の型:

None

cattrs.errors モジュール

exception cattrs.errors.StructureHandlerNotFoundError(message, type_)[ソース]

ベースクラス: Exception

構造化が、入力を type_ に変換するためのハンドラーを見つけられない場合に発生するエラー。

パラメータ:

  • message (str)

  • type_ (Type)

戻り値の型:

None

exception cattrs.errors.BaseValidationError(message, excs, cl)[ソース]

ベースクラス: ExceptionGroup

パラメータ:

cl (Type)

cl: Type
derive(excs)[ソース]
class cattrs.errors.IterableValidationNote(string, index, type)[ソース]

ベースクラス: str

iterable 要素の構造化に失敗した場合、例外への注釈として添付されます。

パラメータ:

  • string (str)

  • index (int | str)

  • type (Any)

戻り値の型:

IterableValidationNote

type: Any
exception cattrs.errors.IterableValidationError(message, excs, cl)[ソース]

ベースクラス: BaseValidationError

iterable を構造化する際に発生します。

パラメータ:

cl (Type)

group_exceptions()[ソース]

例外を、検証ノートの有無にかかわらず、2 つのグループに分割します。

戻り値の型:

Tuple[List[Tuple[Exception, IterableValidationNote]], List[Exception]]

class cattrs.errors.AttributeValidationNote(string, name, type)[ソース]

ベースクラス: str

属性の構造化に失敗した場合、例外への注釈として添付されます。

パラメータ:

  • string (str)

  • name (str)

  • type (Any)

戻り値の型:

AttributeValidationNote

name: str
type: Any
exception cattrs.errors.ClassValidationError(message, excs, cl)[ソース]

ベースクラス: BaseValidationError

属性が無効な場合にクラスを検証すると発生します。

パラメータ:

cl (Type)

group_exceptions()[ソース]

例外を、検証ノートの有無にかかわらず、2 つのグループに分割します。

戻り値の型:

Tuple[List[Tuple[Exception, AttributeValidationNote]], List[Exception]]

exception cattrs.errors.ForbiddenExtraKeysError(message, cl, extra_fields)[ソース]

ベースクラス: Exception

forbid_extra_keys がアクティブ化され、構造化中にそのような余分なキーが検出された場合に発生します。

属性 extra_fields は、このエラーの原因となった余分なキーのシーケンスであり、cl は、それらの余分なキーで構造化されたクラスです。

パラメータ:

  • message (str | None)

  • cl (Type)

  • extra_fields (Set[str])

戻り値の型:

None

cattrs.fns モジュール

役立つ内部関数。

cattrs.fns.Predicate

述語関数は、型を処理できるかどうかを判断します。

Callable[[Any], bool]の別名です。

cattrs.fns.identity(obj)[ソース]

恒等関数。

パラメータ:

obj (T)

戻り値の型:

T

cattrs.fns.raise_error(_, cl)[ソース]

条件スタックの一番下で、処理できない場合はエラーが発生します。

パラメータ:

cl (Type)

戻り値の型:

NoReturn

cattrs.v モジュール

Cattrs のバリデーション。

cattrs.v.format_exception(exc, type)[ソース]

デフォルトの例外フォーマッター。最も一般的な例外を処理します。

以下の例外は特別に処理されます:

  • KeyErrors ( required field missing )

  • ValueErrors ( invalid value for type, expected <type> または invalid value )

  • TypeErrors ( invalid value for type, expected <type> および、iterable のいくつかの特殊なケース )

  • cattrs.ForbiddenExtraKeysError

  • いくつかの AttributeErrors (構造化マッピング用に特別に処理されます)

パラメータ:

  • exc (BaseException)

  • type (type | None)

戻り値の型:

str

cattrs.v.transform_error(exc, path='$', format_exception=<function format_exception>)[ソース]

例外をエラーメッセージのリストに変換します。

詳細なエラーメッセージを取得するには、例外は detailed_validation が設定されたコンバーターによって生成される必要があります。

デフォルトでは、エラーメッセージは {description} @ {path} の形式です。

例外とサブ例外をトラバースする間、パスは次のように形成されます:

  • クラスのフィールドには .{field_name} を追加します

  • リストのような iterable のインデックスには [{int}] を追加します

  • 辞書のようなマッピングのキーには [{str}] を追加します

パラメータ:

  • exc (ClassValidationError | IterableValidationError | BaseException) -- エラーメッセージに変換する例外。

  • path (str) -- 使用するルートパス。

  • format_exception (Callable[[BaseException, type | None], str]) -- Exceptions をエラーの文字列記述に変換するために使用する呼び出し可能オブジェクト。

戻り値の型:

List[str]

Added in version 23.1.0.