pyaml.configuration#

PyAML configuration module

exception pyaml.configuration.UnsupportedConfigurationRootError(message)#

Bases: PyAMLConfigException

Raised when a fragment contains unsupported root-level fields.

class pyaml.configuration.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.

Methods

`root_fields()`	Return the supported accelerator root fields in order. Return the ordered root fields supported by the accelerator configuration.
`add()`	Add a configuration fragment from a dict or a YAML/JSON file.
`remove()`	Remove a named entry from an aggregated category.
`replace()`	Replace an existing named entry in an aggregated category.
`clear()`	Clear the aggregated state, or a single root field/category.
`categories()`	Return categories that currently contain entries.
`keys()`	Return known entry names.
`has()`	Check whether a named entry exists.
`get()`	Return a named configuration entry.
`find()`	Search entry names using wildcards or regular expressions.
`settings()`	Return aggregated scalar accelerator settings.
`to_dict()`	Return the aggregated configuration as a plain dictionary.
`build()`	Build an Accelerator from the aggregated configuration snapshot.
`strip_internal_metadata()`	Remove additionnal internal informations info from value
`strip_runtime_internal_metadata()`	Remove additionnal internal informations info from value

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 supported accelerator root fields in order. Return the ordered root fields supported by the accelerator configuration.

The field order is derived from Accelerator.__init__(), excluding internal or categorized fields such as control and simulator collections.

Returns:

tuple[str, …] – Root field names in configuration order, prefixed with "type".
Examples
.. code-block:: python
>>> ConfigurationManager.root_fields()

Return type:

tuple[str, …]

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.
include_locations (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, validate=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]
Return type:: 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]

Return type:

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]

Return type:

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

Return type:

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]
Return type:: 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]
Return type:: dict[str, Any]

Examples

>>> manager.settings()

to_dict()#

Return the aggregated configuration as a plain dictionary.

Returns:: dict[str, Any]
Return type:: dict[str, Any]

Examples

>>> snapshot = manager.to_dict()

Modules

`factory`	Build PyAML objects from configuration dictionaries and lists.
`fileloader`	Load PyAML configuration files and expand nested references.
`manager`	Aggregate accelerator configuration fragments before runtime construction.
`restfetcher`	Fetch and expand configuration documents from HTTP(S) sources.
`unbound_element`	Deferred construction of control-system-specific elements.