Skip to main content

scpi

Transport-independent, asyncio-based SCPI commands and device helpers for Python 3.12, 3.13 and 3.14. Serial transport uses pyserial-asyncio; VISA is not required.

Usage

Install with pip install scpi or add the package with uv add scpi.

  • Instantiate a transport. GPIB devices use GPIBDeviceTransport.

  • Instantiate SCPIDevice with the transport, or with an explicit SCPIProtocol when you need to share a protocol.

  • Await the device methods from your application’s event loop.

For blocking scripts and interactive use, wrap a device with AIOWrapper. Each wrapper creates its own loop and closes it on quit(). When wrappers share a transport, pass loop=controller.loop to the device wrappers; only that controller owns the loop. Quit device wrappers before their controller. Calling quit() repeatedly is safe. Use the asynchronous API inside an already running event loop.

For example, connect to an HP 6632B power supply:

uv run --locked python examples/hp6632b_serial.py /dev/ttyUSB0

The example leaves an interactive dev object and registers shutdown with atexit. See examples/ for TCP and Prologix GPIB examples. Physical instrument access and serial-port permissions are required for those examples.

Serial I/O

Serial factories and RS232Transport(serialdevice=port) remain synchronous. They open or accept a pyserial port, then attach pyserial-asyncio to the running event loop on the first command or read. Use one event loop per transport and always await quit() (or call the blocking wrapper’s quit()).

Ordinary serial commands and replies use ASCII and CRLF; Prologix uses LF. Replies are buffered, including replies received before get_response(). Response waits are cancellable; a disconnect fails pending reads. Explicit message callbacks remain supported, and unsolicited callbacks receive lines when no response read is pending. Serial BREAK uses an asynchronous delay.

Prologix initialization runs automatically on first use. To reset the controller explicitly, use await transport.initialize_controller(); this method is now asynchronous. Serial read/write timeouts become zero for nonblocking I/O; SCPI command timeouts and asynchronous write flow control bound waits instead.

On POSIX, pyserial-asyncio requires a serial file descriptor. In-memory loop:// ports do not provide one; the tests use pseudo-terminals instead. See the pyserial-asyncio documentation.

Development

The project uses uv, Hatchling, Ruff, strict Pyrefly and prek:

uv sync --locked
uv run --locked prek install
uv run --locked prek run --all-files
uv run --locked pytest
uv run --locked pyrefly check
uv run --locked bandit -r src --skip B101

Run the supported Python matrix with uv run --locked tox. Tox needs Python 3.12, 3.13 and 3.14 available; uv python install 3.12 3.13 3.14 can install them. Tests use fake devices and POSIX pseudo-terminals and need no hardware. Serial integration tests are skipped on Windows. The Bandit B101 exclusion permits existing internal assertions.

Release preparation

From a clean working tree:

uv run --locked bump-my-version bump patch
uv lock
uv run --locked prek run --all-files
uv run --locked pytest
uv build

The bump updates package metadata, the package version and its test. Commit those files and uv.lock together. It does not automatically commit, tag, publish or push. Builds retain LICENSE and py.typed and exclude the local, untracked HANDOFF.md from source distributions.

After a merge or direct push to main, successful Python and container checks automatically create a Git tag matching project.version (for example, 2.6.0). Existing tags are left unchanged, so bump the version before merging a new release. The tagging job uses GITHUB_TOKEN with contents: write; it does not publish packages or create GitHub releases.

Containers

Dockerfile uses Debian Trixie; Dockerfile_alpine uses Alpine 3.24. Both use Python 3.14 and expose test, tox, devel_shell and production targets. Tox checks Python 3.12 through 3.14. Production installs only runtime dependencies, non-editably, and prints the package version by default. Pass a command to run your own script.

Build and run all targets locally:

./run_tests.sh
CONTAINER_ENGINE=podman ./run_tests.sh

Filter a run or use an optional wheelhouse:

CONTAINER_ENGINE=podman VARIANTS=alpine TARGETS=tox ./run_tests.sh
WHEELHOUSE_URL=http://host.docker.internal:3141/debian/ VARIANTS=debian ./run_tests.sh

Sources are copied into images; no host virtualenv, SSH agent or source bind mount is required. The wheelhouse is optional. To build a production image:

docker build --target production -t scpi:local .
docker run --rm scpi:local

Use podman in place of docker if preferred. Access to physical serial instruments must be configured separately for your container engine.

CI

GitHub Actions runs checks on Python 3.12, 3.13 and 3.14, and builds/runs all four container targets on both distributions. Container jobs use Docker.

TODO

Consider configurable carrier-detect and CTS checks for RS232 devices that support those signals.

Metadata

Release files for scpi 2.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for scpi 2.6.0
File Size Uploaded Provenance Actions
scpi-2.6.0.tar.gz 116.4 kB Without provenance Details for scpi-2.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for scpi 2.6.0
File Interpreter ABI Platform Actions
scpi-2.6.0-py3-none-any.whl Python 3 none any Details for scpi-2.6.0-py3-none-any.whl

Total release size: 139.9 kB

Release files / scpi-2.6.0.tar.gz

Download URL scpi-2.6.0.tar.gz
Size 116.4 kB
Tags Source
SHA-256 checksum
How to use checksums
9fdbad02c77f2a758198cb46415b6f6a0e81c57b7af2b831290dc57294f5a34c
BLAKE2b-256 checksum
How to use checksums
1ac912515f9210e7dffd9ad870ea62a2b5b88434087765aae72c1ccaf5784d9d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / scpi-2.6.0-py3-none-any.whl

Download URL scpi-2.6.0-py3-none-any.whl
Size 23.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4b16f42a48f10649ab54efcaf133de8b47c906472df75a656f68d2cf558abb80
BLAKE2b-256 checksum
How to use checksums
bee7f63c8bb155419c1a04053ec8e6e950cdae359a059212a5d9a1f93c1b6624
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for scpi 2.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page