Directory, alarms and put log#

The read-only contracts of the directory, alarm and put-log backends behind All PVs (All PVs: the Control System’s Directory), and which source answers each kind on each control target.

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, 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.

class osprey_connectors.service_answers.BackendSpec(*, kind, type, target, settings, rehearsal)[source]#

Bases: object

One backend to build; service_targets makes these from the config.

kind: Literal['directory', 'alarm_log', 'alarm_state', 'put_log']#
type: str#
target: Literal['live', 'va', 'standin']#
settings: Mapping[str, object]#
rehearsal: bool#
__init__(*, kind, type, target, settings, rehearsal)#
class osprey_connectors.service_answers.HistoryPage(*, outcome, source, rows=<factory>, truncated=False, retention_known=False, reason=None)[source]#

Bases: 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]#
truncated: bool = False#
retention_known: bool = False#
reason: str | None = None#
__init__(*, outcome, source, rows=<factory>, truncated=False, retention_known=False, reason=None)#
class osprey_connectors.service_answers.Outcome(value)[source]#

Bases: 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'#
class osprey_connectors.service_answers.Source(*, kind, target, service, rehearsal)[source]#

Bases: object

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: Literal['live', 'va', 'standin']#
service: str#
rehearsal: bool#
__init__(*, kind, target, service, rehearsal)#
class osprey_connectors.service_answers.Unavailable(reason)[source]#

Bases: object

The service gave no answer, and why, in words a reader can act on.

reason: str#
__init__(reason)#

The control system’s own directory of channels, behind the ChannelDirectory contract.

The backends are the underscore-private modules beside this one, which the factory reaches from their type names.

class osprey_connectors.directory.ChannelDirectory(spec, *, project_dir=None, **seams)[source]#

Bases: _Backend, ABC

Search the control system’s own directory of PVs.

property field_properties: Mapping[str, str]#

The directory property that fills each row field.

A field not listed comes from no single property.

abstractmethod async search(query, deadline)[source]#

One page of the rows query matches; no rows is NO_MATCH, not NOT_LISTED.

Return type:

DirectoryPage

abstractmethod async count(query, deadline)[source]#

How many rows query matches over the whole directory.

Return type:

int | Unavailable

abstractmethod async describe(name, deadline)[source]#

The record of the PV called exactly name, or NOT_LISTED.

Return type:

DirectoryRecord | Literal[Outcome.NOT_LISTED] | ~osprey_connectors.service_answers.Unavailable

abstractmethod async property_names(deadline)[source]#

The property names the directory holds.

Return type:

list[str] | Unavailable

abstractmethod async property_values(name, prefix, deadline)[source]#

The values of property name, those starting with prefix if given.

Return type:

list[str] | Unavailable

abstractmethod async probe(deadline)[source]#

Whether the service answers: the evidence in plain words, or why not.

Return type:

str | Unavailable

class osprey_connectors.directory.DirectoryPage(*, outcome, searched, request, source, total=None, rows=<factory>, truncated=False, partial=<factory>, facets=None, facets_reason=None, reason=None)[source]#

Bases: object

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]#
truncated: bool = False#
partial: list[Mapping[str, str]]#
facets: Mapping[str, list[Mapping[str, object]]] | None = None#
facets_reason: str | None = None#
reason: str | None = None#
__init__(*, outcome, searched, request, source, total=None, rows=<factory>, truncated=False, partial=<factory>, facets=None, facets_reason=None, reason=None)#
class osprey_connectors.directory.DirectoryQuery(*, words='', name=None, properties=<factory>, status=None, server=(), channel_type=(), page=0, page_size=50)[source]#

Bases: object

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]#
status: str | None = None#
server: tuple[str, ...] = ()#
channel_type: tuple[str, ...] = ()#
page: int = 0#
page_size: int = 50#
__init__(*, words='', name=None, properties=<factory>, status=None, server=(), channel_type=(), page=0, page_size=50)#
class osprey_connectors.directory.DirectoryRecord(*, row, properties=<factory>, tags=<factory>)[source]#

Bases: object

One PV in full. Every property is optional and a string, as measured.

row: DirectoryRow#
properties: Mapping[str, str]#
tags: list[str]#
__init__(*, row, properties=<factory>, tags=<factory>)#
class osprey_connectors.directory.DirectoryRow(*, name, status=None, description=None, channel_type=None, server=None, host=None, last_announced=None)[source]#

Bases: object

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#
__init__(*, name, status=None, description=None, channel_type=None, server=None, host=None, last_announced=None)#

What is alarming now, per the AlarmState contract.

The backends are the underscore-private modules beside this one, which the factory reaches from their type names.

class osprey_connectors.alarm_state.AlarmConfigRecord(*, in_tree, path=None, guidance=None, displays=None, enabled=None, latching=None)[source]#

Bases: object

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#
__init__(*, in_tree, path=None, guidance=None, displays=None, enabled=None, latching=None)#
class osprey_connectors.alarm_state.AlarmState(spec, *, project_dir=None, **seams)[source]#

Bases: _Backend, ABC

Follow a live alarm feed.

start() begins whatever feeds the snapshot and 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.

abstractmethod async start()[source]#

Begin feeding the snapshot.

abstractmethod async aclose()[source]#

Stop feeding the snapshot.

abstractmethod async state_for(channel, deadline)[source]#

The alarm state of channel, waiting up to deadline seconds for catch-up.

None is a caught-up feed that holds none for it.

Return type:

AlarmStateRecord | Unavailable | None

abstractmethod async states(deadline)[source]#

Every channel’s alarm state, waiting up to deadline seconds for catch-up.

Before catch-up it answers as state_for() does, never an empty list.

Return type:

AlarmStates | Unavailable

abstractmethod async config_for(channel, deadline)[source]#

The live alarm configuration of channel, waiting up to deadline seconds for catch-up.

Return type:

AlarmConfigRecord | Unavailable

abstractmethod async probe(deadline)[source]#

Whether the service answers: the evidence in plain words, or why not.

Return type:

str | Unavailable

class osprey_connectors.alarm_state.AlarmStateRecord(*, severity=None, status=None, latched=False, acknowledged=False, message=None, time=None, stale=False)[source]#

Bases: object

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#
__init__(*, severity=None, status=None, latched=False, acknowledged=False, message=None, time=None, stale=False)#
class osprey_connectors.alarm_state.AlarmStateRow(*, channel, path, state)[source]#

Bases: object

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#
__init__(*, channel, path, state)#
class osprey_connectors.alarm_state.AlarmStates(*, rows, stale, last_contact)[source]#

Bases: object

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]#
__init__(*, rows, stale, last_contact)#
osprey_connectors.alarm_state.severity_rank(severity)[source]#

The severity’s rank, higher is worse; an unknown one ranks highest, never as recovered.

Return type:

int

Logged alarm history and configuration, per the AlarmLog contract.

The backends are the underscore-private modules beside this one, which the factory reaches from their type names.

class osprey_connectors.alarm_log.AlarmHistoryRow(*, time=None, severity=None, status=None, message=None, user=None, kind='state')[source]#

Bases: object

One logged alarm event, as the logger recorded it.

time: str | None = None#
severity: str | None = None#
status: str | None = None#
message: str | None = None#
user: str | None = None#
kind: Literal['state', 'config'] = 'state'#
__init__(*, time=None, severity=None, status=None, message=None, user=None, kind='state')#
class osprey_connectors.alarm_log.AlarmLog(spec, *, project_dir=None, **seams)[source]#

Bases: _Backend, ABC

Read an alarm logger.

abstractmethod async history(channel, since, limit, deadline)[source]#

The logged alarm events of channel, AlarmHistoryRow rows, newest first.

Return type:

HistoryPage[AlarmHistoryRow]

abstractmethod async config_for(channel, deadline)[source]#

The last logged alarm configuration of channel.

Return type:

AlarmConfigRecord | Unavailable

abstractmethod async probe(deadline)[source]#

Whether the service answers: the evidence in plain words, or why not.

Return type:

str | Unavailable

Logged channel writes, per the PutLog contract.

The backends are the underscore-private modules beside this one, which the factory reaches from their type names.

class osprey_connectors.put_log.PutLog(spec, *, project_dir=None, **seams)[source]#

Bases: _Backend, ABC

Read a log of channel writes.

abstractmethod async history(channel, since, limit, deadline)[source]#

The logged writes of channel, PutRow rows, field puts included, newest first.

Return type:

HistoryPage[PutRow]

abstractmethod async probe(deadline)[source]#

Whether the service answers: the evidence in plain words, or why not.

Return type:

str | Unavailable

class osprey_connectors.put_log.PutRow(*, at=None, channel=None, field=None, old=None, new=None, user=None, client=None)[source]#

Bases: object

One logged write, as the log recorded it.

channel is what was written: an EPICS PV, a Tango attribute, a DOOCS property. field is an EPICS field put’s .HIHI, else None.

at: str | None = None#
channel: str | None = None#
field: str | None = None#
old: object = None#
new: object = None#
user: str | None = None#
client: str | None = None#
__init__(*, at=None, channel=None, field=None, old=None, new=None, user=None, client=None)#

Which source answers each directory section on each control target, in one place.

A deployment carries one pv_directory: block and a session can be pointed at up to three machines. A section answers only from the machine the session is on, so service_targets() says which source that is per target, and a reader holding None says “not available for this target”: never another machine’s data under the selected machine’s name.

row

va

live and standin

directory

simulator_view when simulator.has_simulator

the section’s type

alarm_state

alarm_replay when replay_file is set

the sub-block’s type

alarm_log

None

the sub-block’s type

put_log

None

the sub-block’s type

The facility’s services belong to the facility’s machine and the stand-in rehearses that machine, as osprey_connectors.archive_targets has it, so the two share APPLIANCE_TARGETS and a standin spec is marked rehearsal. A simulator spec carries none of the facility’s settings, and a facility spec no replay_file. replay_file is passed verbatim: only the framework reads its demo: spelling.

Pure, and never raises: the answer is a function of the mapping alone. A block that is not a mapping, or a type or replay_file that is not a non-blank string, names no source; refusing such a block at build is resolve_section’s job in the framework.

osprey_connectors.service_targets.service_targets(config)[source]#

The source of every section on every target, per the module table.

Parameters:

config (Mapping[str, object]) – The full config mapping, as loaded from config.yml: not the pv_directory: section, because the va half turns on whether the deployment built a simulator.

Returns:

{kind: {target: BackendSpec | None}} with every target of CONTROL_TARGETS in every row. With no section, every entry is None.

Return type:

dict[str, dict[str, BackendSpec | None]]