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__(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:

• 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

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