Source code for osprey_connectors.alarm_state._contract

"""What an alarm-state feed answers, and in what shape.

The shared answers and the rules every backend follows are in
:mod:`osprey_connectors.service_answers`.
"""

from __future__ import annotations

from abc import ABC, abstractmethod
from collections.abc import Mapping
from dataclasses import dataclass, field
from typing import Literal

from osprey_connectors.service_answers import Unavailable, _Backend

_SEVERITY_RANK = {"OK": 0, "MINOR": 1, "MAJOR": 2, "INVALID": 3, "UNDEFINED": 4}


[docs] def severity_rank(severity: object) -> int: """The severity's rank, higher is worse; an unknown one ranks highest, never as recovered.""" unknown = len(_SEVERITY_RANK) return _SEVERITY_RANK.get(severity, unknown) if isinstance(severity, str) else unknown
[docs] @dataclass(frozen=True, kw_only=True) class AlarmStateRecord: """What one PV's alarm is now. The backend alone sets ``stale``; others pass it on.""" severity: str | None = None status: str | None = None latched: bool = False acknowledged: bool = False message: str | None = None time: str | None = None stale: bool = False
[docs] @dataclass(frozen=True, kw_only=True) class AlarmStateRow: """One channel the feed holds a state for. ``channel`` is the channel address; ``path`` is the alarm-tree place the state was reported under, ``None`` for a backend with no tree. Tango alarm devices and DOOCS alarm servers fill ``path`` where they keep a hierarchy. """ channel: str path: str | None state: AlarmStateRecord
[docs] @dataclass(frozen=True, kw_only=True) class AlarmStates: """Every channel's alarm state now, and the counts per severity. ``counts`` is derived from the rows' severities, ``OK`` included and a ``None`` severity not counted, so it cannot disagree with them. ``last_contact`` is the ISO-8601 UTC time the backend last heard from the feed (a message or an offset check), ``None`` when it never has; ``stale`` is the backend's flag. """ rows: tuple[AlarmStateRow, ...] stale: bool last_contact: str | None counts: Mapping[str, int] = field(init=False, hash=False) def __post_init__(self) -> None: counts: dict[str, int] = {} for row in self.rows: severity = row.state.severity if severity is not None: counts[severity] = counts.get(severity, 0) + 1 object.__setattr__(self, "counts", dict(sorted(counts.items())))
[docs] @dataclass(frozen=True, kw_only=True) class AlarmConfigRecord: """One PV's place in the alarm tree.""" in_tree: Literal["yes", "no", "unknown"] path: str | None = None guidance: object = None displays: object = None enabled: bool | None = None latching: bool | None = None
[docs] class AlarmState(_Backend, ABC): """Follow a live alarm feed. :meth:`start` begins whatever feeds the snapshot and :meth:`aclose` ends it; both are idempotent. Until the feed has caught up, reads answer ``Unavailable("alarm feed still loading")``, and once caught up with no message at all, ``Unavailable("no message from the feed yet")``: never a clear state and never ``in_tree: "no"``. A read of a started feed waits for catch-up up to its deadline and only then answers ``alarm feed still loading``; a feed that already knows its answer, unreachable or unbuildable, answers at once. """
[docs] @abstractmethod async def start(self) -> None: """Begin feeding the snapshot."""
[docs] @abstractmethod async def aclose(self) -> None: """Stop feeding the snapshot."""
[docs] @abstractmethod async def state_for( self, channel: str, deadline: float ) -> AlarmStateRecord | Unavailable | None: """The alarm state of *channel*, waiting up to *deadline* seconds for catch-up. ``None`` is a caught-up feed that holds none for it. """
[docs] @abstractmethod async def states(self, deadline: float) -> AlarmStates | Unavailable: """Every channel's alarm state, waiting up to *deadline* seconds for catch-up. Before catch-up it answers as :meth:`state_for` does, never an empty list. """
[docs] @abstractmethod async def config_for(self, channel: str, deadline: float) -> AlarmConfigRecord | Unavailable: """The live alarm configuration of *channel*, waiting up to *deadline* seconds for catch-up."""
[docs] @abstractmethod async def probe(self, deadline: float) -> str | Unavailable: """Whether the service answers: the evidence in plain words, or why not."""