Bitwire for Python

bitspark-bitwire provides the shared relative-path Wire contract as the Python module bitwire. It requires Python 3.11 or newer and has no runtime dependencies. The package contains typed declarations and supporting values; endpoint runtimes, carriers, codecs and routing helpers belong to implementations.

from bitwire import Endpoint, Message, Receiver, ReturnAddress, Wire


def call(endpoint: Wire, replies: Wire) -> None:
    endpoint.send(
        ["cells", "get"],
        Message(
            {"version": 1, "kind": "request", "id": "request-1", "params": {}},
            return_address=ReturnAddress(replies),
        ),
    )


def listen(endpoint: Endpoint):
    def receive(path, message):
        print(path, message.frame)

    return endpoint.receive(Receiver(message=receive))

Wire is a send-only structural Protocol; implementations do not need to inherit from it. send accepts or refuses synchronously; the implementation schedules delivery. Endpoint extends it with receive(receiver) and close, keeping attachment and closure authority separate from send access. One receive attachment is allowed at a time; duplicates are refused. Receivers may return an awaitable. receive returns an idempotent detach function that cannot remove a replacement. Path matching belongs to routing compositions, not to these interfaces. Paths are sequences of opaque Unicode-scalar strings and retain empty segments. Receiver paths are relative to the attached endpoint.

ReturnAddress uses object identity, including when its Wire cannot be compared or hashed. Preserve this object during routing. The return address is local capability data and must never be serialized into the profile envelope. Profile payloads must follow the JSON profile despite their Python object annotation. Runtime-owned received context associated with the return identity must survive routing. Application-supplied context or metadata does not establish verified invocation context; that verification remains the runtime's responsibility.

The Wire contract and profile boundary define the behavior. Runtime protocol checks verify only the presence of methods; they cannot establish conformance.

Packaging and checks

From this directory:

python -m pip install -r requirements-dev.txt
python check.py

This builds a source distribution and a wheel from it, verifies the distribution contents, installs the wheel into a temporary virtual environment, and runs both consumer tests and static typing checks against that installed package. The test endpoint is a recording fixture, not a Bitwire runtime or conformance driver.

For release artifacts at a chosen location:

python -m build --outdir dist

Optional PyPI publication

The manual publish-python.yml workflow publishes an existing immutable public release tag. It is separate from the Go/TypeScript release and does not gate that handover. Its default authentication is a PyPI trusted publisher. Configure these fields under the PyPI account's Publishing page for a pending project:

For an existing project, add the same publisher under the project's publishing settings. As a bootstrap fallback, store an API token in the repository or pypi environment secret named PYPI_API_TOKEN, then select api-token when dispatching the workflow from main. Tokens are passed only to publication steps. Revoke the bootstrap token after trusted publishing is configured. The workflow verifies the packaged artifact before upload and installs the published PyPI package afterward.

The binding is adapted from Nightseam's Python Wire declarations at commit 1c63f1c4 under Apache-2.0. See the included LICENSE and NOTICE files.