manager

manager.py

Configuration aggregation helpers for Accelerator.

This module provides ConfigurationManager, a lightweight service used to collect configuration fragments before runtime objects are built.

Typical usage is:

• load one or more accelerator configuration fragments

• inspect or query the aggregated state

• build the final Accelerator

class ConfigurationManager

Bases: object

Aggregate accelerator configuration fragments before runtime build.

ConfigurationManager stores configuration fragments as plain dictionaries and exposes convenience helpers to inspect, query and update them before constructing the final runtime object graph.

Notes

The manager only accepts accelerator-root fragments and merges named categories such as controls, simulators, arrays and devices.

Examples

Load a base configuration and inspect it:

>>> from pyaml.configuration import ConfigurationManager
>>> manager = ConfigurationManager()
>>> manager.add("tests/config/config_manager_base.yaml")
>>> manager.categories()
['simulators']

Build the final accelerator:

>>> sr = manager.build()
>>> sr.design.name()
'design'

classmethod root_fields()

Return the ordered root fields supported by the accelerator model.

The field order is derived from ConfigModel.

Returns:

tuple[str, …]

Examples

>>> ConfigurationManager.root_fields()

static strip_internal_metadata(value)

Remove additionnal internal informations info from value

static strip_runtime_internal_metadata(value)

Remove additionnal internal informations info from value

add(payload, **kwargs)

Add a configuration fragment from a dict or a YAML/JSON file.

Parameters:

• payload (dict or str or os.PathLike) – Fragment to merge into the current aggregated state.

• source_name (str, optional) – Explicit source label to associate with the fragment.

• use_fast_loader (bool, optional) – Forwarded to the configuration loader.

Examples

>>> manager.add("tests/config/config_manager_base.yaml")

>>> manager.add(
...     {
...         "facility": "ESRF",
...         "machine": "sr",
...         "energy": 6e9,
...         "data_folder": "/data/store",
...         "devices": [],
...     }
... )

build(ignore_external=False)

Build an Accelerator from the aggregated configuration snapshot.

Parameters:

ignore_external (bool, optional) – Forwarded to pyaml.accelerator.Accelerator.from_dict().

Returns:

Accelerator

Examples

>>> sr = manager.build()

categories()

Return categories that currently contain entries.

Returns:

list[str]

Examples

>>> manager.categories()

clear(category=None)

Clear the aggregated state, or a single root field/category.

Parameters:

category (str, optional) – If provided, only that category or root field is cleared.

Examples

>>> manager.clear("simulators")

>>> manager.clear()

find(pattern, category=None)

Search entry names using wildcards or regular expressions.

Parameters:

• pattern (str) – Wildcard pattern or regular expression prefixed with re:.

• category (str, optional) – Restrict the search to one category.

Returns:

list[str]

Examples

>>> manager.find("BPM_C04*")

>>> manager.find("re:^QF1.*$")

get(category, name)

Return a named configuration entry.

Parameters:

• category (str) – Category to inspect.

• name (str) – Entry name.

Returns:

dict[str, Any]

Examples

>>> manager.get("simulators", "design")

has(category, name)

Check whether a named entry exists.

Parameters:

• category (str) – Category to inspect.

• name (str) – Entry name.

Returns:

bool

Examples

>>> manager.has("simulators", "design")
True

keys(category=None)

Return known entry names.

Parameters:

category (str, optional) – Restrict the result to one category.

Returns:

list[str]

Examples

>>> manager.keys()

>>> manager.keys("simulators")

remove(category, name)

Remove a named entry from an aggregated category.

Parameters:

• category (str) – Category that contains the entry.

• name (str) – Entry name to remove.

Examples

>>> manager.remove("simulators", "tracking")

replace(category, element)

Replace an existing named entry in an aggregated category.

Parameters:

• category (str) – Category that contains the entry.

• element (dict) – Replacement configuration entry.

Examples

>>> manager.replace(
...     "simulators",
...     {
...         "type": "pyaml.lattice.simulator",
...         "name": "design",
...         "lattice": "tests/config/sr/lattices/ebs.mat",
...     },
... )

settings()

Return aggregated scalar accelerator settings.

Returns:

dict[str, Any]

Examples

>>> manager.settings()

to_dict()

Return the aggregated configuration as a plain dictionary.

Returns:

dict[str, Any]

Examples

>>> snapshot = manager.to_dict()

DEFAULT_TYPE = 'pyaml.accelerator'

NAMED_CATEGORIES = ('controls', 'simulators', 'arrays', 'devices')

class UnsupportedConfigurationRootError(message)

Bases: PyAMLConfigException

Raised when a fragment root is outside ConfigurationManager scope.