Building Connectors#
The factory that builds a connector from its type name, the type names themselves, and the readers every connector shares for its connection block and its call bound.
Connector factory for control system and archiver connectors and the service backends.
Provides centralized factory for instantiating and configuring connectors
based on configuration. Connectors are registered through the Osprey registry
system for unified component management and lazy loading. The four read-only
service kinds (directory, alarm_state, alarm_log, put_log) are
registered and built through one kind-keyed pair, ConnectorFactory.register_service()
and ConnectorFactory.create_service().
- osprey_connectors.factory.BUILTIN_CONNECTORS: tuple[BuiltinConnector, ...] = (BuiltinConnector(name='epics', kind='control_system', module_path='osprey_connectors.control_system._epics_connector', class_name='EPICSConnector', description='EPICS Channel Access control system connector'), BuiltinConnector(name='virtual_accelerator', kind='control_system', module_path='osprey_connectors.control_system._va_connector', class_name='VirtualAcceleratorConnector', description='Virtual Accelerator connector for PyAT-backed soft-IOC simulations'), BuiltinConnector(name='doocs', kind='control_system', module_path='osprey_connectors.control_system._doocs_connector', class_name='DOOCSConnector', description='DOOCS control system connector (requires doocs4py)'), BuiltinConnector(name='tango', kind='control_system', module_path='osprey_connectors.control_system._tango_connector', class_name='TangoConnector', description='TANGO Controls control system connector (requires PyTango)'), BuiltinConnector(name='live_standin', kind='control_system', module_path='osprey_connectors.control_system._epics_connector', class_name='EPICSConnector', description='Live stand-in connector: the facility-shaped soft IOC a deployment runs for itself, served over Channel Access'), BuiltinConnector(name='mock_archiver', kind='archiver', module_path='osprey_connectors.archiver._mock_archiver_connector', class_name='MockArchiverConnector', description='Mock archiver connector for development and testing'), BuiltinConnector(name='epics_archiver', kind='archiver', module_path='osprey_connectors.archiver._epics_archiver_connector', class_name='EPICSArchiverConnector', description='EPICS Archiver Appliance connector'), BuiltinConnector(name='mongodb_archiver', kind='archiver', module_path='osprey_connectors.archiver._mongodb_archiver_connector', class_name='MongoDBArchiverConnector', description='MongoDB archiver connector for time-series PV data'), BuiltinConnector(name='doocs_archiver', kind='archiver', module_path='osprey_connectors.archiver._doocs_archiver_connector', class_name='DOOCSArchiverConnector', description='DOOCS local history connector (requires doocs4py)'), BuiltinConnector(name='mya_archiver', kind='archiver', module_path='osprey_connectors.archiver._mya_archiver_connector', class_name='MYAArchiverConnector', description='MYA archiver connector, read over the myquery HTTP service (requires jlab-archiver-client)'))#
Every built-in connector, in registration order.
- class osprey_connectors.factory.BuiltinConnector(name, kind, module_path, class_name, description)[source]#
Bases:
objectOne connector this package ships, as a registry names it.
The module path names an implementation module of this package, which only this table spells: a registry that loads connectors lazily by path takes its entries from here rather than restating the private paths.
- name: str#
The type name a config selects it by, and the key it registers under.
- kind: Literal['control_system', 'archiver']#
Which registry it goes into, and the
connector_typea registration names.
- module_path: str#
- class_name: str#
- description: str#
- load()[source]#
Import the module and return the connector class.
- Raises:
TypeError – The class is not a subclass of the base its kind names.
- Return type:
- __init__(name, kind, module_path, class_name, description)#
- class osprey_connectors.factory.ConnectorFactory[source]#
Bases:
objectFactory for control system and archiver connectors and the service backends.
Provides centralized management of available connectors. Connectors are registered automatically through the Osprey registry system during framework initialization. A control system or archiver is built from a config dict and connected; a service backend (kind
directory,alarm_state,alarm_logorput_log) is built from aBackendSpecbycreate_service()and connects nothing.Example
>>> # Using default config >>> cs_connector = await ConnectorFactory.create_control_system_connector() >>> >>> # Using custom config >>> config = {'type': 'epics', 'connector': {'epics': {...}}} >>> cs_connector = await ConnectorFactory.create_control_system_connector(config)
- classmethod register_control_system(name, connector_class)[source]#
Register a control system connector.
- Parameters:
name (str) – Unique name for the connector (e.g., ‘epics’, ‘tango’)
connector_class (type[ControlSystemConnector]) – Connector class implementing ControlSystemConnector
- classmethod register_archiver(name, connector_class)[source]#
Register an archiver connector.
- Parameters:
name (str) – Unique name for the connector (e.g., ‘epics_archiver’, ‘mock_archiver’)
connector_class (type[ArchiverConnector]) – Connector class implementing ArchiverConnector
- classmethod register_service(kind, name, backend_class)[source]#
Register a service backend under the type name a
BackendSpecselects it by.- Parameters:
kind (str) –
directory,alarm_state,alarm_logorput_log.name (str) – The type name.
backend_class (type[_ServiceBackend]) – A subclass of that kind’s base.
- Raises:
ValueError – kind is not one of the four.
- classmethod build_control_system_connector(config=None, *, control_target=None)[source]#
Build a control system connector and its type config, without connecting.
- Parameters:
config (Mapping[str, object] | None) –
Control system configuration dict, or None to read the
control_systemsection of the config this process loads (seeosprey_connectors.config.get_config_value()). Its keys:type: Connector type (e.g., ‘epics’, ‘virtual_accelerator’). Defaults to the simulator served in process, with a warning, when unset, so an under-specified config never reaches live hardware.
connector: Dict with connector-specific configs
control_target (str | None) – The control target this connector is being built for —
live,vaorstandin. Stamped on the instance as_control_targetand used to index the per-target narrowing in the control-context record, and nothing else: the deployment half of the write posture stays keyed on the connector type. Callers that have no target to name leave itNone, which is the behaviour every caller had before the stamp existed.
- Returns:
(connector, type_config)— the stamped but unconnected connector, and the type-specific config blockconnect()takes. Both halves are needed to finish the build, and the second is not derivable from the first, so they travel together.- Raises:
ValueError – If connector type is unknown or config is invalid: a dotted type that names no
ControlSystemConnectorsubclass, or a section,connectorblock or type block that is not a mapping.FileNotFoundError – If
configis None and no config is found. The error names where it looked; nothing is built in its place.
- Return type:
tuple[ControlSystemConnector, dict[str, object]]
Example
>>> connector, type_config = ConnectorFactory.build_control_system_connector(config) >>> await connector.connect(type_config)
- async classmethod create_control_system_connector(config=None, *, control_target=None)[source]#
Create, configure and connect a control system connector.
The whole build in one call, and what almost every caller wants.
build_control_system_connector()is the same build stopped one step short, for the one caller that has to reach the instance between the type stamp andconnect().- Parameters:
config (Mapping[str, object] | None) – Control system configuration dict, as
build_control_system_connector()documents it.control_target (str | None) – The control target this connector is being built for, stamped on the instance as
build_control_system_connector()documents it.
- Returns:
Initialized and connected ControlSystemConnector
- Raises:
ValueError – If connector type is unknown or config is invalid
ConnectionError – If connection fails
- Return type:
Example
>>> config = { >>> 'type': 'epics', >>> 'connector': { >>> 'epics': { >>> 'timeout_s': 5.0, >>> 'gateways': {'read_only': {...}} >>> } >>> } >>> } >>> connector = await ConnectorFactory.create_control_system_connector(config)
- async classmethod create_archiver_connector(config=None)[source]#
Create and configure an archiver connector.
- Parameters:
config (Mapping[str, object] | None) –
Archiver configuration dict, or None to read the
archiversection of the config this process loads (seeosprey_connectors.config.get_config_value()). Its keys:type: Connector type (e.g., ‘epics_archiver’, ‘mock_archiver’). Defaults to ‘mock_archiver’ with a warning when unset, so a config that omits the archiver section stays serviceable.
settings: The selected connector’s settings, handed to connect() whole. A short-named connector’s own-name block is read when settings is absent; both at once raise ValueError.
- Returns:
Initialized and connected ArchiverConnector
- Raises:
ValueError – If connector type is unknown or config is invalid: a dotted type that names no
ArchiverConnectorsubclass, or a section that is not a mapping.FileNotFoundError – If
configis None and no config is found. The error names where it looked; nothing is built in its place.ConnectionError – If connection fails
- Return type:
Example
>>> config = { >>> 'type': 'epics_archiver', >>> 'settings': { >>> 'url': 'https://archiver.example.org:8443', >>> 'timeout_s': 60 >>> } >>> } >>> connector = await ConnectorFactory.create_archiver_connector(config)
- async classmethod create_service(spec, *, project_dir=None, **seams)[source]#
Build the service backend a spec names. Backends connect nothing here: no I/O.
The kind is
spec.kind. The builtins are registered first: the panel and the directory MCP server never register them themselves, and registration converges, so every create call can afford to.- Parameters:
spec (BackendSpec) – The backend to build, from
service_targetsor written by hand.project_dir (Path | None) – The rendered config’s directory.
**seams (object) – Test seams, passed on only when not
None.
- Raises:
ValueError – The kind is not one of the four, the type is unknown, or a dotted type does not resolve to a subclass of one of the four service bases.
- Return type:
_ServiceBackend
- osprey_connectors.factory.register_builtin_connectors()[source]#
Register all built-in control system and archiver connectors and service backends.
Safe to call multiple times and convergent: every call ensures each built-in name is registered, and an existing registration under one of those names is never replaced. A registry holding only part of the built-ins (e.g., one that was cleared and then partially repopulated) therefore heals on the next call instead of keeping the truncated set.
Connector type constants, and the fallbacks a factory applies to them.
Single source of truth for built-in connector type name strings. Custom connectors use dotted module paths (e.g., ‘mypackage.SiteConnector’) and don’t need constants here.
The resolvers at the bottom are here rather than in
osprey_connectors.factory so that a guard deciding what a deployment
will build can share them with the factory that builds it. A guard which
re-implements “what does this config select” is a guard that can disagree with
the answer, and the disagreement is a bypass rather than a discrepancy — see
osprey_connectors.honesty.
resolve_archiver_settings() is the same arrangement for the other half of
an archiver selection: which block its connect() is handed. The build
refuses what it would refuse, from the same helpers.
resolve_target() extends that to the run-time question “which machine is
this session pointed at”. It is the same shape of answer for the same reason:
several holders follow a control target — the connector-host process, its child,
an executor sandbox — and a holder that translates live into a connector type
privately can route a tool call somewhere the roster never claimed. A target
names a machine, and there are three of them: the facility’s own control
system (live), the virtual accelerator (va), and the live stand-in
(standin) — a soft IOC a deployment runs for itself, which is a third
machine with a connector block of its own rather than a mode of the first. That
is what keeps live meaning the machine the facility authored on a deployment
that runs the stand-in beside it. The target is an argument here, never
something this module reads from the environment: an environment-reading
override would make the honesty predicate describe a deployment the process is
no longer running.
tier_writes() answers “how far may this deployment write” from the one tier key,
control_system.writes, for the same reason. The lint that reads the config,
the profile card that tells an operator what they hold, and the connector that
would perform the write all have to agree about the answer. Two readings of one
posture is one of them being wrong about a machine somebody can move.
LimitsPosture is the same story for limits checking, which is likewise
per connector type: a deployment may run its simulator optional while its
live machine runs exclusive. It carries the resolved posture together
with the config key that answered it, so a refusal names the line an operator
would have to edit rather than one some per-type block overrides.
Where the write tier reads an unusable value as never and is done, the
limits family cannot: “no limits checking configured” is itself a permissive
answer, so a leaf written as something no reader can turn into a boolean is
reported as a block that failed to state it rather than as a block that stated
nothing. Such a posture answers neither leaf, and a caller that must act blocks
every write instead of waving them through unchecked.
- osprey_connectors.types.DEFAULT_VA_PORT = 5064#
Channel Access port the shipped Virtual Accelerator soft-IOC serves on. It is here rather than only in the VA connector because the deployment layer fills the same default when it dials the VA, and it must not import a concrete connector (and the EPICS client stack behind it) to learn one integer.
- osprey_connectors.types.INVENTED_HISTORY_TYPES = ('virtual_accelerator', 'live_standin')#
Types whose history is invented rather than recorded, so pairing one with a synthesizing archiver leaves nothing that ever tells a reader the data is made up. Both are machines a deployment stands up for itself, and neither has an archive of its own — see
osprey_connectors.honesty.
- osprey_connectors.types.LIMITS_CHECKING_LEAF = 'limits_checking'#
The limits block’s own name, both deployment-wide (
control_system.limits_checking) and inside one connector block (control_system.connector.<type>.limits_checking). One name because it is one block at two scopes, the per-type one overriding the other whole.
- osprey_connectors.types.LIMITS_LEAVES = ('enabled', 'mode')#
The leaves a limits block has to state to answer at all.
database_pathis deliberately not among them: the deployment mounts one limits database, so a per-type block that omits the path is complete rather than incomplete.
- osprey_connectors.types.LIMITS_MODE_EXCLUSIVE = 'exclusive'#
the limits database is the complete list of writable channels, and a channel with no record is refused.
optional: a channel with a record is checked against it, and a channel with no record is written with no limits.- Type:
The two limits modes.
exclusive
- osprey_connectors.types.LIVE_STANDIN = 'live_standin'#
a facility-shaped soft IOC a deployment runs for itself. A connector type of its own — served by the EPICS connector, but keyed apart from
epicsso that the facility’s authoredepicsblock stays the one thinglivecan mean, and the stand-in gets its owncontrol_system.connector.live_standinblock to be configured from.- Type:
The live stand-in
- class osprey_connectors.types.LimitsPosture(enabled, mode, connector_type, incomplete=())[source]#
Bases:
objectA resolved limits posture, together with the config key that answered it.
The value and its key travel as one because a refusal has to send an operator to the line they can actually edit. A deployment that set
mode: optionalfor its simulator alone has two keys in play, and a refusal naming the deployment-wide one would have the operator flip a line the per-type block overrides — a change that does nothing, on a posture they did not mean to touch. Resolving the value without carrying its key back is what makes that mistake available, so this type does not offer the value on its own.Both leaves are tri-state.
Noneis “no block said”, which is not the same as a block stating a value: silence is what a deployment that never configured limits checking has, and every write path treats it as no permission rather than as a decision. OnlyLIMITS_LEAVESare carried; the limits database path stays deployment-wide.- Variables:
enabled (bool | None) – Whether limits checking is on, or
Nonewhen unstated.mode (str | None) – One of
LIMITS_MODES, orNonewhen unstated. Write paths write a channel with no record only onoptional.connector_type (str | None) – The connector type whose block answered, or
Nonewhen the deployment-wide block did. It selects the key spelling and nothing else.incomplete (tuple[str, ...]) – The
LIMITS_LEAVESthe answering block failed to state, inLIMITS_LEAVESorder — a leaf a per-type block omitted, or a leaf either block wrote as something no reader can use. Empty for a well-formed block. A non-empty value means the posture answered nothing — both leaves areNone— and a reader that must act builds a failsafe rather than guessing which half of the block was meant. The one posture not read from a single block,most_restrictive_limits_posture()’s fold, may carry definite leaves beside a non-empty tuple; readers check this field first for exactly that reason.
- enabled: bool | None#
- mode: str | None#
- connector_type: str | None#
- incomplete: tuple[str, ...] = ()#
- key(leaf)[source]#
The config key this posture’s leaf was read from.
control_system.connector.<type>.limits_checking.<leaf>when a connector block answered, andcontrol_system.limits_checking.<leaf>when the deployment-wide block did. A custom connector’s dotted module path ('mypackage.SiteConnector') is one key and is interpolated whole, never split on its dots.A posture holding no type at all — the deployment-wide answer, and the fallback a target that resolves to no type gets — spells the deployment-wide key, which is where such a posture was read from anyway.
- Parameters:
leaf (str) – One of
LIMITS_LEAVES.- Returns:
The dotted key, as a caller spells it for
get_config_valueand as a refusal names it to an operator.- Return type:
str
- property block_key: str#
The dotted key of the whole
limits_checkingblock, without a leaf.What a refusal names when the block itself is the problem — it is not a mapping, or it failed to state leaves an operator now has to go and write. Spelled off
key()rather than rebuilt, so a refusal about a block and a refusal about one of its leaves cannot disagree about where the block is.
- property strict: bool#
Whether this posture refuses everything the limits database does not list.
Limits checking on and the mode explicitly
exclusive— the only definition of “strict” in the codebase, so the target roster and the docs cannot drift into two readings of one word.Explicit on both leaves:
Noneis a deployment that never stated a posture, and a deployment that stated nothing has refused nothing. Counting silence as strict would advertise a guarantee no config line backs, on exactly the deployments least likely to have checked.
- __init__(enabled, mode, connector_type, incomplete=())#
- osprey_connectors.types.RETIRED_CONTROL_SYSTEM_TYPES = {'mock': 'virtual_accelerator'}#
Type names no deployment may state any more, each with the type that now means it. A table rather than a missing registration, so that every site refusing one says what to write instead.
- osprey_connectors.types.SERVING_LEAF = 'serving'#
The leaf under
control_system.connector.virtual_acceleratorthat says where the simulator runs:servedfrom its container over Channel Access, orin_processinside the process that asks, with no network at all.
- osprey_connectors.types.SET_CONTROL_SYSTEM_TYPES = ['epics', 'virtual_accelerator', 'doocs', 'tango', 'live_standin']#
Settable, not initable. A deployment may be pointed at its stand-in once it has one —
osprey set connector=live_standinis how a session starts on the soft IOC — butosprey initnever offers it: a fresh project has no stand-in to point at, so a project that began on one would name a machine that does not exist. Hence one list for what theconnector:shorthand accepts and another, narrower one for whatinitwill materialize.
- osprey_connectors.types.SIMULATED_TYPES = ('virtual_accelerator',)#
Types that serve a machine nobody has to be careful around. They are the reason
livecannot simply be “whatever the config selects”: a deployment whose baseline is one of these has not yet said what its real machine is.
- osprey_connectors.types.STANDIN_TYPES = ('live_standin',)#
Types that serve the live stand-in. Reachable only through the
standintarget: a stand-in is a machine in its own right, so it is never a candidate for a deployment’sliveone — not as the baseline the derivation starts from, and not as a block it falls back to. A deployment running the stand-in beside its facility’s own block still has exactly one real machine.
- osprey_connectors.types.TIER_WORDS: tuple[Literal['never'], Literal['asked'], Literal['allowed']] = ('never', 'asked', 'allowed')#
every answer
tier_writes()gives.- Type:
The three tier words, narrowest first
- osprey_connectors.types.TierWord#
a member of
TIER_WORDS.- Type:
One tier word, as a type
alias of
Literal[‘never’, ‘asked’, ‘allowed’]
- osprey_connectors.types.UNSET_TYPE_WARNING = "control_system.type is not set; defaulting to 'virtual_accelerator' served in process (no network). Set control_system.type explicitly to select a connector."#
What a factory says when it builds from a section that states no type.
- osprey_connectors.types.WRITES_KEY = 'control_system.writes'#
The login tier’s write ceiling, dotted as a caller spells it for
get_config_value:"never","asked"or"allowed", the furthest position a login may pick. Target-blind — a tier that allows writes allows them for every machine, and which machine is actually written is the session’s switch to decide, not the tier’s. Read bytier_writes(); when the key is absent the tier isnever.
- osprey_connectors.types.archiver_settings_errors(section)[source]#
Every block under a rendered
archiver:section that no archiver reads, named.A lint, like
incomplete_limits_blocks(), and read by the build over the config a deployment runs. It reports, in section order: each mapping under a key no reader takes (anything but_ARCHIVER_SECTION_LEAVES, a built-in archiver’s name, or the selected type’s own name when it has no dot); then the two refusalsresolve_archiver_settings()raises, in its words. A scalar is not a block and is not reported. Never raises.- Return type:
list[str]
- osprey_connectors.types.archiver_settings_key(section)[source]#
The dotted key of the block that configures section’s archiver.
archiver.<type>when a short-named archiver is configured by its own-name block alone, elsearchiver.settings— so a message about a setting names the line an operator actually wrote.- Return type:
str
- osprey_connectors.types.baseline_target(section)[source]#
The target a deployment’s own
control_system:section selects.vafor the simulator, in whichever venue its leaf names (a section that states no type is the simulator in process, so it is onva),standinfor the live stand-in, andlivefor every real control system.Beside
resolve_control_system_type()rather than restated by each holder, because “which target am I on when nobody has switched” is asked by the supervisor, the switch predicate below, and every baseline-pinned reader — and three answers to it is three ways for one deployment to be described.- Return type:
Literal[‘live’, ‘va’, ‘standin’]
- osprey_connectors.types.configured_targets(section)[source]#
The targets a session on this deployment can actually be pointed at.
In
CONTROL_TARGETSorder, which is the order every render, roster and state file reads them in. The deployment’sbaseline_target()is always one of them — a session sits on it whether or not the config wrote a block for the connectorcontrol_system.typebuilds — and each of the others is here whentarget_configured()says so, which is the same resolve-and-read-the-block pairswitch_capable()and the deployment layer’s Reach Contracts decide it by.The order is the constant’s and not the baseline’s, so a deployment that gained no target gains no reordering: the two-target deployments that have no stand-in enumerate exactly as they did before
standinexisted, down to the order their renderedsettings.jsonlists them in.This list, and never the constant, is what an enumerator walks — a roster, a prober, a posture render, a state file.
CONTROL_TARGETSis the vocabulary: it grows when a new kind of machine exists, and a holder that loops it hands every deployment a slot for every machine anybody could run. Widening it to three would otherwise grow astandinrow, probe and posture on deployments with nocontrol_system.connector.live_standinblock at all — a machine that is not there, described as if it were. Which targets are configured is a property of the rendered config, so it is read from the config.- Parameters:
section (object) – The
control_system:config section, in the same shaperesolve_control_system_type()takes.- Returns:
The configured targets in
CONTROL_TARGETSorder, the baseline among them. Never raises and never empty: a section that is missing or malformed still has a baseline, and that one target is what such a deployment is on.- Return type:
list[Literal[‘live’, ‘va’, ‘standin’]]
- osprey_connectors.types.connector_transport(section, connector_type=None)[source]#
The wire a connector built from section speaks.
Computed once, here, from the type and the serving leaf, so every check that asks “does this speak Channel Access” or “does this dial a network” reads one derived fact and never the type word. connector_type defaults to
resolve_control_system_type()of section; a caller building for a target passes the type the target resolves to.- Returns:
TRANSPORT_IN_PROCESSfor the simulator served in process, the type’s_TRANSPORTSrow otherwise, andNonefor a type with no row (a dotted custom connector).- Raises:
ValueError – when the serving leaf holds an unknown value.
- Return type:
str | None
- osprey_connectors.types.incomplete_limits_blocks(section)[source]#
Every half-written per-type limits block in a rendered section, named.
A per-type
limits_checkingblock overrides whole, so a block that states one leaf states no posture at all:type_limits_posture()answersNonetwice for it and a write path that must act builds a failsafe. The build andosprey validaterefuse such a config outright rather than ship a deployment whose limits posture silently stopped working, and this is what they read to do it — the rendered config itself, so a spelling the profile layer could not classify is still caught before it reaches a machine.A lint and not a posture: it answers about a section rather than about a target, and each line it emits names the key an operator has to fix. It reports exactly what
type_limits_posture()reads as a block that failed to state a leaf — the two share_unstated_limits_leaves(), so a config the build accepts and one the runtime enforces cannot come apart — which is the two failures a block can have:A per-type block that omits a leaf. The deployment-wide block is not reported for an omission: it inherits nothing, so a leaf it never carried is the tri-state’s
Noneand the shape every deployment predating per-type blocks has.Either block writing a leaf as something no reader can use — for
enableda quoted'true', a1, a bareenabled:, an unexpanded'${LIMITS_ON}'; formodeanything but one ofLIMITS_MODES. Environment expansion yields strings, so this is what a deployment gets when it wires a limits leaf to a variable nothing set. It blocks every write at runtime, which is the safe direction but a poor way to find out; refusing the build is where that config is cheap to fix.Either
limits_checkingbeing present but not a mapping at all, which gets one line naming the block and quoting what was found there instead of a line per leaf: there are no leaves to name.The deployment-wide block carrying a leaf outside
_LIMITS_BLOCK_LEAVES, or a per-type block one outsideLIMITS_LEAVES. No reader consults such a leaf, so the posture its author meant by it is not the one the deployment runs.
- Parameters:
section (object) – The
control_system:config section, in the same shaperesolve_control_system_type()takes — the rendered one, as the build produced it, since that is the config a deployment runs.- Returns:
the deployment-wide block first, then the connector blocks in the order the section carries them, leaves in
LIMITS_LEAVESorder and undefined leaves sorted after them, so one refusal lists everything an operator has to fix. Empty for a section whose blocks are complete, absent, or not blocks at all. Never raises: a lint that crashed on a malformed config would fail a build without saying what is wrong with it.- Return type:
One line per unstated leaf and per undefined one
- osprey_connectors.types.is_simulated(connector_type)[source]#
Whether a connector type serves the simulator rather than a machine.
A type predicate: the simulator answers True whether it is served or runs in process. It never says whether a connector dials a network; that is
speaks_channel_access()andtalks_to_network().- Return type:
bool
- osprey_connectors.types.limits_database_required(posture, *, path_configured)[source]#
Whether a target with this limits posture needs a limits database.
The one answer every caller gives before it demands the file — the connector’s validator, the compose mount, the build check, a service start and the bridge’s startup gate — so none of them can refuse a deployment another one runs.
A database is required when limits checking is on and either the mode is not
optionalor a path is configured.optionalwith no path is a deployment that legitimately keeps no limits file: every channel is unlisted, and an unlisted channel is written with no limits, so there is no file whose absence could matter. An unstated mode counts as not optional, because silence is no permission to skip the database. A path that is configured is always required, so a configured file that fails to load stays a refusal everywhere rather than quietly checking nothing.- Parameters:
posture (LimitsPosture) – The resolved posture of the target being asked about.
path_configured (bool) – Whether the caller’s own config names a limits database path (the live lookup at runtime, the rendered config at render and build time).
- Returns:
Truewhen a limits database must exist and load.- Return type:
bool
- osprey_connectors.types.machine_kind(section, target)[source]#
The kind of machine target names by its name:
realorsimulator.liveandstandinare the real machine,vathe simulator. The name never answersrehearsal: whether astandintarget really is this deployment’s stand-in is an endpoint fact only the controls server’s report states, read bypublished_machine_kind().Nonewhenresolve_target()cannot resolve the target in this deployment — an unknown target, orliveon a deployment that never named its real machine. Never raises.- Return type:
Literal[‘real’, ‘rehearsal’, ‘simulator’] | None
- osprey_connectors.types.most_restrictive_limits_posture(section)[source]#
The limits posture that holds across every target a session here can select.
What a caller with no target of its own has to assume. The stdlib hook is the one that needs it: when the deployment’s control target cannot be read — no state written yet, an unreadable state directory, a target that resolves to nothing — it still has to decide about a write, and the machine it is deciding about is any of the reachable ones.
The reachable set is every
configured_targets()when the deployment renders the switch (switch_capable()), and otherwise the single connectorcontrol_system.typebuilds, read by type throughtype_limits_posture(). Reading the baseline by type rather than by target is what keeps a deployment without the switch from folding a second block’s relaxation into an answer no session here could ever reach; and walking the configured targets rather thanCONTROL_TARGETSkeepstarget_limits_posture()’s unresolvable-target fallback from voting for a machine nobody stood up.The two leaves fold in opposite directions, each toward the answer that costs a config edit rather than a machine:
enabledisTruewhen any reachable posture has itTrue. Limits checking being on somewhere is a constraint that may apply to the write in hand.modeisoptionalonly when every reachable posture isoptional. Permission to write a channel the limits database does not list holds only where every machine grants it, so oneexclusivetarget — or one that states nothing,Noneand an incomplete block alike counting as not-optional— makes the answerexclusive.
Incompleteness travels with them, as the union of every reachable posture’s
LimitsPosture.incompleteinLIMITS_LEAVESorder. One reachable machine whose block cannot be read makes the fold incomplete, and a reader that must act therefore builds the blocking failsafe. Dropping it would be the worst failure available here: theenabledfold sends an incomplete posture’sNonetoFalse, which reads as “checking off” — and a validator built from that is no validator at all, so the caller with the least information about which machine it is touching would be the one waved through. This is the fail-closed directionLimitsValidator.from_config_most_restrictive()’s callers are promised.The result is derived rather than read, which is why both leaves come back definite where a single block’s would be tri-state, and why the posture carries no connector type: no per-type line answers for a union, and naming one would send an operator to edit a machine rather than the answer. The deployment-wide keys
LimitsPosture.key()then spells are the honest ones — they are the lines that decide every target that wrote no block.- Parameters:
section (object) – The
control_system:config section, in the same shaperesolve_control_system_type()takes.- Returns:
The folded
LimitsPosture, always carryingNonefor its connector type, and incomplete when any reachable posture is. Never raises and never folds an empty set:configured_targets()always holds the baseline, and a deployment that says nothing still has one target.- Return type:
- osprey_connectors.types.published_machine_kind(target, *, state_dir=None)[source]#
The kind of machine target is, as this deployment’s controls server publishes it.
The one source every surface reads (C-KIND).
standinisrehearsalonly when the first live server’s report — in the hook twin’s order, dead servers’ reports ignored — says so for it; no live report, no key, or any other value readsreal, the cautious words. So a process that sees no report (an executor sandbox, a bluesky or dispatch container, a deployment with no server running) names astandinthe real machine. Every other target answers from the name table:vais the simulator,liveand anything unknown the real machine — a report can never make them a rehearsal.- Parameters:
target (object) – The control target.
state_dir (str | PathLike[str] | None) – The directory holding the servers’ reports;
Nonereadsosprey_connectors.posture_store.state_dir().
- Returns:
real,rehearsalorsimulator. Never raises.- Return type:
Literal[‘real’, ‘rehearsal’, ‘simulator’]
- osprey_connectors.types.resolve_archiver_settings(section)[source]#
The settings block the selected archiver’s
connect()is handed.archiver.settingsfor every archiver; for a short-named one, its own-name block whensettingsis absent. Absent, or a baresettings:, is{}.- Raises:
ValueError – when both spellings are present, or the block is not a mapping.
archiver_settings_errors()refuses the same configs at build time, with the same words.- Return type:
dict[str, object]
- osprey_connectors.types.resolve_archiver_type(section)[source]#
The archiver an
archiver:config section actually selects.Absent means the mock: a config that says nothing about its archiver is a config that gets the synthesizing one, which is the fact the honesty rule is really about.
- Return type:
str
- osprey_connectors.types.resolve_control_system_type(section)[source]#
The control system a
control_system:config section actually selects.A section that states no type selects the simulator, and
resolve_serving()runs it in process, so it dials nothing. The transport (connector_transport()), never the type, says whether a connector dials a network.- Return type:
str
- osprey_connectors.types.resolve_serving(section)[source]#
Where the simulator a
control_system:section selects runs.A section that states no type is the fail-safe default, the simulator in process, and the leaf is not read: a section that names nothing must dial nothing. A stated
virtual_acceleratoranswersSERVING_KEY, elseSERVED. Any other stated type isSERVED: only the simulator has an in-process venue.- Raises:
ValueError – when the leaf holds a value outside
SERVING_MODES.- Return type:
str
- osprey_connectors.types.resolve_target(section, target)[source]#
The connector type a session target selects, in a given deployment.
The returned type is also the key of the block the factory reads its settings from —
control_system.connector.<type>— so one string answers both “what do I build” and “where are its gateways”.vaandstandinare the same answer everywhere:vais the deployment’s simulator, and the stand-in is the soft IOC the deployment runs for itself, configured from the block that carries its name. The factory servesvain the venueconnector.virtual_accelerator.servingnames, and only a deployment whose own type isvirtual_acceleratormay serve it in process; the type this function answers is the same in either venue.liveis deployment-specific and is the half that can refuse:When the section’s own type is a real control system, that is the live machine, and it is returned as written — including a value this module does not recognize, which reaches the factory’s “Unknown … type” error exactly as
resolve_control_system_type()already lets it. A second non-simulated block beside it is not a second target: no name reaches it (_ONE_REAL_MACHINE), so it is warned about rather than skipped in silence.When the section’s own type is simulated or is a stand-in (or absent, which resolves to the simulator in process), the deployment has not named its real machine there, so the live type is taken from the connector table: exactly one block that is neither simulated nor a stand-in means the deployment has said which machine it means. None, or more than one, raises. The stand-in is skipped on both sides of that derivation, so standing it up beside a facility’s
epicsblock never makesliveambiguous and never answers it with the stand-in.
Nothing is inferred from the absence of evidence. A deployment that has never been told about its real machine gets an error naming what it would have to configure, because the alternative — resolving
liveto the one connector type that talks to hardware because it is the usual one — is a tool call arriving at a real machine on the strength of a guess.- Parameters:
section (object) – The
control_system:config section, in the same shaperesolve_control_system_type()takes.target (object) – The control target, one of
CONTROL_TARGETS. An argument, never read from the environment, and never defaulted.
- Returns:
The connector type, which doubles as the connector sub-block key.
- Raises:
ValueError – If target is not a known target (including
Noneand blank), or if it isliveon a deployment with no single derivable live control system.- Return type:
str
- osprey_connectors.types.retired_type_message(value)[source]#
The one sentence every site refusing a retired type name quotes.
- Return type:
str
- osprey_connectors.types.speaks_channel_access(section, connector_type=None)[source]#
Whether a connector built from section speaks real Channel Access.
The facility’s own EPICS machine, the simulator served from its container, or the live stand-in soft IOC. The queue worker builds its devices over Channel Access, so these are the connectors plans can execute against today and every other one browses. That is a property of the worker’s device layer, not of the plan stack: a facility whose machine speaks another protocol executes plans once a device layer for it exists, and its transport joins this one — this is not a statement that no other protocol can ever run plans.
- Return type:
bool
- osprey_connectors.types.switch_capable(section)[source]#
Whether a deployment gives a session more than one target to be pointed at.
The predicate itself, in the module that already owns “which connector type does a target mean here”. Two layers ask the question and must never answer it differently: the controls server decides from it whether its tools are served by a connector-host child, and the build decides from it whether the agent’s frozen safety rule describes a switchable machine at all. A build that promises a switch the runtime will not perform is worse than one that never mentions it.
One rule: a deployment is switch-capable when its section resolves and at least two targets are configured (
configured_targets(), the same resolve-and-read-the-block enumeration every roster walks; the baseline is always one of them).Which two is not this predicate’s business: a facility rehearsing on a stand-in beside its simulator, with no live machine authored yet, has exactly the two-machine world the switch exists for — demanding the
live/vapair specifically would lock that deployment’s posture toggles for want of a machine it never claimed to have.Deliberately not checked:
probe_channel, the gateways table, the operator acknowledgment. Those decide whether a target may be switched to — a per-switch question answered with a reason the operator is told. This is the coarser question of whether the deployment is in the multi-target world.- Parameters:
section (object) – The
control_system:config section, in the same shaperesolve_control_system_type()takes. Callers holding a whole rendered config passconfig.get("control_system").- Returns:
Truewhen the section resolves and configures at least two targets. Never raises: a section that is not a mapping or does not resolve is not capable.- Return type:
bool
- osprey_connectors.types.talks_to_network(section, connector_type=None)[source]#
Whether a connector built from section dials anything at all.
False only for the simulator served in process. A transport this module has no row for (a dotted custom connector) answers True: what it dials is not known, so it is not assumed to dial nothing.
- Return type:
bool
- osprey_connectors.types.target_configured(section, target)[source]#
Whether section carries the connector block target is served by.
Both halves of “does this deployment have that machine”, asked the way the runtime asks them:
resolve_target()names the connector type the target selects HERE — refusing rather than guessing a live machine the config never described — and that type’s owncontrol_system.connector.<type>block is what such a connector is configured from. A target that does not resolve is not one this deployment has, and an empty block is not a configured one.The one spelling of a question every enumerator asks:
configured_targets()of each machine that is not the baseline — which is also whatswitch_capable()counts — and the deployment layer’s Reach Contracts of the target a projected port would serve. Two predicates over one pair of keys would already be two chances to disagree about which machines a deployment has.- Parameters:
section (object) – The
control_system:config section, in the same shaperesolve_control_system_type()takes.target (object) – The control target being asked about.
- Returns:
Whether the target resolves and its block is a non-empty mapping. Never raises: an unresolvable target is simply not configured.
- Return type:
bool
- osprey_connectors.types.target_limits_posture(section, target)[source]#
The limits posture one session target runs under.
type_limits_posture()for the type that target resolves to, so a holder following the control target and the connector that knows only its own type read one posture and not two. The roster row, the stdlib hook, the executor and the tool layer all arrive here; the connector, the factory and the IPC child arrive attype_limits_posture()— and a deployment that described one machine must not answer them differently.A target that does not resolve answers the deployment-wide block instead. Two shapes reach that branch and both mean the same thing: there is no per-type block to consult because there is no type. An unknown target names nothing.
liveon a deployment baselined on the simulator in process with no real machine authored names a machine the config never described, whichresolve_target()refuses to guess. Such a deployment has only ever had the one deployment-wide block, and keeping it is parity rather than a fallback: a target this deployment never configured still has the one block every such deployment had. Refusing here would instead take the posture away from every deployment that never had a second target.- Parameters:
section (object) – The
control_system:config section, in the same shaperesolve_control_system_type()takes.target (object) – The control target, one of
CONTROL_TARGETS.
- Returns:
The resolved
LimitsPosturefor that target, carrying the type whose block answered — orNonefor the deployment-wide block, which is both what an unresolvable target gets and what a resolvable one gets when its type wrote no block. Never raises.- Return type:
- osprey_connectors.types.tier_allows(section)[source]#
Whether the tier arms anything:
tier_writes()is notnever. Never raises.This reads the ceiling only:
askedandallowedboth answer true, so whether a write prompts is not decided here.- Return type:
bool
- osprey_connectors.types.tier_limits_database_targets(section, *, path_configured)[source]#
The targets the login tier lets write whose limits posture needs a database.
The tier is a ceiling, not a selection: a render whose
tier_writes()answersaskedorallowedlets a session write to everyconfigured_targets(), so every one of them whose resolvedtarget_limits_posture()makeslimits_database_required()true — limits checking on, and a mode other thanoptionalor a path configured — needs the channel-limits database to exist and load. Aneverrender writes nowhere and so arms none. This is the one list a deployment-level caller reads before it demands the file (the compose mount, the build check), so none of them can refuse a deployment another one runs; a caller that serves one lane or one type askslimits_database_required()for that posture directly.The write half is deployment-wide and the limits half is per target, so both are read off the same machine by construction.
incompleteis not read here: a half-written block builds a blocking failsafe at every write surface, and a caller that refuses it names the leaves itself (LimitsPosture.incomplete).- Parameters:
section (object) – The
control_system:config section.path_configured (bool) – Whether the config names a limits database path; the path is deployment-wide, so one answer serves every target.
- Returns:
The qualifying targets in
configured_targets()order; empty for aneverrender. Never raises.- Return type:
list[str]
- osprey_connectors.types.tier_writes(section)[source]#
The write ceiling this deployment’s login tier sets:
never,askedorallowed.WRITES_KEYdecides when the section carries it, and then only the literal strings"asked"and"allowed"arm, matched exactly;"never", any other string (the switch’s retired"on"among them),True,Noneand every other value answernever. When the key is absent the tier isnever: the retired arming leaves are not read at run time, so a render built before the tier key existed writes nowhere until it is rebuilt (the build’s normalizer writes the key into every render).Target-blind by design: a tier that allows writes allows them for every machine. The tier is a ceiling, not a selection — the session’s switch picks the machine.
Never raises. A section that is not a mapping answers
never.- Return type:
Literal[‘never’, ‘asked’, ‘allowed’]
- osprey_connectors.types.type_limits_posture(section, connector_type)[source]#
The limits posture one connector type runs under.
control_system.connector.<type>.limits_checkingwhen that block is there, andcontrol_system.limits_checkingwhen it is not, where connector_type is one key. A custom connector’s dotted module path ('mypackage.SiteConnector') names a single block, never a path through several, so the type is looked up whole and never split on its dots.The per-type block overrides whole, and that is the rule the rest of the family is built on:
Absent — no connector table, no block for this type, a connector block that is not a mapping, or one carrying no
limits_checkingkey at all — inherits the deployment-wide block, both leaves tri-state. That is the compatibility story: a deployment that says nothing per type keeps the posture it had when the deployment-wide block was the only posture there was.Present but not a mapping —
limits_checking: 'true', a list, a barelimits_checking:— is a block written and unreadable, not an absent one, so it answers nothing with both leaves incomplete. Inheriting there would hand the deployment-wide posture to a type whose own block says something nobody can read, which is the one case where inheritance would be a guess rather than compatibility.Present and complete answers alone. Not one leaf is borrowed from the deployment-wide block, because a facility that wrote a block under its live machine has described that machine, and a global relaxation meant for a simulator must not complete it into permission on hardware.
Present and failing to state a leaf answers nothing: both leaves
None, andLimitsPosture.incompletenames what it failed to state. Half a block is a config the build andosprey validaterefuse outright; a hand-edited or older render can still carry one, and then a reader that must act builds a failsafe — blocking every write — rather than guessing which half was meant.
A block fails to state a leaf in two ways, and only the first is particular to per-type blocks. A per-type block may omit one, which the deployment-wide block may do freely because it inherits nothing. Either block may write one unreadably — the
NoneYAML gives a bareenabled:, the quoted'true', a1, an unexpanded'${LIMITS_ON}'— and that is a failure in both scopes. It has to be: an unreadable leaf read as merely unset would leaveenabledmeaning “this deployment configured no limits checking”, so a deployment that wroteenabled: 'true'to switch checking on would have its writes go unchecked. Reported as unstated, it costs a config edit; read as unset, it would cost the guarantee the line was written to provide. Both readings are the build refusal’s too (incomplete_limits_blocks()), so a config the build accepts and one the runtime enforces cannot come apart.Keyed by type rather than by control target because a connector, the factory that builds it, an IPC child all know which connector type they are and never which target selected it.
target_limits_posture()is this same answer for the holders that carry a target instead.- Parameters:
section (object) – The
control_system:config section, in the same shaperesolve_control_system_type()takes.connector_type (str | None) – A connector type name, as
resolve_control_system_type()andresolve_target()return it — which is also its connector sub-block key.None(or an empty name) asks the deployment-wide question, which is what a caller holding no type at all has always asked.
- Returns:
The resolved
LimitsPosture, carrying the type whose block answered — orNonefor the deployment-wide block, which is the key such a posture was read from anyway. Never raises: a section or a connector table that is not a mapping is a deployment that has said nothing, and a deployment that has said nothing states no posture — alimits_checkingvalue that is present but not a mapping is instead an unreadable block, incomplete on both leaves.- Return type:
The one reader of an outbound connection block’s address, bound, login and CA.
Every block that reaches a service by address spells the same shape:
url: https://service.example.org:8443
timeout_s: 60
auth:
token_env: SERVICE_TOKEN # a bearer token, OR
username: service-user # a user and the variable
password_env: SERVICE_PASSWORD # that holds the password
tls:
ca_bundle: /etc/ssl/certs/site-ca.pem
Three invariants hold for every consumer:
A secret is named by environment variable, never written in config. The settings object holds variable names only; the secret is read from the environment when the connection is made.
There is no free-form header map. A login is declared under
auth:.No setting turns certificate verification off.
tls.ca_bundleonly changes which CA is trusted, for this endpoint.
read_connection_settings(), read_credential_env_names() and
read_ca_bundle() are pure: they read neither the environment nor a file,
so a build-time check can call them. The environment and the CA file are
touched only by ConnectionSettings.resolve_credential() and
ConnectionSettings.ssl_context(), when a connection is made.
- class osprey_connectors.connection.ConnectionSettings(where, url=None, timeout_s=None, login=None, ca_bundle=None)[source]#
Bases:
objectAn outbound connection block, read and checked. It never holds a secret.
- where: str#
- url: str | None = None#
- timeout_s: float | None = None#
- ca_bundle: Path | None = None#
- property credential_env_names: tuple[str, ...]#
The environment variables the login’s secret is read from;
()without one.
- timeout_or(default)[source]#
The configured bound, or
defaultwhen the block sets none.- Return type:
float
- resolve_credential(environ=None)[source]#
Read the login’s secret from the environment.
- Parameters:
environ (Mapping[str, str] | None) – The environment to read;
os.environwhen None.- Returns:
The credential, or None when the block names no login.
- Raises:
ConnectionError – The named variable is unset or blank. That is a deployment state, not a config error.
- Return type:
Credential | None
- ssl_context()[source]#
The TLS context for this endpoint.
Without
tls.ca_bundleit is the default context, so the process trust store applies. With one, exactly that file is trusted for this endpoint, in place of the default roots. Verification stays on either way.- Raises:
ValueError – The CA file is missing, unreadable or holds no certificate.
- Return type:
SSLContext
- __init__(where, url=None, timeout_s=None, login=None, ca_bundle=None)#
- class osprey_connectors.connection.Credential(kind, username, secret)[source]#
Bases:
objectA login resolved from the environment. Its repr never shows the secret.
- kind: Literal['token', 'password']#
- username: str | None#
- secret: str#
- authorization_header()[source]#
The
Authorizationvalue: a bearer token, or HTTP Basic sent up front.- Return type:
str
- __init__(kind, username, secret)#
- osprey_connectors.connection.ENV_NAME_RE = re.compile('\\A[A-Za-z_][A-Za-z0-9_]*\\Z')#
What an environment variable name looks like, wherever a config names one.
\Aand\Zanchor the whole string, somatchandfullmatchagree; a$anchor would also match just before a trailing newline.
- class osprey_connectors.connection.Login(kind, token_env=None, username=None, password_env=None)[source]#
Bases:
objectA login named by a connection block. It holds variable names, never a secret.
- kind: Literal['token', 'password']#
- token_env: str | None = None#
- username: str | None = None#
- password_env: str | None = None#
- property env_key: str#
The
auth:key that names this login’s secret variable.
- property env_names: tuple[str, ...]#
The environment variable that holds this login’s secret.
- __init__(kind, token_env=None, username=None, password_env=None)#
- osprey_connectors.connection.read_ca_bundle(block, *, where)[source]#
The CA file a block names under
tls.ca_bundle, as the connector will open it.The path follows the rules
read_connection_settings()applies: it must be absolute, and a~path is refused. Nothing else in the block is checked, so a flatca_bundleoutsidetls:names nothing here. The call reads no environment and no file: whether the file exists is decided when the connection is made.- Parameters:
block (Mapping[str, object] | None) – The settings mapping; None or
{}names no CA.where (str) – The block’s dotted key, named in every message.
- Raises:
ValueError – The block or its
tls:is not a mapping,tls:holds a key other thanca_bundle, or the path is blank,~-spelled or relative.- Return type:
Path | None
- osprey_connectors.connection.read_connection_settings(block, *, where, logins=_ALL_LOGINS, tls=True, unsupported_because='', extra_auth_keys=frozenset())[source]#
Read the shared keys of an outbound connection block.
Only
url,timeout_s,authandtlsare read; every other key is left to the consumer. The call reads no environment and no file.- Parameters:
block (Mapping[str, object] | None) – The settings mapping; None or
{}reads as nothing set.where (str) – The block’s dotted key, named in every message.
logins (frozenset[Literal['token', 'password']]) – The login forms this consumer can send.
tls (bool) – Whether this consumer can apply a per-connection CA.
unsupported_because (str) – Why a refused login or
tls:cannot be sent. Required wheneverloginsortlsis restricted.extra_auth_keys (frozenset[str]) – Keys under
auth:this consumer reads itself beside the login. They are accepted and left to the consumer; they never count as a login.
- Raises:
TypeError –
loginsortlsis restricted without a reason.ValueError – The block breaks the shape. The message starts with the key and never repeats a value from under
auth:or a url’s userinfo.
- Return type:
- osprey_connectors.connection.read_credential_env_names(block, *, where)[source]#
The credential variables a block names under
auth:, with the key naming each.Returns
(dotted key, name as written)pairs,auth.token_envbeforeauth.password_env. A username is not a secret and is never reported. The names are not checked as variable names and otherauth:keys are not checked at all:read_connection_settings()refuses those when the connector reads the block. Only a flat spelling outsideauth:counts for nothing here. The call reads no environment and no file.- Parameters:
block (Mapping[str, object] | None) – The settings mapping; None or
{}names no variable.where (str) – The block’s dotted key, named in every message.
- Raises:
ValueError – The block or its
auth:is not a mapping, orauth:names two logins.- Return type:
tuple[tuple[str, object], …]
- osprey_connectors.connection.urllib_opener(settings, *, environ=None)[source]#
Build the one
urllibopener an HTTP client sends every request through.It trusts the block’s CA (or the default store) and adds the login to requests for the configured origin only. Building it opens no socket.
- Raises:
ValueError – The block has no http(s) url, or its CA file cannot be loaded.
ConnectionError – The login’s variable is unset.
- Return type:
OpenerDirector
The call bound of a control-system connector.
The seconds a control-system connector gives one call when the call names no
bound of its own, read from the connector’s own block
(control_system.connector.<type>). One key, one default and one check, so
every connector that bounds its calls names and refuses that bound alike.
- osprey_connectors.call_timeout.DEFAULT_TIMEOUT_S = 5.0#
Seconds a control-system call is given when its connector block names none.
- osprey_connectors.call_timeout.TIMEOUT_KEY = 'timeout_s'#
The connector block’s key for that bound.
- osprey_connectors.call_timeout.call_timeout_s(config, connector_type)[source]#
The call bound one connector block declares.
- Parameters:
config (Mapping[str, object]) – A connector’s own config section — the mapping
control_system.connector.<type>resolves to.connector_type (str | None) – The type that block belongs to, so a refusal names the key an operator has to go and fix.
Noneleaves the type a placeholder in that message.
- Returns:
The declared bound in seconds, or
DEFAULT_TIMEOUT_Swhen the block declares none.- Raises:
ValueError – If the block still carries
timeout, or iftimeout_sis a bool, neither a number nor a numeric string, not finite, or not positive.- Return type:
float
- osprey_connectors.call_timeout.refuse_renamed_timeout_keys(config)[source]#
Refuse a whole config that still spells a connector’s call bound
timeout.Checked when a config is read, so the old key fails before any connector is built;
call_timeout_s()refuses it again at connect. Nested and dotted spellings are read alike, so aconfig.ymland a profile’sconfig:block are both covered.- Parameters:
config (Mapping[str, object]) – A whole config mapping, nested, dotted or both.
- Raises:
ValueError – Naming every old-spelled key and
TIMEOUT_KEY.