4.8.1. Field Model

class caterpillar.fields.Field(struct, order=None, offset=-1, flags=None, amount=0, options=None, condition=True, arch=None, default=<object object>, bits=None)

Represents a field in a data structure.

Parameters:

• struct – The structure or callable used to define the field’s type.

• order – Byte order for the field (default: SysNative).

• offset – Field offset or callable (default: -1, meaning no explicit offset).

• flags – Optional set of flags associated with the field.

• amount – The number of elements if this field is a sequence (default: 0).

• options – A dictionary representing a switch-case mapping.

• condition – A boolean or callable determining whether the field is active.

• arch – Architecture specification (default: system_arch).

• default – The default value (default: INVALID_DEFAULT).

• bits – Bit size if the field is bit-packed.

property struct

The internal structure for this field.

property condition

The field’s condition expression or value.

property flags

The set of flags associated with this field.

add_flag(flag) → None

Adds a flag to this field.

Parameters:

flag – The flag to add.

Added in version 2.6.0.

has_flag(flag: Flag) → bool

Checks whether this field stores the given flag.

Parameters:

flag (Flag) – the flag to lookup

Returns:

true if this flag has been found

Return type:

bool

remove_flag(flag: Flag) → None

Removes a flag from this field.

Parameters:

flag – The flag to remove.

Added in version 2.6.0.

property offset

The field’s offset.

property amount

The repetition count for this field.

property options

The switch-case options dictionary.

_verify_context_value(value, expected) → None

Verifies that a value is either of the expected type(s) or is a callable. Used to validate inputs for context-aware fields.

Parameters:

• value – The value to validate.

• expected – A type or tuple of valid types.

Raises:

TypeError – If validation fails.

is_seq() → bool

Returns whether this field is sequential.

Returns:

whether this field is sequental

Return type:

bool

is_enabled(context) → bool

Evaluates the condition of this field.

Parameters:

context (_ContextLike) – the context on which to operate

Returns:

True, if this field is enabled

Return type:

bool

has_condition() → bool

Returns whether this field is linked to a condition

length(context)

Calculates the sequence length of this field.

Parameters:

context (_ContextLike) – the context on which to operate

Raises:

DynamicSizeError – if this field has a dynamic size

Returns:

the number of elements

Return type:

Union[int, _GreedyType]

get_struct(value, context)

Returns the struct from stored options.

Parameters:

• value (Any) – the unpacked or packed value

• context (_ContextLike) – the current context

Returns:

the struct that packs or unpacks the data

Return type:

_StructLike

get_offset(context) → int

Returns the offset position of this field

get_type()

Returns the annotation type for this field

Returns:

the annotation type

Return type:

type

get_name()

class caterpillar.fields.FieldMixin

A simple mixin to support operators used to create Field instances.

class caterpillar.fields.FieldStruct

A mix-in class combining the behavior of _StructLike with additional functionality for packing and unpacking structured data.

pack_single(obj, context) → None

Abstract method to pack a single element.

Parameters:

• obj (Any) – The element to pack.

• context (_ContextLike) – The current operation context.

Raises:

NotImplementedError – This method must be implemented by subclasses.

unpack_single(context)

Abstract method to unpack a single element.

Parameters:

context (_ContextLike) – The current operation context.

Raises:

NotImplementedError – This method must be implemented by subclasses.

Returns:

The unpacked element.

pack_seq(seq, context) → None

Pack a sequence of elements using the provided context.

Parameters:

• seq (Iterable) – The sequence of elements to pack.

• context (_ContextLike) – The current operation context.

unpack_seq(context)

Unpack a sequence of elements using the provided context.

Parameters:

context (_ContextLike) – The current operation context.

Returns:

The list of unpacked elements.

__pack__(obj, context) → None

Pack data based on whether the field is sequential or not.

Parameters:

• obj (Any) – The data to pack.

• context (_ContextLike) – The current operation context.

__unpack__(context)

Unpack data based on whether the field is sequential or not.

Parameters:

context (_ContextLike) – The current operation context.

Returns:

The unpacked data.

__repr__() → str

String representation of the FieldStruct instance.

Returns:

A string representation.

__byteorder__

An internal field used to measure the byte order of this struct.

Note that this field will be used during processing only and not during parsing or building data. In addition, the actual byte order should be retrieved using the Field instance within the context.

__bits__

TBD

class caterpillar.fields.Chain(initial, *structs)

Represents a chain of structures where each structure in the chain is linked to the next one, forming a sequence.

Parameters:

• initial – The initial structure in the chain.

• structs – Additional structures to be added to the chain.

The chain allows packing and unpacking data through its elements in sequence.

Note

• Unpacking travels from the head to the tail.

• Packing travels from the tail to the head.

__init__(initial, *structs) → None

property head

Get the head of the chain, i.e., the first structure.

Returns:

The head of the chain.

Return type:

_StructLike

property tail

Get the tail of the chain, i.e., the last structure.

Returns:

The tail of the chain.

Return type:

_StructLike

__size__(context) → int

Calculate the size of the chain in bytes.

Parameters:

context (_ContextLike) – The context for the calculation.

Returns:

The size of the chain.

Return type:

int

__type__() → type

Get the type of the tail structure in the chain.

Returns:

The type of the tail structure.

Return type:

type

__and__(other)

Concatenate another structure to the end of the chain.

Parameters:

other (_StructLike) – The structure to concatenate.

Returns:

The updated chain.

Return type:

Chain

__rand__(other)

Concatenate another structure to the beginning of the chain.

Parameters:

other (_StructLike) – The structure to concatenate.

Returns:

The updated chain.

Return type:

Chain

unpack_single(context)

Unpack a single data instance from the chain.

Parameters:

context (_ContextLike) – The context for the unpacking operation.

Returns:

A memory view representing the unpacked data.

Return type:

memoryview

pack_single(obj, context) → None

Pack a single data instance into the chain.

Parameters:

• obj (Any) – The data to pack into the chain.

• context (_ContextLike) – The context for the packing operation.

class caterpillar.fields.If(condition, depth=2)

If-statement implementation for class definitions.

Changed in version 2.4.5: Python 3.14 is not supported.

@struct
class Format:
    a: uint32

    with If(lambda _: GLOBAL_CONSTANT == 33):
        b: uint8

Note that this class will alter the used fields and cover multiple field definitions. In addition, the type annotation will be modified to display the condition as well.

Note

This class is not a struct, but a simple context manager.

class caterpillar.fields.ElseIf(condition, depth=2)

ElseIf-statement implementation for class definitions.

Changed in version 2.4.3: Python 3.14 is not supported.

@struct
class Format:
    a: uint32

    with this.a == 32:
        ...

    with ElseIf(this.a == 34):
        ...