Field Model#

class caterpillar.py.Field[source]#

Represents a field in a data structure.

amount: _ContextLambda | int | ellipsis | slice#: A constant or dynamic value to represent the amount of structs. Zero indicates there are no sequence types associated with this field.

arch: Arch#: The field’s architecture (inferred or explicitly specified).

bits: _ContextLambda | int | None#: The configured bits.

condition: _ContextLambda | bool#: Given optional execution this attribute should be used to return a boolean value that decides whether the value of this field should be set. Using // the condition can be set during class declaration.

default: Any | None#: The configured default value.

flags: Dict[int, Flag]#

Additional options that can be enabled using the logical OR operator |.

Note that there are default options that will be set automatically:

keep_position:
Persists the streams position after parsing data using the underlying struct. In relation to offset, this option will reset the stream to its original position if deactivated.
dynamic:
Specifies that this field does not store a constant size.
sequential:
An automatic flag that indicates this field stores a sequential struct.

get_offset(context: _ContextLike) → int[source]#: Returns the offset position of this field

get_struct(value: Any, context: _ContextLike) → _StructLike[source]#

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_type() → type[source]#

Returns the annotation type for this field

Returns:: the annotation type
Return type:: type

has_condition() → bool[source]#: Returns whether this field is linked to a condition

has_flag(flag: Flag) → bool[source]#

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

is_enabled(context: _ContextLike) → bool[source]#

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

is_seq() → bool[source]#

Returns whether this field is sequential.

Returns:: whether this field is sequental
Return type:: bool

length(context: _ContextLike) → int | ellipsis | slice[source]#

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]

offset: _ContextLambda | int#

Using the @ operator an offset can be assigned to a field. If set, the stream will be reset and set to the original position.

The minus one indicates that no offset has been associated with this field.

options: _Switch | Dict[Any, _StructLike] | None#: An extra attribute that stores additional options that can be translates as a switch statement.

order: ByteOrder#: An automatically inferred or explicitly specified byte order. Note that this attribute may have no impact on the underlying struct. The default byte order is SysNative.

struct: _StructLike | _ContextLambda#: Stores a reference to the actual parsing struct that will be used to parse or build our data. This attribute is never null.

class caterpillar.py.FieldMixin[source]#: A simple mixin to support operators used to create Field instances.

class caterpillar.py.FieldStruct[source]#

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

__bits__#: TBD

__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.

__pack__(obj: Any, context: _ContextLike) → None[source]#

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

Parameters:

obj (Any) – The data to pack.
context (_ContextLike) – The current operation context.

__repr__() → str[source]#

String representation of the FieldStruct instance.

Returns:: A string representation.

__unpack__(context: _ContextLike) → Any[source]#

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

Parameters:: context (_ContextLike) – The current operation context.
Returns:: The unpacked data.

pack_seq(seq: Iterable, context: _ContextLike) → None[source]#

Pack a sequence of elements using the provided context.

Parameters:

seq (Iterable) – The sequence of elements to pack.
context (_ContextLike) – The current operation context.

pack_single(obj: Any, context: _ContextLike) → None[source]#

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_seq(context: _ContextLike) → List[Any][source]#

Unpack a sequence of elements using the provided context.

Parameters:: context (_ContextLike) – The current operation context.
Returns:: The list of unpacked elements.

unpack_single(context: _ContextLike) → Any[source]#

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.

class caterpillar.py.Chain(initial: _StructLike, *structs: _StructLike)[source]#

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.

__and__(other: _StructLike) → Chain[source]#

Concatenate another structure to the end of the chain.

Parameters:: other (_StructLike) – The structure to concatenate.
Returns:: The updated chain.
Return type:: Chain

__init__(initial: _StructLike, *structs: _StructLike) → None[source]#

__rand__(other: _StructLike) → Chain[source]#

Concatenate another structure to the beginning of the chain.

Parameters:: other (_StructLike) – The structure to concatenate.
Returns:: The updated chain.
Return type:: Chain

__size__(context: _ContextLike) → int[source]#

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[source]#

Get the type of the tail structure in the chain.

Returns:: The type of the tail structure.
Return type:: type

property head: _StructLike#

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

Returns:: The head of the chain.
Return type:: _StructLike

pack_single(obj: Any, context: _ContextLike) → None[source]#

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.

property tail: _StructLike#

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

Returns:: The tail of the chain.
Return type:: _StructLike

unpack_single(context: _ContextLike) → memoryview[source]#

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

class caterpillar.py.If(condition: _ContextLambda | bool, depth=2)[source]#

If-statement implementation for class definitions.

@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.py.ElseIf(condition: _ContextLambda | bool, depth=2)[source]#

ElseIf-statement implementation for class definitions.

@struct
class Format:
    a: uint32

    with this.a == 32:
        ...

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