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:
objectOne backend to build;
service_targetsmakes 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.
rowsare the records of the kind that answered.- 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:
StrEnumHow a lookup ended.
NOT_LISTEDis 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:
objectWhich kind of service, on which machine, an answer came from.
serviceis the backend’s type name;rehearsalis true onstandin.- 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)#
Bases:
objectThe service gave no answer, and why, in words a reader can act on.
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,ABCSearch 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, notNOT_LISTED.- Return type:
- 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:
objectOne page of a search.
searchedis the search in plain words andrequestthe literal request sent.partiallists{part, reason}for what missed the deadline;facetsmaps a row field to{value, count}lists, and isNonewithfacets_reasonwhen it could not be computed.- searched: str#
- request: str#
- 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:
objectOne 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
propertiesstays 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:
objectOne 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:
objectOne channel, as the directory lists it.
serveris the process serving the channel andchannel_typeits type there: EPICS RecSync’siocNameandrecordType, a Tango database’s device-server instance and device class, a DOOCS ENS server name and device type.last_announcedis RecSync’stimeor 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:
objectOne 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,ABCFollow a live alarm feed.
start()begins whatever feeds the snapshot andaclose()ends it; both are idempotent. Until the feed has caught up, reads answerUnavailable("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 neverin_tree: "no". A read of a started feed waits for catch-up up to its deadline and only then answersalarm feed still loading; a feed that already knows its answer, unreachable or unbuildable, answers at once.- abstractmethod async state_for(channel, deadline)[source]#
The alarm state of channel, waiting up to deadline seconds for catch-up.
Noneis 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:
- abstractmethod async config_for(channel, deadline)[source]#
The live alarm configuration of channel, waiting up to deadline seconds for catch-up.
- Return type:
- 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:
objectWhat 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:
objectOne channel the feed holds a state for.
channelis the channel address;pathis the alarm-tree place the state was reported under,Nonefor a backend with no tree. Tango alarm devices and DOOCS alarm servers fillpathwhere 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:
objectEvery channel’s alarm state now, and the counts per severity.
countsis derived from the rows’ severities,OKincluded and aNoneseverity not counted, so it cannot disagree with them.last_contactis the ISO-8601 UTC time the backend last heard from the feed (a message or an offset check),Nonewhen it never has;staleis 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:
objectOne 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,ABCRead an alarm logger.
- abstractmethod async history(channel, since, limit, deadline)[source]#
The logged alarm events of channel,
AlarmHistoryRowrows, newest first.- Return type:
- abstractmethod async config_for(channel, deadline)[source]#
The last logged alarm configuration of channel.
- Return type:
- 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,ABCRead a log of channel writes.
- abstractmethod async history(channel, since, limit, deadline)[source]#
The logged writes of channel,
PutRowrows, field puts included, newest first.- Return type:
- 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:
objectOne logged write, as the log recorded it.
channelis what was written: an EPICS PV, a Tango attribute, a DOOCS property.fieldis an EPICS field put’s.HIHI, elseNone.- 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 |
|
|
|---|---|---|
|
|
the section’s |
|
|
the sub-block’s |
|
|
the sub-block’s |
|
|
the sub-block’s |
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 thepv_directory:section, because thevahalf turns on whether the deployment built a simulator.- Returns:
{kind: {target: BackendSpec | None}}with every target ofCONTROL_TARGETSin every row. With no section, every entry isNone.- Return type:
dict[str, dict[str, BackendSpec | None]]