4.5.3. Bitfield#

Changed in version 2.5.0: New revised concept since v2.5.0.

4.5.3.1. Main Interface#

class caterpillar.model.Bitfield(model, order=None, arch=None, options=None, field_options=None, alignment=None)[source]#

A Bitfield represents a packed structure composed of bit-level fields. This class allows for the declarative definition of compact memory representations where each field can occupy an arbitrary number of bits, not necessarily aligned to byte boundaries.

Core Implementation: - Bitfields are organized into BitfieldGroups, which manage alignment and field aggregation. - Entries can be individual bit widths or wrapped fields with explicit alignment. - Special field options like NewGroup and EndGroup can control group layout. - Supports value factories for type conversion and symbolic runtime actions.

Available global options: - B_NO_AUTO_BOOL: disables automatically converting 1bit fields to boolean - B_GROUP_KEEP: disables finalizing groups when using the alignment definition syntax

Parameters:

  • model (Any) – The model for the structure.

  • order (Optional[str]) – Byte order of the structure.

  • arch (Optional[str]) – Target architecture.

  • options (Optional[set]) – Global structure options.

  • field_options (Optional[set]) – Field-specific options.

  • alignment (Optional[int]) – Bit alignment size.

Changed in version 2.5.0: Updated concept. See the _reference_ for more information.

add_action(action) → None[source]#

Add an action to the struct.

Parameters:

action – The action to add.

class caterpillar.model.BitfieldGroup(bit_count: int)[source]#

A group of one or more bitfield entries. Groups are used to organize fields within a single alignment unit and may represent either packed fields or standalone fields.

Parameters:

bit_count (int) – The number of bits in the group, or -1 for single field representation.

Changed in version 2.5.0: Renamed from BitFieldGroup to BitfieldGroup

is_field() → bool[source]#

Determine whether the group contains a single non-bitfield field.

Returns:

True if the group holds a single struct-like field.

Return type:

bool

get_field()[source]#

Get the single field from this group.

Returns:

The field object.

Return type:

BitfieldEntry

set_field(field)[source]#

Set the group to hold only the given field and mark it as a standalone field group.

Parameters:

field (BitfieldEntry) – The field to store in this group.

align_to(alignment: int)[source]#

Align the bit count of this group to the specified boundary.

Parameters:

alignment (int) – The number of bits to align to.

is_empty() → bool[source]#

Check if the group contains any entries.

Returns:

True if the group is empty.

Return type:

bool

get_size(context=None)[source]#

Get the size of this group in bytes.

Parameters:

context (Any) – Optional context used for size evaluation.

Returns:

The size of the group in bytes.

Return type:

int

get_bits(context=None)[source]#

Get the total number of bits in this group.

Parameters:

context (Any) – Optional context used for size evaluation.

Returns:

The number of bits.

Return type:

int

class caterpillar.model.BitfieldEntry(bit: int, width: int, name: str, factory=None, action=None)[source]#

Represents a single entry in a bitfield, including its bit position, width, name, and conversion behavior.

May also represent a special action or directive instead of a field.

Parameters:

  • bit (int) – The starting bit position within its group.

  • width (int) – The number of bits used by this field.

  • name (str) – The name of the field.

  • factory (type or BitfieldValueFactory or None) – A factory for type conversion. Defaults to BitfieldValueFactory.

  • action (Any) – Optional action object for special handling (e.g., alignment or padding).

Added in version 2.5.0.

static new_action(action)[source]#

Create a new action-type entry (e.g., padding, control directive).

Parameters:

action (Any) – The action object to encapsulate.

Returns:

A BitfieldEntry instance with no bit-width, used for meta instructions.

Return type:

BitfieldEntry

shift(value_width: int) → int[source]#

Calculate how much to shift the field when extracting it from a value.

Parameters:

value_width (int) – The total bit width of the container.

Returns:

The number of bits to shift.

Return type:

int

is_action() → bool[source]#

Check whether this entry is an action (i.e., not a data field).

Returns:

True if this is an action entry.

Return type:

bool

caterpillar.model.getbits(obj) → int[source]#

Retrieve the bit-width of a given object.

This function checks for a __bits__() attribute on the object. The object must either implement the _SupportsBits or _ContainsBits protocol.

>>> class A:
...     __bits__ = 3
...
>>> a = A()
>>> getbits(a)
3
Parameters:

obj (Any) – The object for which the bit-width should be determined. It is expected to have an ATTR_BITS attribute.

Returns:

The number of bits used by the object.

Return type:

int

Raises:

AttributeError – If the object does not have an attribute defined by ATTR_BITS.

caterpillar.model.issigned(obj) → bool[source]#

Determine whether a given object represents a signed field.

Parameters:

obj (Any) – The object for which signedness should be determined.

Returns:

True if the field is marked as signed, False otherwise.

Return type:

bool

caterpillar.model.bitfield(cls=None, /, *, options=None, order=None, arch=None, field_options=None, alignment=None)[source]#

Decorator that transforms a class definition into a Bitfield structure.

This decorator enables defining bitfields using simple class syntax, with support for custom alignment, ordering, architecture, and field options.

Parameters:

  • cls (Optional[type]) – The user-defined class to transform.

  • options (Optional[set]) – A set of global or structure-specific options.

  • order (Optional[str]) – Optional byte order for serialization (e.g., ‘little’ or ‘big’).

  • arch (Optional[str]) – Optional architecture string (e.g., ‘x86’, ‘arm’).

  • field_options (Optional[set]) – Optional default options for fields.

  • alignment (Optional[int]) – Optional alignment in bits.

Returns:

The decorated class, enhanced as a Bitfield structure.

Return type:

type

from caterpillar.py import bitfield, SetAlignment, uint16

@bitfield
class Packet:
    version   : 3
    type      : (5, SetAlignment(16))
    length    : 10
    _         : 0  # align to 16bits
    payload   : uint16

# You can now pack/unpack Packet instances as compact binary bitfields
pkt = Packet(version=1, type=2, length=128, payload=0xABCD)
packed = pack(pkt)
unpacked = unpack(Packet, packed)

Changed in version 2.5.0: Added the alignment parameter.

4.5.3.2. Default Factory Classes#

class caterpillar.model.BitfieldValueFactory(target=None)[source]#

A generic factory class responsible for converting values between Python objects and integers for use in bitfield entries.

By default, the factory converts to and from Python’s built-in int type, but it can be customized to support any type that accepts an integer in its constructor and implements __int__.

Parameters:

target (type, optional) – The target type to which integer values will be converted., defaults to None

Added in version 2.5.0.

to_int(obj) → int[source]#

Convert a Python object to an integer.

Parameters:

obj (Any) – The object to convert.

Returns:

The integer representation of the object.

Return type:

int

from_int(value: int)[source]#

Convert an integer to the target object type.

Parameters:

value (int) – The integer to convert.

Returns:

The value converted to the target type.

Return type:

Any

class caterpillar.model.CharFactory[source]#

A value factory for handling single ASCII/Unicode characters as integers.

This factory allows treating a character field as a one-byte integer and vice versa, automatically converting during packing and unpacking.

Added in version 2.5.0.

from_int(value: int)[source]#

Convert an integer to its character representation.

Parameters:

value (int) – Integer ASCII or Unicode code point.

Returns:

Corresponding character.

Return type:

str

to_int(obj) → int[source]#

Convert a character to its integer (ordinal) representation.

Parameters:

obj (str) – The character to convert.

Returns:

Corresponding integer value.

Return type:

int

class caterpillar.model.EnumFactory(model, strict=False)[source]#

A value factory for enum-like types used in bitfields.

This factory attempts to convert between integers and enumeration instances, using the provided model (which should support __int__). It can operate in strict or lenient mode:

  • In strict mode, a ValueError is raised if conversion fails.

  • In lenient mode, the raw integer is returned if the value is not in the enum.

Parameters:

  • model (Type) – The enum model or mapping type to use.

  • strict (bool) – Whether to raise an error on unknown values.

Example#
class Status(enum.IntEnum):
    OK = 0
    ERROR = 1

factory = EnumFactory(Status, strict=True)
factory.from_int(0)  # -> Status.OK
factory.from_int(2)  # -> ValueError (strict mode)

Added in version 2.5.0.

from_int(value: int)[source]#

Convert an integer into an enum instance or raw int.

Parameters:

value (int) – The integer to convert.

Returns:

Enum instance or raw int if not found (in non-strict mode).

Return type:

Any

Raises:

ValueError – If strict is enabled and value is not valid.

4.5.3.3. Default Options#

caterpillar.model.EndGroup#

Added in version 2.5.0.

Alias for the B_GROUP_NEW flag, used to indicate that a new bitfield group should be started.

caterpillar.model.NewGroup#

Alias for the B_GROUP_END flag, used to indicate that the current bitfield group should be finalized.

class caterpillar.model.SetAlignment(new_alignment: int)[source]#

Instructional flag used to update the current bitfield alignment dynamically during bitfield generation.

This class allows to explicitly set a new alignment boundary (in bits) for subsequent fields or groups in a bitfield definition. This enables finer control over how bitfield groups are organized and aligned.

Parameters:

new_alignment (int) – The alignment size in bits to be used from this point forward in the bitfield layout.

static flag(new_alignment: int)[source]#

Create a Flag instance representing a request to set a new alignment.

This method is intended for use where a generic Flag is expected rather than a full SetAlignment object, e.g. for setting options for a Field.

>>> field = 5 - uint32 | SetAlignment.flag(32)
Parameters:

new_alignment (int) – The alignment size in bits.

Returns:

A Flag object with the key “bitfield.new_alignment” and the specified alignment as its value.

Return type:

Flag