Skip to main content

Python client binding

Python provides blocking and asyncio clients. Routing and server listeners are provided by Rust/Go or an external WAMP router.

from xconn import Client

with Client().connect("ws://127.0.0.1:8080/ws", "realm1") as session:
    result = session.call("example.echo").arg("hello").execute()
    print(result.args)
from xconn import AsyncClient


async def main():
    async with await AsyncClient().connect("ws://127.0.0.1:8080/ws", "realm1") as session:
        result = await session.call("example.echo").arg("hello").execute()
        print(result.args)

The package includes its own xconn.auth, xconn.serializers and custom-peer message views. Built-in JSON/CBOR/MessagePack codecs and anonymous/ticket/CRA/ cryptosign authentication execute in Rust. One native PyO3 extension handles all operations; no standalone Wampproto Python package is required. Client/session operations use fluent call/register/subscribe/publish builders with an explicit execute() terminal. Application callbacks, progress and custom transport/codec adapters remain available.

App/Component helpers remain optional client composition APIs. Embedded router, server, start_router and in-memory router conveniences have been removed.

Installation

uv add xconn
# Or install into an existing environment:
uv pip install xconn

The package imports as xconn. A matching prebuilt ABI3 wheel contains the native extension; users need no Rust toolchain or separate SDK. Wheels support CPython 3.10 and newer. Source builds require Rust and the platform build tools. Linux wheels must be built in manylinux containers and repaired to bundle external TLS libraries before publication. See binding packaging.

Application configuration helpers have optional dependencies:

uv add 'xconn[framework]'

The optional Cap'n Proto serializer is distributed separately from GitHub. Its compatibility import remains available after installing it explicitly:

uv pip install 'git+https://github.com/xconnio/wampproto-messages-capnproto@main#subdirectory=python'

Development and release builds

From the workspace root, use uv to build the source archive and a wheel from that archive, then install the wheel in an isolated environment:

uv build bindings/python --out-dir target/python-dist
uv venv target/python-release-venv
uv pip install --python target/python-release-venv/bin/python target/python-dist/xconn-*.whl
uv pip install --python target/python-release-venv/bin/python pytest pytest-asyncio ruff==0.17.1
cargo build -p xconn --features router --bin xconn-router
target/python-release-venv/bin/python -m pytest bindings/python/tests

The Python release workflow builds and tests wheels and one source archive on Linux x86-64/ARM64 and macOS ARM64. A shared vVERSION tag publishes the verified artifacts to PyPI using trusted publishing and the pypi environment. Manual runs build artifacts without publishing. To retry publication, rerun the failed jobs from the original tag-push run. See binding distribution for setup and release ordering.

The Rust executable is used only by test fixtures. Client tests also exercise the independent original Go router when XCONN_REFERENCE_GO_BIN is configured. The Python CI workflow runs inherited lint rules and Python tests, including streaming against a separate Go binding process. Python callbacks execute outside Rust locks; asyncio completions wake the event loop without polling or one waiting native thread per operation. Explicitly close sessions.

Fluent requests use execute() exclusively: for example, session.call("echo").arg("hello").execute(), or await session.call("echo").arg("hello").execute() with AsyncSession. The former do() spelling has been removed. See the shared execution contract.

Invocation, Event and Result share strict typed payload accessors with explicit defaults and consistent numeric/binary conversion rules.

Result construction and received values use one payload type for handler replies, progressive results and completed calls.

Progressive RPCs use the fluent stream() terminal (Stream()/StreamContext() in Go). See the cross-language streaming API for examples and lifecycle rules.

Progressive results

with session.call("example.process").arg("input").stream(timeout=30) as call:
    for result in call.results():
        print(result.args, result.progress)

With asyncio, use async with await ...stream() and async for. Enable input chunks with stream(progressive_input=True), then send(...) and finish(...).

QUIC connections

from xconn.quic import QUICConnection

with QUICConnection.connect("host:443", server_name="host") as connection:
    session = connection.open_session("realm")
    try:
        print(session.call("echo").arg("hello").execute().args)
    finally:
        session.close()

TLS uses system roots, or an explicit DER certificate. AsyncQUICConnection provides the same operations with await and async with. Connections own their sessions and byte streams. Closing a session leaves the connection usable. open_stream()/accept_stream() return independent byte streams with read, write, write_all, write_eof, and close.

WebTransport

xconn.webtransport.WebTransportConnection and AsyncWebTransportConnection provide the same session and byte-stream operations as QUIC. Connect using an HTTPS URL:

from xconn.webtransport import AsyncWebTransportConnection

async with await AsyncWebTransportConnection.connect("https://host:443/wamp") as connection:
    session = await connection.open_session("realm")
    try:
        print((await session.call("echo").arg("hello").execute()).args)
    finally:
        await session.close()

Rust verifies the server hostname and certificate chain using system roots, or an explicitly supplied DER certificate. Certificate verification is mandatory.

WebRTC

from xconn import AsyncClient
from xconn.webrtc import WebRTCOptions, connect_async

signaling = await AsyncClient().connect("wss://router/ws", "realm")
try:
    peer = await connect_async(
        signaling,
        "realm",
        WebRTCOptions(
            offer_procedure="offer",
            remote_candidates_topic="to-client",
            local_candidates_topic="to-provider",
        ),
    )
    async with peer.connection as connection:
        try:
            print((await peer.call("echo").arg("hello").execute()).args)
            async with await connection.open_channel("files") as channel:
                await channel.write_message(b"file contents")
        finally:
            await peer.close()
finally:
    await signaling.close()

connect is the blocking equivalent. ICE servers and connection, session-open, and handshake deadlines are configured through WebRTCOptions. Rust handles trickle ICE, candidate ordering, signaling, and channel framing. A connection can open additional WAMP sessions and accept remote channels. Closing a WAMP session leaves its connection and other channels open; close the connection explicitly. Raw send/receive preserve text versus binary packets. write_message and read_message use the shared chunk framing for larger messages; use the same framing mode at both ends. Packet channels may be configured as ordered or unreliable; chunked messages require ordered, reliable channels.

Metadata

Release files for xconn 0.6.4

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

Source distribution (sdist)

Source distribution for xconn 0.6.4
File Size Uploaded Provenance Actions
xconn-0.6.4.tar.gz 303.7 kB With provenance Details for xconn-0.6.4.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for xconn 0.6.4
File Interpreter ABI Platform Actions
xconn-0.6.4-cp310-abi3-manylinux_2_28_x86_64.whl CPython 3.10 abi3 Linux glibc 2.28+ x86-64 Details for xconn-0.6.4-cp310-abi3-manylinux_2_28_x86_64.whl
xconn-0.6.4-cp310-abi3-manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.28+ ARM64 Details for xconn-0.6.4-cp310-abi3-manylinux_2_28_aarch64.whl
xconn-0.6.4-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for xconn-0.6.4-cp310-abi3-macosx_11_0_arm64.whl

Total release size: 27.0 MB

Release files / xconn-0.6.4.tar.gz

Download URL xconn-0.6.4.tar.gz
Size 303.7 kB
Tags Source
SHA-256 checksum
How to use checksums
5c2379436c6f0c9c34ccc69b8e4b63ce55a0aab76bebacc052a12105f7c9b227
BLAKE2b-256 checksum
How to use checksums
316541a9e18abf3f66198c7d1900aa4023a9d0cc72e7664fb2c0d77cc5e536aa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 19, 2026.

Transparency log

Release files / xconn-0.6.4-cp310-abi3-manylinux_2_28_x86_64.whl

Download URL xconn-0.6.4-cp310-abi3-manylinux_2_28_x86_64.whl
Size 9.0 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
917d0e3a771d8eb11e5a7425a6fefa2b9e3473995a420b184e5284f50fac5e67
BLAKE2b-256 checksum
How to use checksums
c41746f3bd80fb5baf8175cb3bbf52ce4934b4c51f13019b5ef8f5496fb94ffb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 19, 2026.

Transparency log

Release files / xconn-0.6.4-cp310-abi3-manylinux_2_28_aarch64.whl

Download URL xconn-0.6.4-cp310-abi3-manylinux_2_28_aarch64.whl
Size 9.2 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
aa4c348bd9fd76f3c56de4d90a3cbd78472d5fbb9742ecab3a6242243491db7d
BLAKE2b-256 checksum
How to use checksums
687446038cf16991028caf6ee8bb020f107b7e1a706796512f6d970c0c006023
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 19, 2026.

Transparency log

Release files / xconn-0.6.4-cp310-abi3-macosx_11_0_arm64.whl

Download URL xconn-0.6.4-cp310-abi3-macosx_11_0_arm64.whl
Size 8.4 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
45cd438a05b43e0b079bf19e24c938842c662505e7ac1ac03be389fd23e9822d
BLAKE2b-256 checksum
How to use checksums
4318d45ea19617f95ce971046d0875b13dfb491a319e2ebf2f022a796d44a781
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Nov 19, 2026.

Transparency log

Security for xconn 0.6.4

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

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for xconn-0.6.4.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 Nov 19, 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