Serialization

This module implements the main interface for saving and loading HermesPy’s runtime objects to and from disk.

All Serializable classes within the hermespy namespace are detected automatically by the Factory managing the serialization process. As a result, dumping any Serializable object state to a file is as simple as

# Initialize a new serialization process
factory = Factory()
process = factory.serialize('file')

# Serialize the object
process.serialize_object(serializable_object, 'identifier')

# Close the serialization process
process.finalize()

and can be loaded again just as easily via

# Initialize a new deserialization process
factory = Factory()
process = factory.deserialize('file')

# Deserialize the object
deserialized_object = process.deserialize_object('identifier', SerializableType)

# Close the deserialization process
process.finalize()

from any context. By default, the objects will be serialized in the HDF format, which is currently the only supported format for serialization. Future versions of HermesPy may support additional serialization formats such as Matlab or JSON.

class Serializable

Bases: object

Base class for serializable classes.

Only classes inheriting from Serializable will be serialized by the factory.

abstract classmethod Deserialize(process)

Deserialize an object’s state.

Objects cannot be deserialized directly, instead a Factory must be instructed to carry out the deserialization process.

Parameters:

process (DeserializationProcess) – The current stage of the deserialization process. This object is generated by the Factory and provides an interface to deserialization methods supporting multiple backends.

Return type:

TypeVar(SerializableType, bound= Serializable)

Returns:

The deserialized object.

classmethod serialization_tag()

Tag used to identify the respective class during serialization.

Returns: The serialization tag.

Return type:

str

abstract serialize(process)

Serialize this object’s state.

Objects cannot be serialized directly, instead a Factory must be instructed to carry out the serialization process.

Parameters:

process (SerializationProcess) – The current stage of the serialization process. This object is generated by the Factory and provides an interface to serialization methods supporting multiple backends.

Return type:

None

class SerializableEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Serializable, Enum

Base class for serializable enumerations.

classmethod Deserialize(process)

Deserialize an object’s state.

Objects cannot be deserialized directly, instead a Factory must be instructed to carry out the deserialization process.

Parameters:

process (DeserializationProcess) – The current stage of the deserialization process. This object is generated by the Factory and provides an interface to deserialization methods supporting multiple backends.

Return type:

TypeVar(SET, bound= SerializableEnum)

Returns:

The deserialized object.

classmethod from_parameters(enum)

Initialize enumeration from multiple parameters.

Parameters:

enum (Union[TypeVar(SET, bound= SerializableEnum), int, str]) – The parameter from which the enum should be initialized.

Return type:

TypeVar(SET, bound= SerializableEnum)

Returns: The initialized enumeration.

serialize(process)

Serialize this object’s state.

Objects cannot be serialized directly, instead a Factory must be instructed to carry out the serialization process.

Parameters:

process (SerializationProcess) – The current stage of the serialization process. This object is generated by the Factory and provides an interface to serialization methods supporting multiple backends.

Return type:

None

class Factory

Bases: object

Helper class to serialize Hermespy’s runtime objects.

deserialize(target, campaign=None, backend=SerializationBackend.HDF)

Deserialize an object from a file.

Parameters:

• target (str) – Path to the target file.

• campaign (str | None) – Name of the serialization campaign. Can be set to store multiple related serializations within the same file.

• backend (SerializationBackend) – Serialization backend to be used. Defaults to SerializationBackend.HDF.

Return type:

DeserializationProcess

Returns: The deserialized object.

from_HDF(target, type)

Load a runtime object from a single HDF5 file or HDF5 file-like object.

Parameters:

target (str | Group) – Path to the configuration file or HDF5 file-like object.

Returns:

The deserialized object.

Return type:

Serializable

Raises:

RuntimeError – If the object is not a registered class.

serialize(target, campaign=None, backend=SerializationBackend.HDF)

Serialize an object to a file.

Parameters:

target (str) –

Path to the target file.

campaign:

Name of the serialization campaign. Can be set to store multiple related serializations within the same file.

backend:

Serialization backend to be used. Defaults to SerializationBackend.HDF.

Return type:

SerializationProcess

to_HDF(target, serializable)

Dump a runtime object to a single HDF5 file or HDF5 file-like object.

Parameters:

• target (str | Group) – Path to the configuration file or HDF5 file-like object.

• serializable (Serializable) – Object to be serialized.

Raises:

RuntimeError – If objects in *args are unregistered classes or not serializable.

Return type:

None

property registered_classes: ValuesView[Type[Serializable]]

Classes registered for serialization within the factory.

property registered_tags: KeysView[str]

Read registered serialization tags.

property tag_registry: Mapping[str, Type[Serializable]]

Read registered serialization tags.

class ProcessBase(tag_registry)

Bases: ABC

Common base class for serialization and deserialization processes.

class SerializationProcess(tag_registry)

Bases: ProcessBase

Base class for all serialization processes.

finalize()

Finalize the serialization process.

After finalization, the serialization process is considered complete and no further serialization is possible. Closes any open file handles and releases any resources reserved used during the serialization process.

Return type:

None

abstract serialize_array(array, name, cache=True)

Serialize a numpy array.

Warning

Arrays to be serialized should be immutable during the serialization process. This is to ensure that the array’s memory address remains constant and can be used as a unique identifier. If this can’t be guaranteed, caching for the respective array should be disabled.

Parameters:

• array (ndarray) – The numpy array to be serialized.

• name (str) – Name of the dataset.

• cache (bool) – Cache the array for future reference. Defaults to True.

Return type:

None

abstract serialize_complex(value, name)

Serialize a complex value.

Parameters:

• value (complex) – The complex value to be serialized.

• name (str) – Name of the dataset.

Return type:

None

abstract serialize_custom(name, serializer)

Serialize anything using a custom function.

Parameters:

• name (str) – Name of the dataset.

• serializer (Callable[[SerializationProcess], None]) – Serialization function to be executed.

Return type:

None

abstract serialize_floating(value, name)

Serialize a floating point value.

Parameters:

• value (float) – The floating point value to be serialized.

• name (str) – Name of the dataset.

Return type:

None

abstract serialize_integer(value, name)

Serialize an integer value.

Parameters:

• value (int) – The integer value to be serialized.

• name (str) – Name of the dataset.

Return type:

None

serialize_object(obj, name, root=False)

Serialize an object.

Parameters:

• obj (Serializable) – The object to be serialized.

• name (str) – Name of the dataset.

• root (bool) – Serialize the object as a root object. Defaults to False.

Raises:

RuntimeError – If the object is not a registered class.

Return type:

None

serialize_object_mapping(objects, name, append=True, root=False)

Serialize a mapping of string keys to objects.

Parameters:

• objects (Mapping[str, Serializable]) – The mapping of objects to be serialized.

• name (str) – Name of the dataset.

• append (bool) – Append the objects to the dataset if it already exists. Defaults to True.

Return type:

None

serialize_object_sequence(objects, name, append=False, root=False)

Serialize a sequence of objects.

Parameters:

• objects (Sequence[Serializable]) – The sequence of objects to be serialized.

• name (str) – Name of the dataset.

• append (bool) – Append the objects to the dataset if it already exists. Defaults to False.

Return type:

None

serialize_range(value, name)

Return type:

None

abstract serialize_string(value, name)

Serialize a string value.

Parameters:

• value (str) – The string value to be serialized.

• name (str) – Name of the dataset.

Return type:

None

class DeserializationProcess(tag_registry)

Bases: ProcessBase

Base class for all deserialization processes.

abstract deserialize_array(name, dtype, default='UNDEFINED')

Deserialize a numpy array.

Parameters:

• name (str) – Name of the dataset.

• dtype (Union[dtype[Any], None, type[Any], _SupportsDType[dtype[Any]], str, tuple[Any, int], tuple[Any, Union[SupportsIndex, Sequence[SupportsIndex]]], list[Any], _DTypeDict, tuple[Any, Any]]) – Expected data type of the array.

• default (Union[ndarray, Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized numpy array.

Return type:

numpy.ndarray

abstract deserialize_complex(name, default='UNDEFINED')

Deserialize a complex value.

Parameters:

• name (str) – Name of the dataset.

• default (Union[complex, Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized complex value.

Return type:

complex

abstract deserialize_custom(name, callback)

Deserialize anything using a custom callback function.

Parameters:

• name (str) – Name of the dataset.

• callback (Callable[[DeserializationProcess], TypeVar(_RT)]) – Callback function to be executed.

Returns:

The result of the callback function.

Return type:

_RT

abstract deserialize_floating(name, default='UNDEFINED')

Deserialize a floating point value.

Parameters:

• name (str) – Name of the dataset.

• default (Union[float, Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized floating point value.

Return type:

float

abstract deserialize_integer(name, default='UNDEFINED')

Deserialize an integer value.

Parameters:

• name (str) – Name of the dataset.

• default (Union[int, Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized integer value.

Return type:

int

deserialize_object(name, /, *args)

Deserialize an object.

Parameters:

• name (str) – Name of the dataset.

• *args – Optional arguments for method overloading.

Return type:

Any

Returns: The deserialized object.

Raises:

• RuntimeError – If the object is not a registered class.

• RuntimeError – If the dataset does not exist and no default value was provided.

• RuntimeError – If the deserialized object is not of the expected type.

abstract deserialize_object_sequence(name, type, start=0, stop=None)

Deserialize a sequence of objects.

Parameters:

• name (str) – Name of the dataset.

• type (Type[TypeVar(_OT, bound= Serializable)]) – Expected type of the deserialized objects.

• start (int) – Index of the first object in the sequence. Defaults to zero.

• stop (int | None) – Index of the last object in the sequence. Defaults to None, i.e. the end of the sequence.

Returns:

The deserialized sequence of objects.

Return type:

Sequence[_OT]

Raises:

IndexError – If the start index is out of bounds.

deserialize_range(name, default='UNDEFINED')

Deserialize a range value.

Parameters:

• name (str) – Name of the dataset.

• default (Union[TypeVar(_RT), Literal['UNDEFINED']]) – Default value to be returned if the dataset does not exist.

Return type:

Union[float, tuple[float, float], TypeVar(_RT)]

Returns: The deserialized range value.

abstract deserialize_string(name, default='UNDEFINED')

Deserialize a string value.

Parameters:

• name (str) – Name of the dataset.

• default (Union[str, Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized string value.

Return type:

str

finalize()

Finalize the deserialization process.

After finalization, the deserialization process is considered complete and no further deserialization is possible. Closes any open file handles and releases any resources reserved used during the deserialization process.

Return type:

None

abstract sequence_length(name)

Deserialize the length of a sequence.

Parameters:

name (str) – Name of the dataset.

Return type:

int

Returns: The length of the sequence. Zero if the dataset does not exist.

class HDFSerializationProcess(tag_registry, base_group, group, arrays, objects)

Bases: SerializationProcess

A process representation for serializing objects to HDF5.

static New(tag_registry, base_group, campaign=None)

Return type:

HDFSerializationProcess

finalize()

Finalize the serialization process.

After finalization, the serialization process is considered complete and no further serialization is possible. Closes any open file handles and releases any resources reserved used during the serialization process.

Return type:

None

serialize_array(array, name, cache=True)

Serialize a numpy array.

Warning

Arrays to be serialized should be immutable during the serialization process. This is to ensure that the array’s memory address remains constant and can be used as a unique identifier. If this can’t be guaranteed, caching for the respective array should be disabled.

Parameters:

• array (ndarray) – The numpy array to be serialized.

• name (str) – Name of the dataset.

• cache (bool) – Cache the array for future reference. Defaults to True.

Return type:

None

serialize_complex(value, name)

Serialize a complex value.

Parameters:

• value (complex) – The complex value to be serialized.

• name (str) – Name of the dataset.

Return type:

None

serialize_custom(name, serializer)

Serialize anything using a custom function.

Parameters:

• name (str) – Name of the dataset.

• serializer (Callable[[SerializationProcess], None]) – Serialization function to be executed.

Return type:

None

serialize_floating(value, name)

Serialize a floating point value.

Parameters:

• value (float) – The floating point value to be serialized.

• name (str) – Name of the dataset.

Return type:

None

serialize_integer(value, name)

Serialize an integer value.

Parameters:

• value (int) – The integer value to be serialized.

• name (str) – Name of the dataset.

Return type:

None

serialize_object_sequence(objects, name, append=False, root=False)

Serialize a sequence of objects.

Parameters:

• objects (Union[Sequence[Serializable], set[Serializable]]) – The sequence of objects to be serialized.

• name (str) – Name of the dataset.

• append (bool) – Append the objects to the dataset if it already exists. Defaults to False.

Return type:

None

serialize_string(value, name)

Serialize a string value.

Parameters:

• value (str) – The string value to be serialized.

• name (str) – Name of the dataset.

Return type:

None

class HDFDeserializationProcess(tag_registry, base_group, group, objects, arrays)

Bases: DeserializationProcess

A process representation for deserializing objects from HDF5.

static New(tag_registry, base_group, campaign=None)

Return type:

HDFDeserializationProcess

deserialize_array(name, dtype, default='UNDEFINED')

Deserialize a numpy array.

Parameters:

• name (str) – Name of the dataset.

• dtype (Union[dtype[Any], None, type[Any], _SupportsDType[dtype[Any]], str, tuple[Any, int], tuple[Any, Union[SupportsIndex, Sequence[SupportsIndex]]], list[Any], _DTypeDict, tuple[Any, Any]]) – Expected data type of the array.

• default (Union[ndarray, Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized numpy array.

Return type:

numpy.ndarray

deserialize_complex(name, default='UNDEFINED')

Deserialize a complex value.

Parameters:

• name (str) – Name of the dataset.

• default (Union[TypeVar(_RT), Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized complex value.

Return type:

complex

deserialize_custom(name, callback=None)

Deserialize anything using a custom callback function.

Parameters:

• name (str) – Name of the dataset.

• callback (Optional[Callable[[DeserializationProcess], TypeVar(_RT)]]) – Callback function to be executed.

Returns:

The result of the callback function.

Return type:

_RT

deserialize_floating(name, default='UNDEFINED')

Deserialize a floating point value.

Parameters:

• name (str) – Name of the dataset.

• default (Union[TypeVar(_RT), Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized floating point value.

Return type:

float

deserialize_integer(name, default='UNDEFINED')

Deserialize an integer value.

Parameters:

• name (str) – Name of the dataset.

• default (Union[TypeVar(_RT), Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized integer value.

Return type:

int

deserialize_object_sequence(name, type, start=0, stop=None)

Deserialize a sequence of objects.

Parameters:

• name (str) – Name of the dataset.

• type (Type[TypeVar(_OT, bound= Serializable)]) – Expected type of the deserialized objects.

• start (int) – Index of the first object in the sequence. Defaults to zero.

• stop (int) – Index of the last object in the sequence. Defaults to None, i.e. the end of the sequence.

Returns:

The deserialized sequence of objects.

Return type:

Sequence[_OT]

Raises:

IndexError – If the start index is out of bounds.

deserialize_string(name, default='UNDEFINED')

Deserialize a string value.

Parameters:

• name (str) – Name of the dataset.

• default (Union[TypeVar(_RT), Literal['UNDEFINED']]) – Default value to be returned if the value does not exist.

Returns:

The deserialized string value.

Return type:

str

finalize()

Finalize the deserialization process.

After finalization, the deserialization process is considered complete and no further deserialization is possible. Closes any open file handles and releases any resources reserved used during the deserialization process.

Return type:

None

sequence_length(name)

Deserialize the length of a sequence.

Parameters:

name (str) – Name of the dataset.

Return type:

int

Returns: The length of the sequence. Zero if the dataset does not exist.

class SerializableType

Type of Serializable Class.

alias of TypeVar(‘SerializableType’, bound=Serializable)

class SerializationBackend(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: SerializableEnum

Backend of the serialization process.

HDF = 0

HDF5 serialization backend.

MAT = 1

MATLAB serialization backend.

Not implemented yet.

PICKLE = 2

Pickle serialization backend.

Not implemented yet.

UNDEF_TYPE

Type of an undefined value representing optional arguments that include None as a default value.

UNDEF

Undefined value for optional arguments that include None as a default value.

class SET

Type of serializable enumeration.

alias of TypeVar(‘SET’, bound=SerializableEnum)

class _RT

alias of TypeVar(‘_RT’)

class _OT

alias of TypeVar(‘_OT’, bound=Serializable)