cattrs package¶
Subpackages¶
Submodules¶
cattrs.converters module¶
- class cattrs.converters.BaseConverter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, prefer_attrib_converters=False, detailed_validation=True)[source]¶
Bases:
object
Converts between structured and unstructured data.
- Parameters
dict_factory (Callable[[], Any]) –
unstruct_strat (cattrs.converters.UnstructureStrategy) –
prefer_attrib_converters (bool) –
detailed_validation (bool) –
- Return type
None
- copy(dict_factory=None, unstruct_strat=None, prefer_attrib_converters=None, detailed_validation=None)[source]¶
- Parameters
dict_factory (Optional[Callable[[], Any]]) –
unstruct_strat (Optional[cattrs.converters.UnstructureStrategy]) –
prefer_attrib_converters (Optional[bool]) –
detailed_validation (Optional[bool]) –
- Return type
- detailed_validation¶
- register_structure_hook(cl, func)[source]¶
Register a primitive-to-class converter function for a type.
- The converter function should take two arguments:
a Python object to be converted,
the type to convert to
and return the instance of the class. The type may seem redundant, but is sometimes needed (for example, when dealing with generic classes).
- Parameters
cl (Any) –
func (Callable[[Any, Type[cattrs.converters.T]], cattrs.converters.T]) –
- Return type
None
- register_structure_hook_factory(predicate, factory)[source]¶
Register a hook factory for a given predicate.
A predicate is a function that, given a type, returns whether the factory can produce a hook for that type.
A factory is a callable that, given a type, produces a structuring hook for that type. This structuring hook will be cached.
- Parameters
predicate (Callable[[Any], bool]) –
factory (Callable[[Any], Callable[[Any, Any], Any]]) –
- Return type
None
- register_structure_hook_func(check_func, func)[source]¶
Register a class-to-primitive converter function for a class, using a function to check if it’s a match.
- Parameters
check_func (Callable[[Type[cattrs.converters.T]], bool]) –
func (Callable[[Any, Type[cattrs.converters.T]], cattrs.converters.T]) –
- Return type
None
- register_unstructure_hook(cls, func)[source]¶
Register a class-to-primitive converter function for a class.
The converter function should take an instance of the class and return its Python equivalent.
- Parameters
cls (Any) –
func (Callable[[Any], Any]) –
- Return type
None
- register_unstructure_hook_factory(predicate, factory)[source]¶
Register a hook factory for a given predicate.
A predicate is a function that, given a type, returns whether the factory can produce a hook for that type.
A factory is a callable that, given a type, produces an unstructuring hook for that type. This unstructuring hook will be cached.
- Parameters
predicate (Callable[[Any], bool]) –
factory (Callable[[Any], Callable[[Any], Any]]) –
- Return type
None
- register_unstructure_hook_func(check_func, func)[source]¶
Register a class-to-primitive converter function for a class, using a function to check if it’s a match.
- Parameters
check_func (Callable[[Any], bool]) –
func (Callable[[Any], Any]) –
- Return type
None
- structure(obj, cl)[source]¶
Convert unstructured Python data structures to structured data.
- Parameters
obj (Any) –
cl (Type[cattrs.converters.T]) –
- Return type
cattrs.converters.T
- structure_attrs_fromdict(obj, cl)[source]¶
Instantiate an attrs class from a mapping (dict).
- Parameters
obj (collections.abc.Mapping[str, Any]) –
cl (Type[cattrs.converters.T]) –
- Return type
cattrs.converters.T
- structure_attrs_fromtuple(obj, cl)[source]¶
Load an attrs class from a sequence (tuple).
- Parameters
obj (Tuple[Any, ...]) –
cl (Type[cattrs.converters.T]) –
- Return type
cattrs.converters.T
- property unstruct_strat: cattrs.converters.UnstructureStrategy¶
The default way of unstructuring
attrs
classes.
- unstructure(obj, unstructure_as=None)[source]¶
- Parameters
obj (Any) –
unstructure_as (Optional[Any]) –
- Return type
Any
- class cattrs.converters.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)[source]¶
Bases:
cattrs.converters.BaseConverter
A converter which generates specialized un/structuring functions.
- Parameters
dict_factory (Callable[[], Any]) –
unstruct_strat (cattrs.converters.UnstructureStrategy) –
omit_if_default (bool) –
forbid_extra_keys (bool) –
type_overrides (collections.abc.Mapping[Type, cattrs.gen.AttributeOverride]) –
unstruct_collection_overrides (collections.abc.Mapping[Type, Callable]) –
prefer_attrib_converters (bool) –
detailed_validation (bool) –
- 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)[source]¶
- Parameters
dict_factory (Optional[Callable[[], Any]]) –
unstruct_strat (Optional[cattrs.converters.UnstructureStrategy]) –
omit_if_default (Optional[bool]) –
forbid_extra_keys (Optional[bool]) –
type_overrides (Optional[collections.abc.Mapping[Type, cattrs.gen.AttributeOverride]]) –
unstruct_collection_overrides (Optional[collections.abc.Mapping[Type, Callable]]) –
prefer_attrib_converters (Optional[bool]) –
detailed_validation (Optional[bool]) –
- Return type
- forbid_extra_keys¶
- gen_structure_attrs_fromdict(cl)[source]¶
- Parameters
cl (Type[cattrs.converters.T]) –
- Return type
Callable[[collections.abc.Mapping[str, Any], Any], cattrs.converters.T]
- gen_structure_counter(cl)[source]¶
- Parameters
cl (Any) –
- Return type
Callable[[Mapping[Any, Any], Any], cattrs.converters.T]
- gen_structure_mapping(cl)[source]¶
- Parameters
cl (Any) –
- Return type
Callable[[Mapping[Any, Any], Any], cattrs.converters.T]
- gen_unstructure_attrs_fromdict(cl)[source]¶
- Parameters
cl (Type[cattrs.converters.T]) –
- Return type
Callable[[cattrs.converters.T], Dict[str, Any]]
- gen_unstructure_hetero_tuple(cl, unstructure_to=None)[source]¶
- Parameters
cl (Any) –
unstructure_to (Optional[Any]) –
- Return type
Callable[[Tuple[Any, …]], Any]
- gen_unstructure_iterable(cl, unstructure_to=None)[source]¶
- Parameters
cl (Any) –
unstructure_to (Optional[Any]) –
- Return type
Callable[[Iterable[Any]], Any]
- gen_unstructure_mapping(cl, unstructure_to=None, key_handler=None)[source]¶
- Parameters
cl (Any) –
unstructure_to (Optional[Any]) –
key_handler (Optional[Callable[[Any, Optional[Any]], Any]]) –
- Return type
Callable[[Mapping[Any, Any]], Any]
- get_structure_newtype(type)[source]¶
- Parameters
type (Type[cattrs.converters.T]) –
- Return type
Callable[[Any, Any], cattrs.converters.T]
- omit_if_default¶
- type_overrides¶
- cattrs.converters.GenConverter¶
alias of
cattrs.converters.Converter
- class cattrs.converters.UnstructureStrategy(value)[source]¶
Bases:
enum.Enum
attrs classes unstructuring strategies.
- AS_DICT = 'asdict'¶
- AS_TUPLE = 'astuple'¶
cattrs.disambiguators module¶
Utilities for union (sum type) disambiguation.
cattrs.dispatch module¶
- class cattrs.dispatch.FunctionDispatch(handler_pairs=NOTHING)[source]¶
Bases:
object
FunctionDispatch is similar to functools.singledispatch, but instead dispatches based on functions that take the type of the first argument in the method, and return True or False.
objects that help determine dispatch should be instantiated objects.
- Parameters
handler_pairs (list) –
- Return type
None
- copy_to(other, skip=0)[source]¶
- Parameters
other (cattrs.dispatch.FunctionDispatch) –
skip (int) –
- class cattrs.dispatch.MultiStrategyDispatch(fallback_func)[source]¶
Bases:
object
MultiStrategyDispatch uses a combination of exact-match dispatch, singledispatch, and FunctionDispatch.
- copy_to(other, skip=0)[source]¶
- Parameters
other (cattrs.dispatch.MultiStrategyDispatch) –
skip (int) –
- dispatch¶
cattrs.errors module¶
- exception cattrs.errors.BaseValidationError(message, excs, cl)[source]¶
Bases:
exceptiongroup.ExceptionGroup
- Parameters
cl (Type) –
- cl: Type¶
- exception cattrs.errors.ClassValidationError(message, excs, cl)[source]¶
Bases:
cattrs.errors.BaseValidationError
Raised when validating a class if any attributes are invalid.
- Parameters
cl (Type) –
- exception cattrs.errors.ForbiddenExtraKeysError(message, cl, extra_fields)[source]¶
Bases:
Exception
Raised when forbid_extra_keys is activated and such extra keys are detected during structuring.
The attribute extra_fields is a sequence of those extra keys, which were the cause of this error, and cl is the class which was structured with those extra keys.
- Parameters
message (Optional[str]) –
cl (Type) –
extra_fields (Set[str]) –
- Return type
None
- exception cattrs.errors.IterableValidationError(message, excs, cl)[source]¶
Bases:
cattrs.errors.BaseValidationError
Raised when structuring an iterable.
- Parameters
cl (Type) –
cattrs.gen module¶
- class cattrs.gen.AttributeOverride(omit_if_default=None, rename=None, omit=False)[source]¶
Bases:
object
- Parameters
omit_if_default (Optional[bool]) –
rename (Optional[str]) –
omit (bool) –
- Return type
None
- omit: bool¶
- omit_if_default: Optional[bool]¶
- rename: Optional[str]¶
- cattrs.gen.make_dict_structure_fn(cl, converter, _cattrs_forbid_extra_keys=False, _cattrs_use_linecache=True, _cattrs_prefer_attrib_converters=False, _cattrs_detailed_validation=True, **kwargs)[source]¶
Generate a specialized dict structuring function for an attrs class.
- Parameters
cl (Type[cattrs.gen.T]) –
converter (BaseConverter) –
_cattrs_forbid_extra_keys (bool) –
_cattrs_use_linecache (bool) –
_cattrs_prefer_attrib_converters (bool) –
_cattrs_detailed_validation (bool) –
kwargs (cattrs.gen.AttributeOverride) –
- Return type
Callable[[Mapping[str, Any], Any], cattrs.gen.T]
- cattrs.gen.make_dict_unstructure_fn(cl, converter, _cattrs_omit_if_default=False, _cattrs_use_linecache=True, **kwargs)[source]¶
Generate a specialized dict unstructuring function for an attrs class or a dataclass.
- Parameters
cl (Type[cattrs.gen.T]) –
converter (BaseConverter) –
_cattrs_omit_if_default (bool) –
_cattrs_use_linecache (bool) –
kwargs (cattrs.gen.AttributeOverride) –
- Return type
Callable[[cattrs.gen.T], Dict[str, Any]]
- cattrs.gen.make_hetero_tuple_unstructure_fn(cl, converter, unstructure_to=None)[source]¶
Generate a specialized unstructure function for a heterogenous tuple.
- Parameters
cl (Any) –
converter (BaseConverter) –
unstructure_to (Any) –
- Return type
Callable[[Tuple[Any, …]], Any]
- cattrs.gen.make_iterable_unstructure_fn(cl, converter, unstructure_to=None)[source]¶
Generate a specialized unstructure function for an iterable.
- Parameters
cl (Any) –
converter (BaseConverter) –
unstructure_to (Any) –
- Return type
Callable[[Iterable[Any]], Any]
- cattrs.gen.make_mapping_structure_fn(cl, converter, structure_to=<class 'dict'>, key_type=NOTHING, val_type=NOTHING, detailed_validation=True)[source]¶
Generate a specialized unstructure function for a mapping.
- Parameters
cl (Type[cattrs.gen.T]) –
converter (BaseConverter) –
structure_to (Type) –
detailed_validation (bool) –
- Return type
Callable[[Mapping[Any, Any], Any], cattrs.gen.T]
- cattrs.gen.make_mapping_unstructure_fn(cl, converter, unstructure_to=None, key_handler=None)[source]¶
Generate a specialized unstructure function for a mapping.
- Parameters
cl (Any) –
converter (BaseConverter) –
unstructure_to (Any) –
key_handler (Optional[Callable[[Any, Optional[Any]], Any]]) –
- Return type
Callable[[Mapping[Any, Any]], Any]
Module contents¶
- class cattrs.BaseConverter(dict_factory=<class 'dict'>, unstruct_strat=UnstructureStrategy.AS_DICT, prefer_attrib_converters=False, detailed_validation=True)[source]¶
Bases:
object
Converts between structured and unstructured data.
- Parameters
dict_factory (Callable[[], Any]) –
unstruct_strat (cattrs.converters.UnstructureStrategy) –
prefer_attrib_converters (bool) –
detailed_validation (bool) –
- Return type
None
- copy(dict_factory=None, unstruct_strat=None, prefer_attrib_converters=None, detailed_validation=None)[source]¶
- Parameters
dict_factory (Optional[Callable[[], Any]]) –
unstruct_strat (Optional[cattrs.converters.UnstructureStrategy]) –
prefer_attrib_converters (Optional[bool]) –
detailed_validation (Optional[bool]) –
- Return type
- detailed_validation¶
- register_structure_hook(cl, func)[source]¶
Register a primitive-to-class converter function for a type.
- The converter function should take two arguments:
a Python object to be converted,
the type to convert to
and return the instance of the class. The type may seem redundant, but is sometimes needed (for example, when dealing with generic classes).
- Parameters
cl (Any) –
func (Callable[[Any, Type[cattrs.converters.T]], cattrs.converters.T]) –
- Return type
None
- register_structure_hook_factory(predicate, factory)[source]¶
Register a hook factory for a given predicate.
A predicate is a function that, given a type, returns whether the factory can produce a hook for that type.
A factory is a callable that, given a type, produces a structuring hook for that type. This structuring hook will be cached.
- Parameters
predicate (Callable[[Any], bool]) –
factory (Callable[[Any], Callable[[Any, Any], Any]]) –
- Return type
None
- register_structure_hook_func(check_func, func)[source]¶
Register a class-to-primitive converter function for a class, using a function to check if it’s a match.
- Parameters
check_func (Callable[[Type[cattrs.converters.T]], bool]) –
func (Callable[[Any, Type[cattrs.converters.T]], cattrs.converters.T]) –
- Return type
None
- register_unstructure_hook(cls, func)[source]¶
Register a class-to-primitive converter function for a class.
The converter function should take an instance of the class and return its Python equivalent.
- Parameters
cls (Any) –
func (Callable[[Any], Any]) –
- Return type
None
- register_unstructure_hook_factory(predicate, factory)[source]¶
Register a hook factory for a given predicate.
A predicate is a function that, given a type, returns whether the factory can produce a hook for that type.
A factory is a callable that, given a type, produces an unstructuring hook for that type. This unstructuring hook will be cached.
- Parameters
predicate (Callable[[Any], bool]) –
factory (Callable[[Any], Callable[[Any], Any]]) –
- Return type
None
- register_unstructure_hook_func(check_func, func)[source]¶
Register a class-to-primitive converter function for a class, using a function to check if it’s a match.
- Parameters
check_func (Callable[[Any], bool]) –
func (Callable[[Any], Any]) –
- Return type
None
- structure(obj, cl)[source]¶
Convert unstructured Python data structures to structured data.
- Parameters
obj (Any) –
cl (Type[cattrs.converters.T]) –
- Return type
cattrs.converters.T
- structure_attrs_fromdict(obj, cl)[source]¶
Instantiate an attrs class from a mapping (dict).
- Parameters
obj (collections.abc.Mapping[str, Any]) –
cl (Type[cattrs.converters.T]) –
- Return type
cattrs.converters.T
- structure_attrs_fromtuple(obj, cl)[source]¶
Load an attrs class from a sequence (tuple).
- Parameters
obj (Tuple[Any, ...]) –
cl (Type[cattrs.converters.T]) –
- Return type
cattrs.converters.T
- property unstruct_strat: cattrs.converters.UnstructureStrategy¶
The default way of unstructuring
attrs
classes.
- unstructure(obj, unstructure_as=None)[source]¶
- Parameters
obj (Any) –
unstructure_as (Optional[Any]) –
- Return type
Any
- exception cattrs.BaseValidationError(message, excs, cl)[source]¶
Bases:
exceptiongroup.ExceptionGroup
- Parameters
cl (Type) –
- cl: Type¶
- exception cattrs.ClassValidationError(message, excs, cl)[source]¶
Bases:
cattrs.errors.BaseValidationError
Raised when validating a class if any attributes are invalid.
- Parameters
cl (Type) –
- 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)[source]¶
Bases:
cattrs.converters.BaseConverter
A converter which generates specialized un/structuring functions.
- Parameters
dict_factory (Callable[[], Any]) –
unstruct_strat (cattrs.converters.UnstructureStrategy) –
omit_if_default (bool) –
forbid_extra_keys (bool) –
type_overrides (collections.abc.Mapping[Type, cattrs.gen.AttributeOverride]) –
unstruct_collection_overrides (collections.abc.Mapping[Type, Callable]) –
prefer_attrib_converters (bool) –
detailed_validation (bool) –
- 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)[source]¶
- Parameters
dict_factory (Optional[Callable[[], Any]]) –
unstruct_strat (Optional[cattrs.converters.UnstructureStrategy]) –
omit_if_default (Optional[bool]) –
forbid_extra_keys (Optional[bool]) –
type_overrides (Optional[collections.abc.Mapping[Type, cattrs.gen.AttributeOverride]]) –
unstruct_collection_overrides (Optional[collections.abc.Mapping[Type, Callable]]) –
prefer_attrib_converters (Optional[bool]) –
detailed_validation (Optional[bool]) –
- Return type
- forbid_extra_keys¶
- gen_structure_attrs_fromdict(cl)[source]¶
- Parameters
cl (Type[cattrs.converters.T]) –
- Return type
Callable[[collections.abc.Mapping[str, Any], Any], cattrs.converters.T]
- gen_structure_counter(cl)[source]¶
- Parameters
cl (Any) –
- Return type
Callable[[Mapping[Any, Any], Any], cattrs.converters.T]
- gen_structure_mapping(cl)[source]¶
- Parameters
cl (Any) –
- Return type
Callable[[Mapping[Any, Any], Any], cattrs.converters.T]
- gen_unstructure_attrs_fromdict(cl)[source]¶
- Parameters
cl (Type[cattrs.converters.T]) –
- Return type
Callable[[cattrs.converters.T], Dict[str, Any]]
- gen_unstructure_hetero_tuple(cl, unstructure_to=None)[source]¶
- Parameters
cl (Any) –
unstructure_to (Optional[Any]) –
- Return type
Callable[[Tuple[Any, …]], Any]
- gen_unstructure_iterable(cl, unstructure_to=None)[source]¶
- Parameters
cl (Any) –
unstructure_to (Optional[Any]) –
- Return type
Callable[[Iterable[Any]], Any]
- gen_unstructure_mapping(cl, unstructure_to=None, key_handler=None)[source]¶
- Parameters
cl (Any) –
unstructure_to (Optional[Any]) –
key_handler (Optional[Callable[[Any, Optional[Any]], Any]]) –
- Return type
Callable[[Mapping[Any, Any]], Any]
- get_structure_newtype(type)[source]¶
- Parameters
type (Type[cattrs.converters.T]) –
- Return type
Callable[[Any, Any], cattrs.converters.T]
- omit_if_default¶
- type_overrides¶
- exception cattrs.ForbiddenExtraKeysError(message, cl, extra_fields)[source]¶
Bases:
Exception
Raised when forbid_extra_keys is activated and such extra keys are detected during structuring.
The attribute extra_fields is a sequence of those extra keys, which were the cause of this error, and cl is the class which was structured with those extra keys.
- Parameters
message (Optional[str]) –
cl (Type) –
extra_fields (Set[str]) –
- Return type
None
- cattrs.GenConverter¶
alias of
cattrs.converters.Converter
- exception cattrs.IterableValidationError(message, excs, cl)[source]¶
Bases:
cattrs.errors.BaseValidationError
Raised when structuring an iterable.
- Parameters
cl (Type) –
- exception cattrs.StructureHandlerNotFoundError(message, type_)[source]¶
Bases:
Exception
Error raised when structuring cannot find a handler for converting inputs into
type_
.- Parameters
message (str) –
type_ (Type) –
- Return type
None
- class cattrs.UnstructureStrategy(value)[source]¶
Bases:
enum.Enum
attrs classes unstructuring strategies.
- AS_DICT = 'asdict'¶
- AS_TUPLE = 'astuple'¶
- cattrs.override(omit_if_default=None, rename=None, omit=False)[source]¶
- Parameters
omit_if_default (Optional[bool]) –
rename (Optional[str]) –
omit (bool) –
- cattrs.register_structure_hook(cl, func)¶
Register a primitive-to-class converter function for a type.
- The converter function should take two arguments:
a Python object to be converted,
the type to convert to
and return the instance of the class. The type may seem redundant, but is sometimes needed (for example, when dealing with generic classes).
- Parameters
cl (Any) –
func (Callable[[Any, Type[cattrs.converters.T]], cattrs.converters.T]) –
- Return type
None
- cattrs.register_structure_hook_func(check_func, func)¶
Register a class-to-primitive converter function for a class, using a function to check if it’s a match.
- Parameters
check_func (Callable[[Type[cattrs.converters.T]], bool]) –
func (Callable[[Any, Type[cattrs.converters.T]], cattrs.converters.T]) –
- Return type
None
- cattrs.register_unstructure_hook(cls, func)¶
Register a class-to-primitive converter function for a class.
The converter function should take an instance of the class and return its Python equivalent.
- Parameters
cls (Any) –
func (Callable[[Any], Any]) –
- Return type
None
- cattrs.register_unstructure_hook_func(check_func, func)¶
Register a class-to-primitive converter function for a class, using a function to check if it’s a match.
- Parameters
check_func (Callable[[Any], bool]) –
func (Callable[[Any], Any]) –
- Return type
None
- cattrs.structure(obj, cl)¶
Convert unstructured Python data structures to structured data.
- Parameters
obj (Any) –
cl (Type[cattrs.converters.T]) –
- Return type
cattrs.converters.T
- cattrs.structure_attrs_fromdict(obj, cl)¶
Instantiate an attrs class from a mapping (dict).
- Parameters
obj (collections.abc.Mapping[str, Any]) –
cl (Type[cattrs.converters.T]) –
- Return type
cattrs.converters.T
- cattrs.structure_attrs_fromtuple(obj, cl)¶
Load an attrs class from a sequence (tuple).
- Parameters
obj (Tuple[Any, ...]) –
cl (Type[cattrs.converters.T]) –
- Return type
cattrs.converters.T
- cattrs.unstructure(obj, unstructure_as=None)¶
- Parameters
obj (Any) –
unstructure_as (Optional[Any]) –
- Return type
Any