4.6. Annotation Registry#

Module for managing and performing type conversions using custom handlers.

This module provides the TypeConverter class, which is designed to define and manage type conversion handlers for various Python annotations. These handlers allow you to convert different types (like int, str, etc.) into a specialized _StructLike object, which could be used in custom @struct classes.

The TypeConverter class allows for both explicit and delegated conversions, where the user can define how each annotation should be converted, and even delegate the conversion to external functions.

The module also provides a global registry (annotation_registry) to store type converters and a utility function (to_struct()) to perform type conversions using these registered handlers.

Example Usage:

Define a converter for int that converts to uint16:

>>> tc = TypeConverter(int, lambda a, _: Const(a, uint16))

Alternatively, you can use a decorator to define a type converter:

>>> @TypeConverter(int)
... def int_converter(annotation, kwargs):
...     return Const(annotation, uint16)
class caterpillar.registry.TypeConverter(target: type | None = None, delegate: Callable[[Any, dict[str, Any]], _StructLike] | None = None)[source]#

A utility class to define and manage type conversion handlers for annotations.

Type converters take the placed annotation and convert it into a _StructLike object. For instance, a simple converter that always returns uint32 for an object of the Python int class might look like this:

>>> tc = TypeConverter(int, lambda a, _: Const(a, uint16))

or directly as annotation

>>> @TypeConverter(int)
... def int_converter(annotation, kwargs):
...     return Const(annotation, uint16)
...
Parameters:

  • target (Type, optional) – the target type, defaults to None

  • delegate (Callable[[Any, dict], _StructLike], optional) – optional delegation function, defaults to None

delegate: Callable[[Any, dict[str, Any]], _StructLike[Any, Any]] | None#

optional delegation function

matches(annotation: object) → bool[source]#

Check if this converter matches the given annotation type.

Parameters:

annotation (Any) – he type or object to match against the target.

Returns:

True if the annotation matches the target type; otherwise False.

Return type:

bool

convert(annotation: object, kwargs: dict[str, Any]) → _StructLike[source]#

Convert the given annotation (uses the delegate function by default).

Parameters:

  • annotation (Any) – The object to be converted.

  • kwargs (dict) – Additional arguments for the conversion.

Raises:

NotImplementedError – If no delegate is defined for the converter.

Returns:

The converted object.

Return type:

_StructLike

caterpillar.registry.annotation_registry: list[TypeConverter] = [<TypeConverter for dict>, <_EnumTypeConverter>, <TypeConverter for _StructLike>, <_CallableTypeConverter>, <TypeConverter for str>, <TypeConverter for bytes>, <_StructTypeConverter>]#

A global registry to store type converters.

caterpillar.registry.to_struct(obj: object, **kwargs: Any) → _StructLike[source]#

Convert an object to a _StruckLike object using registered type converters.

This function will not convert any objects that are already implementing the functions of _StructLike.

Parameters:

  • obj (Any) – The object to be converted.

  • kwargs – Additional arguments passed to the conversion handler.

Raises:

ValidationError – If no matching type converter is found for the object.

Returns:

the converted object

Return type:

_StructLike