Source code for osprey_connectors.service_answers

"""What every read-only service backend answers, whatever its kind.

A backend is read-only and never raises: a service that gives no answer is a
value, :class:`Unavailable`, or a page whose outcome says so. Every method is
async and takes ``deadline``, the seconds this call may spend; the caller owns
the overall budget and hands the same figure to calls it runs concurrently.

Backends are built as ``Backend(spec, *, project_dir=None, **seams)``. The
constructor does no I/O and there is no connect step, so building one answers
nothing about the service; ``probe`` does. Out-of-tree classes follow the same
signature. A seam the class does not take is ignored, because the factory
passes the same keywords to every backend of a kind.

The records stay plain so one conversion makes their JSON: a list, a mapping or
a string stays what the service answered, as the service recorded it.
"""

from __future__ import annotations

from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from enum import StrEnum
from pathlib import Path
from typing import Generic, Literal, TypeVar

from osprey_connectors.types import ControlTarget

#: The row record a :class:`HistoryPage` holds.
_RowT = TypeVar("_RowT")

__all__ = [
    "BackendSpec",
    "HistoryPage",
    "Outcome",
    "Source",
    "Unavailable",
]


[docs] class Outcome(StrEnum): """How a lookup ended. ``NOT_LISTED`` is only an exact-name lookup's answer.""" FOUND = "found" INACTIVE = "inactive" NOT_LISTED = "not_listed" NO_MATCH = "no_match" UNAVAILABLE = "unavailable"
def _require_reason(outcome: Outcome, reason: str | None) -> None: if outcome is Outcome.UNAVAILABLE and not reason: raise ValueError("an unavailable outcome carries its reason") def _text(recorded: object) -> str | None: """A recorded value a record holds as a string; any other is not that field's.""" return recorded if isinstance(recorded, str) else None def _flag(recorded: object) -> bool | None: """A recorded value a record holds as a flag; any other is not that field's.""" return recorded if isinstance(recorded, bool) else None
[docs] @dataclass(frozen=True) class Unavailable: """The service gave no answer, and why, in words a reader can act on.""" reason: str
[docs] @dataclass(frozen=True, kw_only=True) class Source: """Which kind of service, on which machine, an answer came from. ``service`` is the backend's type name; ``rehearsal`` is true on ``standin``. """ kind: Literal["directory", "alarm_state", "alarm_log", "put_log", "logbook", "archive"] target: ControlTarget service: str rehearsal: bool
[docs] @dataclass(frozen=True, kw_only=True) class BackendSpec: """One backend to build; ``service_targets`` makes these from the config.""" kind: Literal["directory", "alarm_log", "alarm_state", "put_log"] type: str target: ControlTarget settings: Mapping[str, object] rehearsal: bool
[docs] @dataclass(frozen=True, kw_only=True) class HistoryPage(Generic[_RowT]): """Logged rows of one PV. No rows means nothing was logged, not that nothing happened. ``rows`` are the records of the kind that answered. """ outcome: Outcome source: Source rows: Sequence[_RowT] = field(default_factory=list) truncated: bool = False retention_known: bool = False reason: str | None = None def __post_init__(self) -> None: _require_reason(self.outcome, self.reason)
class _Backend: """The construction and the source every backend kind shares.""" def __init__( self, spec: BackendSpec, *, project_dir: Path | None = None, **seams: object ) -> None: self.spec = spec self.project_dir = project_dir @property def source(self) -> Source: return Source( kind=self.spec.kind, target=self.spec.target, service=self.spec.type, rehearsal=self.spec.rehearsal, )