Skip to main content

warpedpinball

CI PyPI

Control real pinball machines from Python.

If a machine has a Warped Pinball Vector board installed, this library lets you talk to it in a few lines of code: watch scores change ball by ball, pull leaderboards, manage players, read and write the game's memory, and push firmware updates. Build a tournament display, a Discord bot that announces high scores, a stats dashboard for your basement, or a game mod that reacts to what's happening on the playfield.

The library finds boards on your network by name, handles authentication for you, and works the same whether you connect over WiFi or plug in with a USB cable. You write m.leaderboard(); it takes care of the rest.

Documentation Site

Install

Requires Python 3.9+.

pip install warpedpinball

Recommended: install into a virtual environment

A virtual environment keeps warpedpinball and its dependencies isolated from your system Python, so nothing you install here can interfere with other projects (or with packages your OS manages). This is the recommended way to install.

# Create a virtual environment in a ".venv" folder
python3 -m venv .venv

# Activate it
source .venv/bin/activate          # macOS / Linux
# .venv\Scripts\activate           # Windows (PowerShell / cmd)

# Install the library into the active environment
pip install warpedpinball

# Or, to also get USB (serial) support:
pip install "warpedpinball[usb]"

Once activated, python, pip, and the vector CLI all refer to the environment. Run deactivate to leave it; re-run the source line above to come back to it in a new shell.

Quickstart

Connect to a machine by name and see what's happening on it:

import warpedpinball

with warpedpinball.connect("elvira") as m:
    print(m.leaderboard())

    for event in m.watch_game():
        if event.type == "score_changed":
            print(f"player {event.player}: {event.old} -> {event.new}")

That's a live feed of scores from a real pinball machine, in ten lines. connect() finds the board on your LAN by name (partial names work), and read-only calls like these need no password. When you're ready to change things, pass password= to connect() and the same object can update players, reset leaderboards, write memory, and more.

What you can do

  • Follow games live. watch_game() yields events as games start and end, balls drain, and scores change. See working with a machine.
  • Manage scores and players. Leaderboards, tournaments, player rosters, score claiming, import/export. Also covered in working with a machine.
  • Read and write game memory. Peek at credits, scores, and settings in the machine's battery-backed SRAM, or change them. See reading and writing memory.
  • Reach any firmware route. m.call() gives you the whole HTTP API, even routes that don't have a wrapper yet. See the HTTP API reference.
  • Skip the network entirely. Plug in a USB cable and connect_usb() gives you the same interface with no WiFi and no password.
  • Script from the shell. The vector CLI covers discovery, status, leaderboards, memory access, and firmware updates without writing any Python. See the CLI guide.

Documentation

Full guides live in the documentation index:

The complete API reference is generated from the source docstrings and published to GitHub Pages on every push to main. See docs/api-reference.md for how it is built and how to enable Pages.

Curious about the hardware itself? Vector boards and the machines they fit are at warpedpinball.com.

Development

git clone https://github.com/warped-pinball/python-library
cd python-library
pip install -e ".[dev,usb]"

pytest          # run the tests
ruff check .    # lint

pytest --cov --cov-report=term-missing   # run the tests with a coverage report

CI measures test coverage on every pull request and compares it against the base branch. Pull requests that lower total coverage are flagged: the coverage job posts a comment with the change and fails the check.

Metadata

Release files for warpedpinball 0.5.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 warpedpinball 0.5.0
File Size Uploaded Provenance Actions
warpedpinball-0.5.0.tar.gz 80.9 kB With provenance Details for warpedpinball-0.5.0.tar.gz

Built distribution (wheel)

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

Total release size: 117.4 kB

Release files / warpedpinball-0.5.0.tar.gz

Download URL warpedpinball-0.5.0.tar.gz
Size 80.9 kB
Tags Source
SHA-256 checksum
How to use checksums
46a272dbb614195c919aa98f46de5004fb299f211b5ea0ed0619b81cfe35199e
BLAKE2b-256 checksum
How to use checksums
5ebddbe79b53b69f48e1b48df561b3fa24a10a6298b21923c5189b9c14d15a8f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.

Transparency log

Release files / warpedpinball-0.5.0-py3-none-any.whl

Download URL warpedpinball-0.5.0-py3-none-any.whl
Size 36.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8925f7de8e18d320e117c7759a1ebac284db1177869ef6a6d6ebb1fbb833c615
BLAKE2b-256 checksum
How to use checksums
7b70d5468937c80df8bb386fcdef8b22278f6d35fb917a10312e71499f658381
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.

Transparency log

Security for warpedpinball 0.5.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for warpedpinball-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.

Transparency log

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