Serialization Factory

This module implements the main interface for loading / dumping HermesPy configurations from / to YAML files. Every mutable object that is expected to have its state represented as a text-section within configuration files must inherit from the Serializable base class.

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 .yml text file is as easy as

factory = Factory()
factory.to_file("dump.yml", serializable)

and can be loaded again just as easily via

factory = Factory()
serializable = factory.from_file("dump.yml")

from any context.

class Factory

Bases: object

Helper class to load HermesPy simulation scenarios from YAML configuration files.

from_file(file)

Load a configuration from a single YAML file.

Parameters:

file (str) – Path to the folder configuration.

Return type:

Union[Sequence[Any], Any]

Returns: Serialized objects within path.

from_folder(path, recurse=True, follow_links=False)

Load a configuration from a folder.

Parameters:

• path (str) – Path to the folder configuration.

• recurse (bool, optional) – Recurse into sub-folders within path.

• follow_links (bool, optional) – Follow links within path.

Return type:

Union[Sequence[Any], Any]

Returns: Serializable objects recalled from path.

Raises:

ValueError – If path is not a directory.

from_path(paths)

Load a configuration from an arbitrary file system path.

Parameters:

paths (Union[str, Set[str]]) – Paths to a file or a folder featuring .yml config files.

Return type:

Sequence[Any]

Returns: Serializable objects recalled from paths.

Raises:

ValueError – If the provided path does not exist on the filesystem.

from_str(config)

Load a configuration from a string object.

Parameters:

config (str) – The configuration to be loaded.

Return type:

Union[Sequence[Any], Any]

Returns: List of objects or object from config.

from_stream(stream)

Load a configuration from an arbitrary text stream.

Parameters:

stream (TextIOBase) – Text stream containing the configuration.

Return type:

Union[Sequence[Any], Any]

Returns:

List of deserialized objects or object within stream.

Raises:

ConstructorError – If YAML parsing fails.

to_file(path, *args)

Dump a configuration to a single YML file.

Parameters:

• path (str) – Path to the configuration file.

• *args (Any) – Configuration objects to be dumped.

Raises:

RepresenterError – If objects in *args are unregistered classes.

Return type:

None

to_folder(path, *args)

Dump a configuration to a folder.

Parameters:

• path (str) – Path to the folder configuration.

• *args (Any) – Configuration objects to be dumped.

Return type:

None

to_str(*args)

Dump a configuration to a folder.

Parameters:

*args (Any) – Configuration objects to be dumped.

Returns:

String containing full YAML configuration.

Return type:

str

Raises:

RepresenterError – If objects in *args are unregistered classes.

to_stream(stream, *args)

Dump a configuration to an arbitrary text stream.

Parameters:

• stream (TextIOBase) – Text stream to the configuration.

• *args (Any) – Configuration objects to be dumped.

Raises:

RepresenterError – If objects in *args are unregistered classes.

Return type:

None

property clean: bool

Use clean YAML standard.

Disabling the clean flag will deactivate additional text processing to the YAML configuration files done by Hermes, such as dB conversion or linear number spaces.

Returns: Clean flag.

extensions: Set[str] = {'.cfg', '.yaml', '.yml'}

List of recognized filename extensions for serialization files.

property registered_classes: ValuesView[Type[Serializable]]

Classes registered for serialization within the factory.

property registered_tags: KeysView[str]

Read registered YAML tags.

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

Read registered YAML tags.

class HDFSerializable

Bases: object

Base class for object serializable to the HDF5 format.

Structures are serialized to HDF5 files by the to_HDF routine and de-serialized by the from_HDF method, respectively.

class HDFSerializableType

Type of HDF Serializable Class

alias of TypeVar(‘HDFSerializableType’, bound=HDFSerializable)

class SET

Type of serializable enumeration.

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

class Serializable

Bases: object

Base class for serializable classes.

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

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

Bases: Serializable, Enum

Base class for serializable enumerations.

classmethod from_parameters(enum)

Initialize enumeration from multiple parameters.

Parameters:

enum (SET | int | str) – The parameter from which the enum should be initialized.

Return type:

TypeVar(SET, bound= SerializableEnum)

Returns: The initialized enumeration.

class SerializableType

Type of Serializable Class.

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