Python API
✅ Verified · no code on this page ·
The badge reports the whole
docs-verifysuite, not this chapter alone.
Every progressive example in Part III shows Rust and Python side by side, so the tutorial route is the one to take first. This page is the orientation map: what the module contains, and where the full reference lives.
The complete API reference is
spvirit-py/README.md
— around a thousand lines covering every class, method and keyword argument.
It is not duplicated here; this page tells you which part of it you want.
Every object also carries a docstring, so help(spvirit.ai) and
help(spvirit.Server) work at the interpreter prompt.
For the Rust side there is generated reference documentation on docs.rs:
types ·
codec ·
client ·
server ·
tools ·
calc. The Python
module is a thin layer over spvirit-client and spvirit-server, so when a
Python docstring is terse the Rust page for the same call is often the
fuller answer. See the crate map.
Install
pip install spvirit
A compiled PyO3 extension, not a pure-Python package. Wheels ship for the usual platforms; building from source needs a Rust toolchain. See Installation.
The four layers
| Layer | Import | What it gives you |
|---|---|---|
| Typed PV handles | spvirit.ai, spvirit.ao, … | IOC-style records you keep a handle to. The one to start with. |
| Server + store | spvirit.Server | Runs the PVAccess server; store reaches records by name. |
| Client | spvirit.get, spvirit.put, spvirit.monitor, spvirit.Channel | Reading and writing other people's PVs. |
| Low level | spvirit.lowlevel, spvirit.codec | Raw frames and wire encoding, for proxies and analysers. |
Constructors
The module-level PV constructors mirror the Rust handle API one for one:
ai ao bi bo string_in string_out longin longout
mbbi mbbo waveform aai aao calc pv scalar
pv and scalar are the generic forms — you pass the type explicitly rather
than getting it from the constructor name. The full type-coverage table (which
NT scalar types each constructor accepts) is in the
README's NT scalar type coverage section.
Sync and async
Most operations come in both flavours: set/set_async, get/get_async,
connect/connect_async and so on. The sync forms release the GIL while
they block, so they are safe to call from a thread. The README's
Threading and async model section is the one to read before you mix them.
The rule that catches everyone
Attach callbacks before starting the server. on_put, scan and calc
must be registered on a handle while it is still unbound. Once
Server.start() has run, the handle is bound and a late on_put will not
fire. The same rule holds in Rust, but Python makes it easier to trip over
because the server object is mutable and the failure is silent. See
Reacting to writes and
Troubleshooting.
Examples
spvirit-py/examples/ holds around thirty runnable scripts — one concept
each. The ones the book's chapters use directly:
| Script | Chapter |
|---|---|
demo_first_pv.py | Your first PV |
demo_scalars.py | Serving scalars |
demo_get.py, demo_put.py | Reading and writing |
demo_monitor.py | Monitoring changes |
demo_on_put.py | Reacting to writes |
demo_scan.py, demo_calc.py | Simulating a device |
demo_waveform.py | Arrays and waveforms |
demo_enums.py | Enums and binary records |
demo_alarms.py | Alarms and severity |
demo_table.py | Tables and images |
For Custom data sources the Python route is
the demo_source_*.py family — sensor, async, multi, passthrough,
aggregate, rpc, wildcard. The rest of the directory — gateways, stress
tests, wire inspectors, the 10 000-PV farm — is listed in the README's
Examples section.
Internals
How the bindings are put together, and why they are sync-first, is in Python Bindings in the developer guide.