Common Structs#

Numeric Structs#

class caterpillar.py.FormatField(ch: str, type_: type)[source]#

A field class representing a binary format.

is_padding() → bool[source]#

Check if the field represents padding.

Returns:

True if the field is padding, False otherwise.

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

Pack a sequence of values into the stream.

Parameters:

  • seq – The sequence of values.

  • context – The current context.

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

Pack a single value into the stream.

Parameters:

  • obj – The value to pack.

  • stream – The output stream.

  • context – The current context.

text#

The format char (e.g. ‘x’, ‘i’, …)

ty#

The returned Python type

unpack_seq(context: _ContextLike) → List[Any][source]#

Unpack a sequence of values from the stream.

Parameters:

context – The current context.

Returns:

A list of unpacked values.

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

Unpack a single value from the stream.

Parameters:

context – The current context.

Returns:

The unpacked value.

py.uint8 = <FormatField(int) 'B' 8>#
py.int8 = <FormatField(int) 'b' 8>#
py.uint16 = <FormatField(int) 'H' 16>#
py.int16 = <FormatField(int) 'h' 16>#
py.uint32 = <FormatField(int) 'I' 32>#
py.int32 = <FormatField(int) 'i' 32>#
py.uint64 = <FormatField(int) 'Q' 64>#
py.int64 = <FormatField(int) 'q' 64>#
py.size_t = <FormatField(int) 'N' 64>#
py.ssize_t = <FormatField(int) 'n' 64>#
py.float16 = <FormatField(float) 'e' 16>#
py.float32 = <FormatField(float) 'f' 32>#
py.float64 = <FormatField(float) 'd' 64>#
py.void_ptr = <FormatField(int) 'P' 64>#
py.char = <FormatField(str) 'c' 8>#
py.boolean = <FormatField(bool) '?' 8>#
py.padding = <FormatField(padding) 'x' 8>#
class caterpillar.py.Int(bits: int, signed: bool = True)[source]#
pack_single(obj: int, 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_single(context: _ContextLike) → memoryview[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.UInt(bits: int)[source]#
py.vint = <VarInt>#
class caterpillar.py.VarInt[source]#

Variable-length integer struct.

This class implements variable-length unsigned integer for big-endian and little-endian encoding. The default behaviour uses big-endian encoding. It has an additional flag that can be configured globally or once per field.

VARINT_LSB specifies that the last significant byte will use a 1 to identify the end of the varint. Otherwise, zero will be used (which is the default setting). The following configurations are therefore possible:

>>> field = be + vint; print(pack(1024, field))
b'\x88\x00'
>>> field = be + vint | VARINT_LSB; print(pack(1024, field))
b'\x08\x80'
>>> field = le + vint; print(pack(1024, field))
b'\x80\x08'
>>> field = le + vint | VARINT_LSB; print(pack(1024, field))
b'\x00\x88'
pack_single(obj: int, context: _ContextLike) → None[source]#

Pack a single value into the stream.

Parameters:

  • obj – The value to pack.

  • context – The current context.

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

Unpack a single value from the stream.

Parameters:

  • stream – The input stream.

  • context – The current context.

Returns:

The unpacked value.

Bytes, Strings#

class caterpillar.py.Memory(length: int | _ContextLambda | ellipsis, encoding: str | None = None)[source]#
pack_single(obj: memoryview | bytes, context: _ContextLike) → None[source]#

Pack a single bytes object into the stream.

Parameters:

  • obj – The bytes object to pack.

  • context – The current context.

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

Unpack a single bytes object from the stream.

Parameters:

context – The current context.

Returns:

The unpacked bytes object.

class caterpillar.py.Bytes(length: int | _ContextLambda | ellipsis, encoding: str | None = None)[source]#

A specialized FieldStruct for handling byte sequences.

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

Unpack a single bytes object from the stream.

Parameters:

context – The current context.

Returns:

The unpacked bytes object.

class caterpillar.py.String(length: int | _ContextLambda | ellipsis, encoding: str | None = None)[source]#

A specialized field for handling string data.

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

Unpack a single string from the stream.

Parameters:

context – The current context.

Returns:

The unpacked string.

class caterpillar.py.Prefixed(prefix: _StructLike | None = None, encoding: str | None = None)[source]#
pack_single(obj: bytes, context: _ContextLike) → None[source]#

Pack a single bytes object into the stream.

Parameters:

  • obj – The bytes object to pack.

  • context – The current context.

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

Unpack a single bytes object from the stream.

Parameters:

context – The current context.

Returns:

The unpacked bytes object.

class caterpillar.py.CString(length: int | _ContextLambda | None = None, encoding: str | None = None, pad: str | int | None = None)[source]#

A specialized field for handling string data that ends with \0x00.

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

Pack a single string into the stream.

Parameters:

  • obj – The string to pack.

  • context – The current context.

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

Unpack a single string from the stream.

Parameters:

context – The current context.

Returns:

The unpacked string.

class caterpillar.py.ConstString(value: str, encoding: str | None = None)[source]#

A specialized constant field for handling string values.

Parameters:

  • value – The constant string value.

  • encoding – The encoding to use for string encoding (default is UTF-8).

class caterpillar.py.ConstBytes(value: bytes)[source]#

A specialized constant field for handling bytes values.

Parameters:

value – The constant bytes value.

Special Structs#

py.Pass = <Pass>#
class caterpillar.py.Computed(value: str | bytes | Any | _ContextLambda)[source]#
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_single(context: _ContextLike) → None[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.Transformer(struct: _StructLike)[source]#

A class that acts as a transformer for encoding and decoding data using a wrapped _StructLike object.

decode(parsed: Any, context: _ContextLike) → Any[source]#

Decode data using the wrapped _StructLike object.

Parameters:

  • parsed – The parsed data to be decoded.

  • context – The current context.

Returns:

The decoded data.

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

Encode data using the wrapped _StructLike object.

Parameters:

  • obj – The original data to be encoded.

  • context – The current context.

Returns:

The encoded data.

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

Pack a single value into the stream using encoding.

Parameters:

  • obj – The original data to be encoded and packed.

  • context – The current context.

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

Unpack a single value from the stream and decode it.

Parameters:

context – The current context.

Returns:

The decoded data.

class caterpillar.py.Enum(model: ~caterpillar.abc._EnumLike, struct: ~caterpillar.abc._StructLike, default: ~caterpillar.abc._EnumLike | None = <object object>)[source]#

A specialized Transformer for encoding and decoding enumeration values.

Parameters:

  • model – The enumeration model (an object with _member_map_ and _value2member_map_ attributes).

  • struct – The _StructLike object to be wrapped.

decode(parsed: Any, context: _ContextLike) → Any[source]#

Decode an integer value to its corresponding enumeration value.

Parameters:

  • parsed – The parsed integer value.

  • context – The current context.

Returns:

The corresponding enumeration value.

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

Encode an enumeration value.

Parameters:

  • obj – The original enumeration value.

  • context – The current context.

Returns:

The encoded value (integer).

Raises:

ValidationError – If the input is not an enumeration type.

class caterpillar.py.Const(value: str | bytes | Any, struct: _StructLike)[source]#

A specialized Transformer that enforces a constant value during encoding and decoding.

Parameters:

  • value – The constant value to be enforced during encoding and decoding.

  • struct – The _StructLike object to be wrapped.

decode(parsed: Any, context: _ContextLike) → Any[source]#

Decode data and ensure it matches the constant value.

Parameters:

  • parsed – The parsed data to be decoded.

  • context – The current context.

Returns:

The constant value.

Raises:

ValidationError – If the parsed value does not match the constant value.

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

Encode data using the constant value.

Parameters:

  • obj – The original data to be encoded (ignored).

  • context – The current context.

Returns:

The constant value.