4.5.2. Struct#

4.5.2.1. The Struct class#

class caterpillar.model.Struct(model: type, order=None, arch=None, options=None, field_options=None, kw_only=False, hook_cls=None)[source]#

Represents a structured data model for serialization and deserialization.

Parameters:

  • model – The target class used as the base model.

  • order – Optional byte order for the fields in the structure.

  • arch – Global architecture definition (will be inferred on all fields).

  • options – Additional options specifying what to include in the final class.

4.5.2.2. Unions#

caterpillar.model.union(cls=None, /, *, options=None, order=None, arch=None, field_options=None, kw_only=False, hook_cls=None)[source]#

Decorator to create a Union class.

Parameters:

  • cls – The target class used as the base model.

  • options – Additional options specifying what to include in the final class.

  • order – Optional configuration value for the byte order of a field.

  • arch – Global architecture definition (will be inferred on all fields).

Returns:

The created Union class or a wrapper function if cls is not provided.

class caterpillar.model.UnionHook(struct_: Struct)[source]#

Implementation of a hook to simulate union types.

It will hook two methods of the target model type: __init__ and __setattr__. Because the constructor calls setattr for each attribute in the model, we have to intercept it before it gets called to set an internal status.

Internally, these two methods will be translated into __model_init__() and __model_setattr__(). Therefore, any class that implements these two methods can be used as a union hook.

struct: Struct#

The struct reference

max_size: int#

The static (cached) maximum size of the union

4.5.2.3. Standard Interface#

caterpillar.model.struct(cls=None, /, *, options=None, order=None, arch=None, field_options=None, kw_only=False)[source]#

Decorator to create a Struct class.

Parameters:

  • cls – The target class used as the base model.

  • options – Additional options specifying what to include in the final class.

  • order – Optional configuration value for the byte order of a field.

  • arch – Global architecture definition (will be inferred on all fields).

Returns:

The created Struct class or a wrapper function if cls is not provided.

caterpillar.model.pack(obj, struct=None, /, *, use_tempfile=False, as_field=False, **kwds) → bytes[source]#

Pack an object into a bytes buffer using the specified struct.

Parameters:

  • obj – The object to pack.

  • struct – The struct to use for packing.

  • kwds – Additional keyword arguments to pass to the pack function.

Returns:

The packed bytes.

caterpillar.model.pack_into(obj, buffer, struct=None, /, *, use_tempfile=False, as_field=False, **kwds) → None[source]#

Pack an object into the specified buffer using the specified struct.

This function serializes an object (obj) into a given buffer, using a struct to define how the object should be packed. Optionally, the function can handle temporary files for packing, use a Field wrapper around the struct, and support additional keyword arguments. The packed data is written to the buffer.

Example 1: Packing an object into a bytes buffer

>>> buffer = BytesIO()
>>> my_obj = SomeObject()  # Assume SomeObject is a valid object to be packed
>>> pack_into(my_obj, buffer, struct=SomeStruct())  # Using a specific struct
>>> buffer.getvalue()
b"..."

Example 2: Packing into a file-like stream (e.g., file)

>>> with open('packed_data.bin', 'wb') as f:
...     pack_into(my_obj, f, struct=SomeStruct())  # Pack into a file

Example 3: Using as_field to wrap the struct in a Field before packing

>>> buffer = BytesIO()
>>> pack_into(42, buffer, struct=uint8, as_field=True)
>>> buffer.getvalue()
b"\x2a"
Parameters:

  • obj – The object to pack (could be a plain object or a structure-like object).

  • buffer – The buffer to pack the object into (a writable stream such as BytesIO or a file).

  • struct – The struct to use for packing. If not specified, will infer from obj.

  • use_tempfile – Whether to use a temporary file for packing (experimental).

  • as_field – Whether to wrap the struct in a Field before packing.

  • kwds – Additional keyword arguments to pass to the pack function.

Raises:

TypeError – If no struct is specified and cannot be inferred from the object.

caterpillar.model.pack_file(obj, filename: str, struct=None, /, *, use_tempfile=False, as_field=False, **kwds) → None[source]#

Pack an object into a file using the specified struct.

Parameters:

  • obj – The object to pack.

  • filename – The name of the file to write to.

  • struct – The struct to use for packing.

  • kwds – Additional keyword arguments to pass to the pack function.

Returns:

None

caterpillar.model.unpack(struct, buffer, /, *, as_field=False, **kwds)[source]#

Unpack an object from a bytes buffer or stream using the specified struct.

This function takes a struct that defines how data should be unpacked, a buffer (either bytes or a stream) containing the serialized data, and returns the unpacked object. If as_field is set to True, the struct is wrapped by a Field. Additional keyword arguments are passed to the root context as attributes.

Example:

>>> buffer = b'\x00\x01\x02\x03'
>>> struct = SomeStruct()
>>> unpack(struct, buffer)
...
Parameters:

  • struct – The struct to use for unpacking (could be a SupportsUnpack or ContainsStruct object).

  • buffer – The bytes buffer or stream to unpack from.

  • as_field – Whether to wrap the struct in a Field transformer before unpacking.

  • kwds – Additional keyword arguments to pass to the unpack function.

Returns:

The unpacked object, which is the result of calling struct.__unpack__(context).

Raises:

TypeError – If the struct is not a valid struct instance.

caterpillar.model.unpack_file(struct, filename: str, /, *, as_field=False, **kwds)[source]#

Unpack an object from a file using the specified struct.

Parameters:

  • struct – The struct to use for unpacking.

  • filename – The name of the file to read from.

  • kwds – Additional keyword arguments to pass to the unpack function.

Returns:

The unpacked object.

caterpillar.model.sizeof(obj, **kwds) → int[source]#

Changed in version 2.5.0: Now checks if the provided object implements the _SupportsSize protocol