BaseStruct

BaseStruct

Base class for defining a binary serialization schema in the form of a struct using Retrievers with optional support for compression and versioning allowing for conditional serialization

ver instance-attribute

ver: Version

The version of the struct

__new__

__new__(*args, ver: Version = Version(-1), ctx: Context = Context(), init_defaults: bool = True, **retriever_inits: Any) -> Self

Default initialise and create a new instance of this struct

Parameters:

• args –

  generic args receiver

• ver (Version, default: Version(-1) ) –

  The struct version to create

• ctx (Context, default: Context() ) –

  Stores ctx key/values used by on_read/on_write combinators

• init_defaults (bool, default: True ) –

  If set to false, skip initialisation of struct values from defaults. This is only useful when the values are filled in from another source during deserialization

• **retriever_inits (Any, default: {} ) –

  Specify overrides for the default values of retrievers for initialisation by name

__reconstruct__

__reconstruct__()

An initialization method that is called when externally loaded structs are accessed for the first time, since init is skipped.

This method is not called when structs are created directly by code. If required, init should call

this function.

from_stream classmethod

from_stream(stream: ByteStream, ver: Version = Version(0)) -> Self

Deserialize and create an instance of this struct from a ByteStream according to the specified version

Parameters:

• stream (ByteStream) –

  The stream to use for deserialization

• ver (Version, default: Version(0) ) –

  The version of the struct being deserialized

Returns:

• Self –

  An instance of this struct

Raises:

• CompressionError –

  If the _decompress method is not defined and remaining_compressed is set to True in one of the retrievers

to_bytes

to_bytes() -> bytes

Serialize this struct to bytes

Returns:

• bytes –

  The byte representation of this struct

Raises:

• CompressionError –

  If the _compress method is not defined and remaining_compressed is set to True in one of the retrievers

from_base classmethod

from_base(value: BaseStruct) -> Self

Aliases the data in the base class without copying it.

Parameters:

• value (BaseStruct) –

  The base struct instance to alias

Returns:

• Self –

  An instance of this struct

from_bytes classmethod

from_bytes(bytes_: bytes) -> Self

Deserialize and create an instance of this struct from bytes

Parameters:

• bytes_ (bytes) –

  The bytes to use for deserialization

Returns:

• Self –

  An instance of this struct

Raises:

• CompressionError –

  If the _decompress method is not defined and remaining_compressed is set to True in one of the retrievers

from_file classmethod

from_file(filepath: str, strict: bool = True) -> Self

Deserialize and create an instance of this struct from the given file

Parameters:

• filepath (str) –

  The file to use for deserialization

• strict (bool, default: True ) –

  Raise an error if the complete file is not consumed after deserialization is complete

Returns:

• Self –

  An instance of this struct

Raises:

• ParsingError –

  When strict is set to True and the complete file is not consumed after deserialization

• CompressionError –

  If the _decompress method is not defined and remaining_compressed is set to True in one of the retrievers

to_file

to_file(filepath: str)

Serialize this struct to the given file

Parameters:

• filepath (str) –

  The path to write the serialized file to

Raises:

• CompressionError –

  If the _compress method is not defined and remaining_compressed is set to True in one of the retrievers

from_json classmethod

from_json(filepath: str) -> Self

Deserialize and create an instance of this struct from the given JSON file

Parameters:

• filepath (str) –

  The file to use for deserialization

Returns:

• Self –

  An instance of this struct

Raises:

• ValueError –

  For JSONs which do not comply with the BaseStruct schema

to_json

to_json(filepath: str)

Serialize this struct to the given file in JSON.

Parameters:

• filepath (str) –

  The path to write the serialized file to

_get_version classmethod

_get_version(stream: ByteStream, ver: Version = Version(0)) -> Version

Called before deserialization begins. Used to determine the version of the struct

Parameters:

• stream (ByteStream) –

  The ByteStream to use for determining the version

• ver (Version, default: Version(0) ) –

  The version of the parent struct (if any)

Returns:

• Version –

  The version to use for versioning this struct

_compress classmethod

_compress(bytes_: bytes) -> bytes

Used to compress all the bytes of the properties following a retriever with remaining_compressed set to True during serialization

Parameters:

• bytes_ (bytes) –

  The bytes to compress

Returns:

• bytes –

  The compressed bytes

_decompress classmethod

_decompress(bytes_: bytes) -> bytes

Used to decompress all the bytes of the properties following a retriever with remaining_compressed set to True during deserialization

Parameters:

• bytes_ (bytes) –

  The bytes to decompress

Returns:

• bytes –

  The decompressed bytes