4.7. Shared Concepts

caterpillar.shared.ATTR_STRUCT = "__struct__"

All models annotated with either @struct or @bitfield are struct containers. Thus, they store the additional class attribute __struct__.

Internally, any types utilizing this attribute can be employed within a struct, bitfield, or sequence definition. The type of the stored value must be conforming to the _StructLike protocol.

Changed in version 2.5.0: This attribute is now used when callung getstruct() or hasstruct().

caterpillar.shared.ATTR_BYTEORDER = "__byteorder__"

Added in version 2.5.0: Moved from caterpillar.byteorder.

caterpillar.shared.ATTR_TYPE = "__type__"

Added in version 2.5.0.

caterpillar.shared.ATTR_BITS = "__bits__"

Added in version 2.5.0: Moved from caterpillar.model._bitfield.

caterpillar.shared.ATTR_SIGNED = "__signed__"

Added in version 2.5.0: Moved from caterpillar.model._bitfield.

caterpillar.shared.ATTR_TEMPLATE = "__template__"

Added in version 2.5.0: Moved from caterpillar.model._template.

caterpillar.shared.ATTR_ACTION_PACK = "__action_pack__"

Added in version 2.4.0.

caterpillar.shared.ATTR_ACTION_UNPACK = "__action_unpack__"

Added in version 2.4.0.

caterpillar.shared.MODE_PACK = 0

caterpillar.shared.MODE_UNPACK = 1

caterpillar.shared.getstruct(obj, /, __default=None)

Get the structure attribute of the given object.

Parameters:

obj – The object to get the structure attribute from.

Returns:

The structure attribute of the object.

caterpillar.shared.hasstruct(obj) → bool

Check if the given object has a structure attribute.

Parameters:

obj – The object to check.

Returns:

True if the object has a structure attribute, else False.

caterpillar.shared.typeof(struct)

class caterpillar.shared.Action(pack=None, unpack=None, both=None)

A class representing an action to be executed during the parsing or processing of a struct. This is used for cases where a field requires an operation to be performed instead of directly storing data.

An action can be used to execute custom logic (such as modifying the IO stream) before the next field is processed. For example, it could be used to trigger checksum or hash calculations before reading a struct field.

There are two types of actions:

1. Packing actions: These actions are triggered before packing the data into the struct (i.e., before serializing or encoding).

2. Unpacking actions: These actions are triggered before unpacking the data from the struct (i.e., before deserializing or decoding).

Example:

>>> def checksum_action(context: _ContextLike) -> None:
...     # This action could perform some checksum or logging logic
...     pass
...
>>> @struct
... class MyStruct:
...     some_field: Bytes(10)
...     checksum: Action(checksum_action) # runs only when packing

In this example, the checksum field is an action, and the checksum_action will be invoked before the some_field field is parsed.

The action itself is not stored as part of the struct’s model; it merely runs during struct processing.

Parameters:

• pack (_ContextLambda | None) – The callable that will be executed before packing the struct (optional).

• unpack (_ContextLambda | None) – The callable that will be executed before unpacking the struct (optional).