osprey-connectors

Lean control-system and archiver connectors for OSPREY: EPICS, DOOCS, and mock/virtual-accelerator connectors for reading and writing control-system channels, plus matching archiver connectors (EPICS Archiver Appliance, DOOCS local history, MongoDB, mock) for historical data. The package also carries the small set of support modules those connectors depend on — configuration loading, logging setup, the error/exception taxonomy, and the data-driven simulation core used by the mock connectors — without pulling in the rest of the OSPREY framework (agents, capabilities, web UI, etc.).

Install

pip install osprey-connectors

Import map

osprey-framework still imports every one of these from their historical osprey.* paths. Those old paths are compatibility shims — the real code now lives under osprey_connectors.*, and new code should import from there directly.

Optional runtime dependencies

Only the connectors you actually use need their backing libraries installed; none of the following are declared as hard dependencies of this package, so importing osprey_connectors never requires them:

• EPICS Channel Access client libraries — pyepics itself is a declared dependency, but it needs a working libca at runtime to talk to real IOCs. Install epicscorelibs (or otherwise make a per-architecture libca available) if you use EPICSConnector or EPICSArchiverConnector against a live control system; PYEPICS_LIBCA can also point at one explicitly.
• pymongo — required by MongoDBArchiverConnector. Installed with this package; the connector imports it inside connect() so registration stays cheap, not because it is optional.
• doocs4py — required by DOOCSConnector and DOOCSArchiverConnector. Install separately (it is not on PyPI in all environments) if you connect to a DOOCS control system.

Stability

osprey-connectors follows semantic versioning starting at 0.1.0.

The exception taxonomy in osprey_connectors.errors is public API: the class names ChannelWriteBlockedError, ChannelWriteFailedError, and ChannelLimitsViolationError, and their reason codes, are load-bearing for callers that branch on them.

• ChannelWriteBlockedError — the write was refused and no value was written. reason is one of WRITES_DISABLED, LIMITS, VALIDATION_ERROR, or CONTROL_SYSTEM_REFUSED. The first three are refused before any caput; the last means the control system was asked and denied the write itself (EPICS access security, for instance).
• ChannelWriteFailedError — the write was attempted but did not verifiably succeed. reason is one of FAILED (the control system did not take the value), MISMATCH (the channel holds a different value), or UNCONFIRMED (sent, but not acknowledged in time or the confirming re-read itself failed). The codes are the WriteOutcome words that raise; the exception also carries outcome, value_written and observed_value.
• ChannelLimitsViolationError — a channel write violated configured safety limits (range, read-only, step size, or unlisted channel).

Removing or renaming any of these classes or reason codes is a major version bump. Adding new classes or reason codes is a minor version bump.