yellow_pages

yellow_pages.py

Fully dynamic YellowPages service attached to Accelerator.

Key points:

• Auto-discovery only: arrays, tools and diagnostics are discovered at runtime by scanning all modes.

• No caching: every call reflects current runtime state.

• Simple query syntax for identifiers:

  • wildcard / fnmatch:

    yp[“OH4*”]

  • regular expression:

    yp[“re:^SH1A-C0[12]-H$”]

Accelerator interface

• controls() -> dict[str, ElementHolder]

• simulators() -> dict[str, ElementHolder]

• modes() -> dict[str, ElementHolder]

class YellowPages(accelerator)

Bases: object

Dynamic discovery service for accelerator objects.

YellowPages provides a unified access layer to arrays, tuning tools and diagnostics available in an Accelerator.

Entries are discovered dynamically by scanning all ElementHolder instances associated with the Accelerator control and simulation modes.

Notes

The Accelerator must provide:

• controls() -> dict[str, ElementHolder]

• simulators() -> dict[str, ElementHolder]

• modes() -> dict[str, ElementHolder]

Examples

Print the global overview:

>>> print(sr.yellow_pages)

Resolve an entry across all modes:

>>> sr.yellow_pages.get("BPM")

Resolve in a specific mode:

>>> sr.yellow_pages.get("BPM", mode="live")

Search identifiers using wildcards:

>>> sr.yellow_pages["OH4*"]

Search identifiers using a regular expression:

>>> sr.yellow_pages["re:^SH1A-C0[12]-H$"]

__dir__()

Extend dir() with attribute-friendly discovered keys.

__getattr__(name)

Allow attribute-style access for valid discovered keys.

Examples

>>> sr.yellow_pages.BPM

__getitem__(query)

Alias for get().

__repr__()

Return a human-readable overview of the YellowPages content.

The representation lists:

• controls

• simulators

• discovered arrays, tools and diagnostics

The displayed type corresponds to the Python module defining the resolved object.

Examples

>>> print(sr.yellow_pages)

Example output:

Controls:
    live
    .

Simulators:
    design
    .

Arrays:
    BPM (pyaml.arrays.bpm_array) size=224
    HCORR (pyaml.arrays.magnet_array) size=96
    .

Tools:
    DEFAULT_ORBIT_CORRECTION (pyaml.tuning_tools.orbit)
    .

Diagnostics:
    BETATRON_TUNE (pyaml.diagnostics.tune_monitor)
    .

__str__()

Return str(self).

availability(key)

Return the set of modes where a key is available.

Parameters:

key (str) – Entry name.

Returns:

set[str]

Examples

>>> sr.yellow_pages.availability("BPM")
>>> sr.yellow_pages.availability("DEFAULT_ORBIT_CORRECTION")

categories()

Return the list of available categories.

Only categories that contain entries are returned.

Returns:

list[str]

Examples

>>> sr.yellow_pages.categories()
['Arrays', 'Tools', 'Diagnostics']

get(query, mode=None)

Search identifiers using a wildcard or regular expression.

Parameters:

• query (str) – Search expression.

• mode (str, optional) – Restrict the search to a specific Accelerator mode.

Returns:

list[str]

Examples

>>> sr.yellow_pages.get("OH4*")

>>> sr.yellow_pages.get("OH4*", mode="live")

>>> sr.yellow_pages.get("re:^SH1A-C0[12]-H$")

has(key)

Check whether a YellowPages key exists.

Parameters:

key (str) – Entry name.

Returns:

bool – True if the key exists.

Examples

>>> sr.yellow_pages.has("BPM")
True

>>> sr.yellow_pages.has("UNKNOWN")
False

keys(category=None)

Return available YellowPages keys.

Parameters:

category (str or YellowPagesCategory, optional) – Restrict the result to a specific category.

Returns:

list[str]

Examples

All entries:

>>> sr.yellow_pages.keys()

Only arrays:

>>> sr.yellow_pages.keys("Arrays")

Using enum:

>>> sr.yellow_pages.keys(YellowPagesCategory.ARRAYS)

class YellowPagesCategory(*values)

Bases: str, Enum

__repr__()

Return repr(self).

__str__()

Return str(self).

ARRAYS = 'Arrays'

DIAGNOSTICS = 'Diagnostics'

TOOLS = 'Tools'

class YellowPagesError(message)

Bases: PyAMLException

YellowPages-specific error with clear user-facing messages.

class YellowPagesQueryError(message)

Bases: YellowPagesError

Raised when a YellowPages query string cannot be evaluated.