spine.utils.factory

Contains functions needed to instantiate classes from configuration blocks.

This allows to generically convert a YAML block into an instatiated class with all the appropriate checks that the class exists and is provided with appropriate arguments.

Functions

instantiate(mod_dict, cfg[, alt_name])

Instantiates a class based on a configuration dictionary and a list of possible classes to chose from.

instantiate_modules(mod_dict, modules[, ...])

Instantiate an ordered mapping of module configuration blocks.

module_dict(module[, class_name, pattern])

Converts module into a dictionary which maps class names onto classes.

parse_module_config(modules[, name_key, ...])

Parse an ordered mapping of module blocks.
spine.utils.factory.module_dict(module: ModuleType, class_name: str | None = None, pattern: str | None = None) → dict[str, Any][source]

Converts module into a dictionary which maps class names onto classes.

Parameters:

  • module (module) – Module from which to fetch the classes

  • class_name (str, optional) – If specified, only allow aliases that match it

  • pattern (str, optional) – If specified, looks for a specific pattern in the class name

Returns:

Dictionary which maps acceptable class names to classes themselves

Return type:

dict

spine.utils.factory.instantiate(mod_dict: dict[str, Any], cfg: Mapping[str, Any] | str, alt_name: str | None = None, **kwargs: Any) → Any[source]

Instantiates a class based on a configuration dictionary and a list of possible classes to chose from.

This function supports two YAML configuration structures (parsed as a dictionary):

function:
  name: function_name
  kwarg_1: value_1
  kwarg_2: value_2
  ...

or

function:
  name: function_name
  args:
    value_1
    value_2
    ...
  kwargs:
    kwarg_1: value_1
    kwarg_2: value_2
    ...

The name field can have a different name, as long as it is specified.

Parameters:

  • mod_dict (dict) – Dictionary which maps a class name onto an object class.

  • cfg (dict) – Configuration dictionary

  • alt_name (str, optional) – Key under which the class name can be specfied, beside ‘name’ itself

  • **kwargs (dict, optional) – Additional parameters to pass to the function

Returns:

Instantiated object

Return type:

object

spine.utils.factory.parse_module_config(modules: Mapping[str, Mapping[str, Any] | None], name_key: str = 'name', priority_key: str = 'priority', sort_by_priority: bool = False, priority_descending: bool = False, skip_none: bool = True) → OrderedDict[str, dict[str, Any]][source]

Parse an ordered mapping of module blocks.

Each top-level key is treated as the module label. The concrete class name is read from name_key when present, otherwise the label itself is used as the class name. This supports both compact blocks such as:

gain:
  gain: 2.0

and repeated instances of the same module:

first_gain:
  name: gain
  gain: 2.0
second_gain:
  name: gain
  gain: 3.0
Parameters:

  • modules (Mapping) – Ordered mapping of module labels to configuration dictionaries.

  • name_key (str, default 'name') – Configuration key which specifies the class name.

  • priority_key (str, default 'priority') – Configuration key which specifies optional execution priority.

  • sort_by_priority (bool, default False) – If True, modules with smaller priority values run first. Modules without a priority retain their relative order after prioritized modules.

  • priority_descending (bool, default False) – If True and sort_by_priority is True, modules with larger priority values run first instead.

  • skip_none (bool, default True) – If True, skip entries explicitly set to None.

Returns:

Mapping of module label to dictionaries with name, cfg and priority fields.

Return type:

OrderedDict

spine.utils.factory.instantiate_modules(mod_dict: dict[str, Any], modules: Mapping[str, Mapping[str, Any] | None], name_key: str = 'name', priority_key: str = 'priority', sort_by_priority: bool = False, priority_descending: bool = False, skip_none: bool = True, **kwargs: Any) → OrderedDict[str, Any][source]

Instantiate an ordered mapping of module configuration blocks.

Parameters:

  • mod_dict (dict) – Dictionary which maps class names onto classes.

  • modules (Mapping) – Ordered mapping of module labels to configuration dictionaries.

  • name_key (str, default 'name') – Configuration key which specifies the class name.

  • priority_key (str, default 'priority') – Configuration key which specifies optional execution priority.

  • sort_by_priority (bool, default False) – If True, modules with smaller priority values run first.

  • priority_descending (bool, default False) – If True and sort_by_priority is True, modules with larger priority values run first instead.

  • skip_none (bool, default True) – If True, skip entries explicitly set to None.

  • **kwargs (dict) – Extra keyword arguments forwarded to every instantiated class.

Returns:

Mapping of module label to instantiated module objects.

Return type:

OrderedDict