4.1. Byteorder and Architecture#

4.1.1. Byteorder#

class caterpillar.byteorder.ByteOrder(name: str, ch: str, alignment: Alignment = Alignment.NONE, size: Size = Size.STANDARD)[source]#

Represents byte order information, including alignment and size.

Parameters:

  • name – A string representing the name of the byte order.

  • ch – A string representing the character used to specify the byte order in struct format strings.

  • alignment – An enumeration representing the alignment (default is Alignment.NONE).

  • size – An enumeration representing the size (default is Size.STANDARD).

class Alignment(*values)[source]#
class Size(*values)[source]#
apply(other: object) → None[source]#

Applies the byte order information to another object.

Parameters:

other – The object to which the byte order information should be applied.

class caterpillar.byteorder.DynByteOrder(name: str | None = None, key: str | _ContextLambda[str | _EndianLike | bool] | None = None, func: Callable[[], _EndianLike] | _ContextLambda[_EndianLike] | None = None, init_ch: str | None = None)[source]#

Represents a dynamic byte order resolved at runtime.

A dynamic byte order defers endian resolution until pack or unpack execution. Resolution may depend on the active context, a field value, or a user-provided callable.

Supported concepts:

  • Root context resolution using CTX_ORDER

  • Context key lookup using a string or callable

  • Runtime resolution using a function

  • Per-field byte order overrides using addition syntax

Using the root context byte order:

@struct(order=Dynamic)
class Format:
    a: uint16
    b: uint32

pack(obj, **{CTX_ORDER: BigEndian})

Using a context key:

@struct(order=Dynamic(this.spec))
class Format:
    spec: uint8
    a: uint16

Using a function:

def func():
    return BigEndian

@struct(order=DynByteOrder(func=func))
class Format:
    a: uint16

Using a per-field dynamic byte order:

a: Dynamic(this.spec) + uint16
Parameters:

  • name (str, optional) – Human readable name for the byte order, defaults to None

  • key (str or callable, optional) – Context key or callable used to resolve byte order, defaults to None

  • func (callable, optional) – Callable returning an object with a ch attribute, defaults to None

  • init_ch (str, optional) – Initial format character, defaults to None

getch(context: _ContextLike) → str[source]#

Resolve the byte order format character from a context.

Resolution order:

  1. Function result, with or without context

  2. Context key lookup

  3. Root context CTX_ORDER value

  4. Boolean or string fallback

Resolution prioritizes a callable, then a context key, and finally a root context fallback with default behavior. :param context: Context providing byte order information :type context: object :return: Struct format character representing byte order :rtype: str

property ch: str#

Return the active byte order character.

The value may change dynamically by inspecting the caller frame and extracting a local variable named context.

Returns:

Struct format character for byte order

Return type:

str

caterpillar.byteorder.byteorder(obj: object, default: _EndianLike | None = None) → _EndianLike[source]#

Get the byte order of an object, defaulting to SysNative if not explicitly set.

Parameters:

obj – The object to retrieve the byte order from.

Returns:

The byte order of the object.

caterpillar.byteorder.byteorder_is_little(obj: object) → bool[source]#

Check if the byte order of an object is little-endian.

4.1.1.1. Standard Byteorder Instances#

caterpillar.byteorder.Native: Final[ByteOrder] = ByteOrder(name='Native', ch='=', alignment=<Alignment.NONE: 0>, size=<Size.STANDARD: 0>)#

Predefined ByteOrder instance representing native platform byte order.

caterpillar.byteorder.BigEndian: Final[ByteOrder] = ByteOrder(name='Big Endian', ch='>', alignment=<Alignment.NONE: 0>, size=<Size.STANDARD: 0>)#

Predefined ByteOrder instance representing big-endian byte order.

caterpillar.byteorder.LittleEndian: Final[ByteOrder] = ByteOrder(name='Little Endian', ch='<', alignment=<Alignment.NONE: 0>, size=<Size.STANDARD: 0>)#

Predefined ByteOrder instance representing little-endian byte order.

caterpillar.byteorder.NetEndian: Final[ByteOrder] = ByteOrder(name='Network', ch='!', alignment=<Alignment.NONE: 0>, size=<Size.STANDARD: 0>)#

Predefined ByteOrder instance representing network byte order.

caterpillar.byteorder.SysNative: Final[ByteOrder] = ByteOrder(name='SysNative', ch='@', alignment=<Alignment.NATIVE: 1>, size=<Size.NATIVE: 1>)#

Predefined ByteOrder instance representing system-native byte order with native alignment and size rules.

caterpillar.byteorder.Dynamic: Final[DynByteOrder] = <DynByteOrder little=True>#

Predefined DynByteOrder instance for runtime-determined byte order.

caterpillar.byteorder.LITTLE_ENDIAN_FMT: Final[str] = '<'#

Struct format character representing little-endian byte order.

caterpillar.byteorder.O_DEFAULT_ENDIAN: Final[Flag[_EndianLike]] = Flag(name='option.endian', value=None)#

Default flag option representing an unspecified byte order.

4.1.2. Architecture#

class caterpillar.byteorder.Arch(name: str, ptr_size: int)[source]#

Represents a system architecture with a name and an indication of whether it is 64-bit.

Parameters:

  • name – The name of the architecture.

  • ptr_size – the amount of bits one pointer takes

byteorder.system_arch: Final[Arch] = Arch(name='x86_64', ptr_size=64)#

4.1.2.1. Standard Architectures#

byteorder.x86: Final[Arch] = Arch(name='x86', ptr_size=32)#
byteorder.x86_64: Final[Arch] = Arch(name='x86-64', ptr_size=64)#
byteorder.ARM: Final[Arch] = Arch(name='ARM', ptr_size=32)#
byteorder.ARM64: Final[Arch] = Arch(name='ARM64', ptr_size=64)#
byteorder.AARCH64: Final[Arch] = Arch(name='ARM64', ptr_size=64)#
byteorder.PowerPC: Final[Arch] = Arch(name='PowerPC', ptr_size=32)#
byteorder.PowerPC64: Final[Arch] = Arch(name='PowerPC64', ptr_size=64)#
byteorder.MIPS: Final[Arch] = Arch(name='MIPS', ptr_size=32)#
byteorder.MIPS64: Final[Arch] = Arch(name='MIPS64', ptr_size=64)#
byteorder.SPARC: Final[Arch] = Arch(name='SPARC', ptr_size=32)#
byteorder.SPARC64: Final[Arch] = Arch(name='SPARC64', ptr_size=64)#
byteorder.RISC_V64: Final[Arch] = Arch(name='RISK-V64', ptr_size=64)#
byteorder.RISC_V: Final[Arch] = Arch(name='RISK-V', ptr_size=32)#
byteorder.AMD: Final[Arch] = Arch(name='AMD', ptr_size=32)#
byteorder.AMD64: Final[Arch] = Arch(name='AMD64', ptr_size=64)#