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 Serializable

Bases: object

Base class for serializable classes.

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

yaml_tag: Optional[str] = None

YAML serialization tag.

classmethod to_yaml(representer, node)

Serialize a serializable object to YAML.

Parameters
  • representer (SafeRepresenter) – A handle to a representer used to generate valid YAML code. The representer gets passed down the serialization tree to each node.

  • node (Serializable) – The channel instance to be serialized.

Returns

The serialized YAML node.

Return type

Node

classmethod from_yaml(constructor, node)

Recall a new serializable class instance from YAML.

Parameters
  • constructor (SafeConstructor) – A handle to the constructor extracting the YAML information.

  • node (Node) – YAML node representing the Channel serialization.

Returns

The de-serialized object.

Return type

Serializable

classmethod InitializationWrapper(configuration)

Conveniently initializes serializable classes.

Parameters

configuration (Dict[str, Any]) – Configuration parameter dictionary.

Returns

Initialized class instance.

Return type

SerializableArray

class SerializableArray

Bases: hermespy.core.factory.Serializable

Base class for serializable classes within an array-like structure.

Only classes inheriting from Serializable will be serialized by the factory. Additionally, SerializableArray nodes may be annotated with a tuple of non-negative integers indicating their location within the array grid.

static Set_Array(matrix, deserialized_data)

Set matrix fields from deserialized array data.

Parameters
  • matrix (Union[Mapping, Sequence]) – The matrix to be set.

  • ( (deserialized_data) –

Return type

None

class Factory

Bases: object

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

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

List of recognized filename extensions for serialization files.

property clean: bool

Access clean flag.

Returns

Clean flag.

Return type

bool

property registered_classes: Set[Type[hermespy.core.factory.Serializable]]

Classes registered for serialization within the factory.

Return type

Set[Type[Serializable]]

property registered_tags: Set[str]

Read registered YAML tags.

Returns

Set of registered YAML tags.

Return type

Set[str]

load(path)

Load a serialized executable configuration from a filesystem location.

Parameters

path (str) – Path to a file or a folder featuring serialization files.

Returns

Serializable HermesPy objects.

Return type

executables (List[Serializable])

Raises
  • RuntimeError – If path does not contain an executable object.

  • RuntimeError – If path contains more than one executable object.

refurbish_tags(serialization)

Callback to restore explicit YAML tags to serialization streams.

Return type

str

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.

Returns

List of serializable objects recalled from paths.

Return type

List[Any]

Raises

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

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.

Returns

List of serializable objects recalled from path.

Return type

List[Any]

Raises

ValueError – If path is not a directory.

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

from_str(config)

Load a configuration from a string object.

Parameters

config (str) – The configuration to be loaded.

Returns

List of serialized objects within path.

Return type

List[Any]

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.

from_file(file)

Load a configuration from a single YAML file.

Parameters

file (str) – Path to the folder configuration.

Returns

List of serialized objects within path.

Return type

List[Any]

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

from_stream(stream)

Load a configuration from an arbitrary text stream.

Parameters

stream (TextIOBase) – Text stream containing the configuration.

Returns

List of serialized objects within stream.

Return type

List[Any]

Raises

ConstructorError – If YAML parsing fails.

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