Source code for osprey_connectors.directory._contract

"""What a channel directory answers, and in what shape.

The shared answers (``Outcome``, ``Unavailable``, ``Source``, ``BackendSpec``)
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 Iterable, Mapping
from dataclasses import dataclass, field
from types import MappingProxyType
from typing import Literal

from osprey_connectors.service_answers import (
    Outcome,
    Source,
    Unavailable,
    _Backend,
    _require_reason,
)


[docs] @dataclass(frozen=True, kw_only=True) class DirectoryRow: """One channel, as the directory lists it. ``server`` is the process serving the channel and ``channel_type`` its type there: EPICS RecSync's ``iocName`` and ``recordType``, a Tango database's device-server instance and device class, a DOOCS ENS server name and device type. ``last_announced`` is RecSync's ``time`` or Tango's last export time. """ name: str status: Literal["Active", "Inactive"] | None = None description: str | None = None channel_type: str | None = None server: str | None = None host: str | None = None last_announced: str | None = None
[docs] @dataclass(frozen=True, kw_only=True) class DirectoryRecord: """One PV in full. Every property is optional and a string, as measured.""" row: DirectoryRow properties: Mapping[str, str] = field(default_factory=dict) tags: list[str] = field(default_factory=list)
[docs] @dataclass(frozen=True, kw_only=True) class DirectoryQuery: """One search, built only by the service; callers pass these fields as keywords. A query keys the service's cache, so it hashes: the repeatable filters become tuples and ``properties`` stays out of the hash. """ words: str = "" name: str | None = None properties: Mapping[str, str] = field(default_factory=dict, hash=False) status: str | None = None server: tuple[str, ...] = () channel_type: tuple[str, ...] = () page: int = 0 page_size: int = 50 def __post_init__(self) -> None: for name in ("server", "channel_type"): object.__setattr__(self, name, _filter_values(getattr(self, name)))
def _filter_values(values: str | Iterable[str] | None) -> tuple[str, ...]: if values is None: return () return (values,) if isinstance(values, str) else tuple(values)
[docs] @dataclass(frozen=True, kw_only=True) class DirectoryPage: """One page of a search. ``searched`` is the search in plain words and ``request`` the literal request sent. ``partial`` lists ``{part, reason}`` for what missed the deadline; ``facets`` maps a row field to ``{value, count}`` lists, and is ``None`` with ``facets_reason`` when it could not be computed. """ outcome: Outcome searched: str request: str source: Source total: int | None = None rows: list[DirectoryRow] = field(default_factory=list) truncated: bool = False partial: list[Mapping[str, str]] = field(default_factory=list) facets: Mapping[str, list[Mapping[str, object]]] | None = None facets_reason: str | None = None reason: str | None = None def __post_init__(self) -> None: _require_reason(self.outcome, self.reason)
[docs] class ChannelDirectory(_Backend, ABC): """Search the control system's own directory of PVs.""" @property def field_properties(self) -> Mapping[str, str]: """The directory property that fills each row field. A field not listed comes from no single property. """ return MappingProxyType({})
[docs] @abstractmethod async def search(self, query: DirectoryQuery, deadline: float) -> DirectoryPage: """One page of the rows *query* matches; no rows is ``NO_MATCH``, not ``NOT_LISTED``."""
[docs] @abstractmethod async def count(self, query: DirectoryQuery, deadline: float) -> int | Unavailable: """How many rows *query* matches over the whole directory."""
[docs] @abstractmethod async def describe( self, name: str, deadline: float ) -> DirectoryRecord | Literal[Outcome.NOT_LISTED] | Unavailable: """The record of the PV called exactly *name*, or ``NOT_LISTED``."""
[docs] @abstractmethod async def property_names(self, deadline: float) -> list[str] | Unavailable: """The property names the directory holds."""
[docs] @abstractmethod async def property_values( self, name: str, prefix: str | None, deadline: float ) -> list[str] | Unavailable: """The values of property *name*, those starting with *prefix* if given."""
[docs] @abstractmethod async def probe(self, deadline: float) -> str | Unavailable: """Whether the service answers: the evidence in plain words, or why not."""