cattrs.strategies package#

Module contents#

High level strategies for converters.

cattrs.strategies.configure_tagged_union(union, converter, tag_generator=<function default_tag_generator>, tag_name='_type', default=_Nothing.NOTHING)[source]#

Configure the converter so that union (which should be a union) is un/structured with the help of an additional piece of data in the unstructured payload, the tag.

Parameters:

  • converter (Converter) – The converter to apply the strategy to.

  • tag_generator (Callable[[Type], str]) – A tag_generator function is used to map each member of the union to a tag, which is then included in the unstructured payload. The default tag generator returns the name of the class.

  • tag_name (str) – The key under which the tag will be set in the unstructured payload. By default, ‘_type’.

  • default (Type | None) – An optional class to be used if the tag information is not present when structuring.

  • union (Any) –

Return type:

None

The tagged union strategy currently only works with the dict un/structuring base strategy.

New in version 23.1.0.

cattrs.strategies.configure_union_passthrough(union, converter)[source]#

Configure the converter to support validating and passing through unions of the provided types and their subsets.

For example, all mature JSON libraries natively support producing unions of ints, floats, Nones, and strings. Using this strategy, a converter can be configured to efficiently validate and pass through unions containing these types.

The most important point is that another library (in this example the JSON library) handles producing the union, and the converter is configured to just validate it.

Literals of provided types are also supported, and are checked by value.

NewTypes of provided types are also supported.

The strategy is designed to be O(1) in execution time, and independent of the ordering of types in the union.

If the union contains a class and one or more of its subclasses, the subclasses will also be included when validating the superclass.

New in version 23.2.0.

Parameters:
Return type:

None

cattrs.strategies.include_subclasses(cl, converter, subclasses=None, union_strategy=None, overrides=None)[source]#

Configure the converter so that the attrs/dataclass cl is un/structured as if it was a union of itself and all its subclasses that are defined at the time when this strategy is applied.

Parameters:

  • cl (Type) – A base attrs or dataclass class.

  • converter (Converter) – The Converter on which this strategy is applied. Do note that the strategy does not work for a cattrs.BaseConverter.

  • subclasses (Tuple[Type, ...] | None) – A tuple of sublcasses whose ancestor is cl. If left as None, subclasses are detected using recursively the __subclasses__ method of cl and its descendents.

  • union_strategy (Callable[[Any, BaseConverter], Any] | None) – A callable of two arguments passed by position (subclass_union, converter) that defines the union strategy to use to disambiguate the subclasses union. If None (the default), the automatic unique field disambiguation is used which means that every single subclass participating in the union must have an attribute name that does not exist in any other sibling class.

  • overrides (Dict[str, AttributeOverride] | None) – a mapping of cl attribute names to overrides (instantiated with cattrs.gen.override()) to customize un/structuring.

Return type:

None

New in version 23.1.0.

cattrs.strategies.use_class_methods(converter, structure_method_name=None, unstructure_method_name=None)[source]#

Configure the converter such that dedicated methods are used for (un)structuring the instance of a class if such methods are available. The default (un)structuring will be applied if such an (un)structuring methods cannot be found.

Parameters:

  • converter (BaseConverter) – The Converter on which this strategy is applied. You can use cattrs.BaseConverter or any other derived class.

  • structure_method_name (str | None) – Optional string with the name of the class method which should be used for structuring. If not provided, no class method will be used for structuring.

  • unstructure_method_name (str | None) – Optional string with the name of the class method which should be used for unstructuring. If not provided, no class method will be used for unstructuring.

Return type:

None

If you want to (un)structured nested objects, just append a converter parameter to your (un)structuring methods and you will receive the converter there.

New in version 23.2.0.