binobj.structures module

Classes defining structures and unions.

class Struct(**values: Any)

Bases: object

An ordered collection of fields and other structures.

Changed in version 0.5.0: A Struct will compare equal to UNDEFINED if and only if all of its fields are also undefined.

Changed in version 0.7.1: Removed the private-ish __components__ and __validators__ attributes. Field definitions, validators, and other metadata can be found in the new __binobj_struct__ class attribute. However, it should be considered an implementation detail and is subject to change.

Changed in version 0.10.0: The __objclass__ attribute is set on all fields.

classmethod from_bytes(data: bytes, context: Any | None = None, exact: bool = True, init_kwargs: Mapping[str, Any] | None = None) → TStruct

Load a struct from the given byte string.

Parameters:

  • data (bytes) – A bytes-like object to get the data from.

  • context – Additional data to pass to this method. Subclasses must ignore anything they don’t recognize.

  • exact (bool) – data must contain exactly the number of bytes required. If not all the bytes in data were used when reading the struct, throw an exception.

  • init_kwargs (dict) – Additional keyword arguments to pass to the struct’s constructor, for subclasses that take additional arguments beyond the fields that comprise the struct. You can also use this to override field values; anything given in here takes precedence over loaded values.

Returns:

The loaded struct.

Raises:

ExtraneousDataError – exact is True and there’s data left over at the end of the byte string.

New in version 0.7.0: The init_kwargs argument.

classmethod from_stream(stream: BinaryIO, context: Any | None = None, init_kwargs: Mapping[str, Any] | None = None) → TStruct

Load a struct from the given stream.

Parameters:

  • stream (BinaryIO) – The stream to load data from.

  • context – Additional data to pass to the components’ from_stream() methods. Subclasses must ignore anything they don’t recognize.

  • init_kwargs (dict) – Additional keyword arguments to pass to the struct’s constructor, for subclasses that take additional arguments beyond the fields that comprise the struct. You can also use this to override field values; anything given in here takes precedence over loaded values.

Returns:

The loaded struct.

New in version 0.7.0: The init_kwargs argument.

classmethod get_field(stream: BinaryIO, name: str, context: Any | None = None) → Any

Return the value of a single field.

If the field is at a fixed byte offset from the beginning of the struct, it’ll be read directly.

If the field isn’t at a fixed offset from the beginning of the struct (e.g. a variable-length field occurs before it) then the entire struct up to and including this field must be read. Unfortunately, this means that unrelated validation errors can be thrown if other fields have problems.

Parameters:

  • stream (BinaryIO) – The stream to read from. It’s assumed that the stream pointer is positioned at the start of a struct. The stream pointer is returned to its original position even if an exception occurred.

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

  • context – Optional. Any object containing extra information to pass to the from_stream() method of the field. For fields located at a variable offset, this will be passed to the from_stream() method of each field read.

Returns:

The value of the field in the struct data.

Raises:

UnexpectedEOFError – The end of the stream was reached before the requested field could be completely read.

classmethod get_size() → int | None

Return the size of this struct in bytes, if possible.

If there are variable-sized fields that can’t be resolved, this function returns None instead.

Do not use this on instances; use len(instance) instead.

Returns:

The struct’s size, in bytes.

Return type:

int

New in version 0.3.0.

partial_dump(stream: BinaryIO, last_field: str | None = None, context: Any | None = None) → None

Partially dump the object, up to and including the last named field.

All fields up to and including the field named in last_field will be serialized.

If last_field isn’t given, as many fields will be serialized as possible up to the first missing one.

Parameters:

  • stream (BinaryIO) – The stream to dump into.

  • last_field (str) – The name of the last field in the object to dump.

  • context – Any object containing extra information to pass to the fields’ from_stream() methods.

classmethod partial_load(stream: BinaryIO, last_field: str | None = None, context: Any | None = None) → TStruct

Partially load this object, either until EOF or the named field.

All fields up to and including the field named in last_field will be loaded from stream.

If last_field isn’t given, as many complete fields as possible will be loaded from stream. Any partially loaded fields will be discarded and the stream pointer will be reset to the end of the last complete field read.

Note

Because the struct is only partially loaded, struct-level validators are not executed. Individual fields still are.

Parameters:

  • stream (BinaryIO) – The stream to load from.

  • last_field (str) – The name of the last field to load in the object. If given, enough bytes for this and all previous fields must be present in the stream.

  • context – Any object containing extra information to pass to the fields’ from_stream() method.

Returns:

The loaded struct.

to_bytes(context: Any | None = None) → bytes

Convert the given data into bytes.

Parameters:

context – Additional data to pass to this method. Subclasses must ignore anything they don’t recognize.

Returns:

The serialized data.

Return type:

bytes

to_dict(keep_discardable: bool = False) → Dict[str, Any]

Convert this struct into an ordered dictionary.

The primary use for this method is converting a loaded Struct into native Python types. As such, validation is not performed since that was done while loading.

Parameters:

keep_discardable (bool) – If True, don’t exclude fields marked with discard=True from the result.

Return type:

Dict[str, Any]

Raises:

MissingRequiredValueError – One or more fields don’t have assigned values.

Changed in version 0.3.0: This now recursively calls to_dict() on all nested structs and arrays so that the returned dictionary is completely converted, not just the first level.

Changed in version 0.6.0: Fields with discard set are not included in the returned dict by default.

Changed in version 0.6.1: The keep_discardable argument was added.

to_stream(stream: BinaryIO, context: Any | None = None) → None

Convert the given data into bytes and write it to stream.

Parameters:

  • stream (BinaryIO) – The stream to write the serialized data into.

  • context – Additional data to pass to this method. Subclasses must ignore anything they don’t recognize.

validate_contents() → None

Validate the stored values in this struct.

Raises:

ValidationError – Validation failed.

New in version 0.4.0.