Struct Model#

TODO

Base classes#

class caterpillar.model.Sequence[source]#

Default implementation for a sequence of fields.

The native Python type mapped to this struct class is dict. To convert a dictionary into a sequence, you can either use the contructor directly or apply the type converter for this class:

>>> to_struct({'a': uint8})
Sequence(fields=['a'])
add_field(name: str, field: Field, included: bool = False) → None[source]#

Add a field to the struct.

Parameters:

  • name – The name of the field.

  • field – The field to add.

  • included – True if the field should be included, else False.

arch: Arch | None#

Global architecture definition (will be inferred on all fields)

del_field(name: str, field: Field) → None[source]#

Remomves a field from this struct.

Parameters:

  • name – The name of the field.

  • field – The field to remove.

field_options: Set[Flag]#

Global field flags that will be applied on all fields.

fields: List[Field]#

A list of all fields defined in this struct.

This attribute stores the fields in an ordered collection, whereby ordered means, relative to their initial class declaration position. These fields can be modified using add_field, del_field or the operators + and -.

has_option(option: Flag) → bool[source]#

Check if the struct has a specific option.

Parameters:

option – The option to check.

Returns:

True if the struct has the specified option, else False.

model: Any#

Specifies the target class/dictionary used as the base model.

options: Set[Flag]#

Additional options specifying what to include in the final class.

order: ByteOrder | None#

Optional configuration value for the byte order of a field.__annotations__

class caterpillar.model.Struct[source]#

Represents a structured data model for serialization and deserialization.

Parameters:

  • model – The target class used as the base model.

  • order – Optional byte order for the fields in the structure.

  • arch – Global architecture definition (will be inferred on all fields).

  • options – Additional options specifying what to include in the final class.

class caterpillar.model.BitFieldGroup(size: int, pos: int, fields: Dict = None)[source]#
class caterpillar.model.BitField(model: type, order: ByteOrder | None = None, arch: Arch | None = None, options: Iterable[Flag] = None, field_options: Iterable[Flag] = None)[source]#
class caterpillar.model.UnionHook(struct_: Struct)[source]#

Implementation of a hook to simulate union types.

It will hook two methods of the target model type: __init__ and __setattr__. Because the constructor calls setattr for each attribute in the model, we have to intercept it before it gets called to set an internal status.

Internally, these two methods will be translated into __model_init__() and __model_setattr__(). Therefore, any class that implements these two methods can be used as a union hook.

max_size: int#

The static (cached) maximum size of the union

struct: Struct#

The struct reference

Standard functions#

caterpillar.model.struct(cls: type = None, /, **kwds)[source]#

Decorator to create a Struct class.

Parameters:

  • cls – The target class used as the base model.

  • options – Additional options specifying what to include in the final class.

  • order – Optional configuration value for the byte order of a field.

  • arch – Global architecture definition (will be inferred on all fields).

Returns:

The created Struct class or a wrapper function if cls is not provided.

caterpillar.model.union(cls: type = None, /, *, options: Iterable[Flag] = None, **kwds)[source]#

Decorator to create a Union class.

Parameters:

  • cls – The target class used as the base model.

  • options – Additional options specifying what to include in the final class.

  • order – Optional configuration value for the byte order of a field.

  • arch – Global architecture definition (will be inferred on all fields).

Returns:

The created Union class or a wrapper function if cls is not provided.

caterpillar.model.pack(obj: Any | _ContainsStruct, struct: _StructLike | None = None, **kwds) → bytes[source]#

Pack an object into a bytes buffer using the specified struct.

Parameters:

  • obj – The object to pack.

  • struct – The struct to use for packing.

  • kwds – Additional keyword arguments to pass to the pack function.

Returns:

The packed bytes.

caterpillar.model.pack_into(obj: Any | _ContainsStruct, buffer: IOBase, struct: _StructLike | None = None, use_tempfile: bool = False, **kwds) → None[source]#

Pack an object into the specified buffer using the specified struct.

Parameters:

  • obj – The object to pack.

  • buffer – The buffer to pack the object into.

  • struct – The struct to use for packing.

  • kwds – Additional keyword arguments to pass to the pack function.

Returns:

None

caterpillar.model.pack_file(obj: Any | _ContainsStruct, filename: str, struct: _StructLike | None = None, use_tempfile: bool = False, **kwds) → None[source]#

Pack an object into a file using the specified struct.

Parameters:

  • obj – The object to pack.

  • filename – The name of the file to write to.

  • struct – The struct to use for packing.

  • kwds – Additional keyword arguments to pass to the pack function.

Returns:

None

caterpillar.model.unpack(struct: _SupportsUnpack | _ContainsStruct, buffer: bytes | IOBase, **kwds) → Any[source]#

Unpack an object from a bytes buffer or stream using the specified struct.

Parameters:

  • struct – The struct to use for unpacking.

  • buffer – The bytes buffer or stream to unpack from.

  • kwds – Additional keyword arguments to pass to the unpack function.

Returns:

The unpacked object.

caterpillar.model.unpack_file(struct: _StructLike | _ContainsStruct, filename: str, **kwds) → Any[source]#

Unpack an object from a file using the specified struct.

Parameters:

  • struct – The struct to use for unpacking.

  • filename – The name of the file to read from.

  • kwds – Additional keyword arguments to pass to the unpack function.

Returns:

The unpacked object.

caterpillar.model.bitfield(cls: type = None, /, *, options: Iterable[Flag] = None, order: ByteOrder | None = None, arch: Arch | None = None, field_options: Iterable[Flag] = None)[source]#

Templates#

class caterpillar.model.TemplateTypeVar(name: str, **field_kwds)[source]#

Template type variable.

These specialised type variables are used within a template definition. They support most field operators. Therefore, they can be used in some situations where you need to adapt the field type at runtime.

>>> T = TemplateTypeVar("T")

Note that there is currently no support for inlined type variables, for example:

>>> @template(T)
... class Foo:
...     bar: Enum(Baz, T) # !!! throws an error

is not possible.

field_kwds: Dict[str, Any]#

Arguments that will be passed to the created field instance.

name: str#

The bound name of this type variable

caterpillar.model.istemplate(obj: Any) → bool[source]#

Return true if the object is a template.

caterpillar.model.template(*args: str | TemplateTypeVar, **kwargs) → Callable[[type], type][source]#

Defines required template type variables if necessary and prepares template class definition.

Returns:

a wrapper function that will be called with the class instance

Return type:

Callable[[type], type]

caterpillar.model.derive(template_ty: type, *tys_args, partial=False, name=None, union=False, **tys_kwargs) → type[source]#

Creates a new struct class based on the given template class.

Parameters:

  • template_ty (type) – the template class

  • partial (bool, optional) – whether the resulting class is also a template, defaults to False

  • name (str | Ellipsis, optional) – the new class name, ... infers the outer variable name, defaults to None

Returns:

the derived type

Return type:

type