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.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 xconn 0.6.0
File Size Uploaded Provenance Actions
xconn-0.6.0.tar.gz 297.4 kB With provenance Details for xconn-0.6.0.tar.gz

Built distributions (wheels)

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

Total release size: 26.9 MB

Release files / xconn-0.6.0.tar.gz

Download URL xconn-0.6.0.tar.gz
Size 297.4 kB
Tags Source
SHA-256 checksum
How to use checksums
2cf596473ee59c138d10a6c05072036f2272afaaa6988c14238cc9696581ac3d
BLAKE2b-256 checksum
How to use checksums
93741995dd73f90638e60415bc0758aa22bc40580b2df9c2b66717a41c187b44
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 12, 2026.

Transparency log

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

Download URL xconn-0.6.0-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
97ea6cd663a56d5a745ece69d43318dcbfc4f76f32d5318e7ed59c460c489d33
BLAKE2b-256 checksum
How to use checksums
20a3511fe05d5bc0cf6f804930b981a126ea8944f555113ee516d0873b62ce6c
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 12, 2026.

Transparency log

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

Download URL xconn-0.6.0-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
f67962b149e0ed4e49d3fd9f8a24fb7ff559ee88b5494aafdefc4ff471ea0847
BLAKE2b-256 checksum
How to use checksums
98bea8b879cf86118fc4bf10e40140c19c71d4bd9b446afda8a1f9e0f4feb985
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 12, 2026.

Transparency log

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

Download URL xconn-0.6.0-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
953465629002fbd19c6c3b2342e4dd6d68c2fcd9e9255d8e1aebe831f5bcafef
BLAKE2b-256 checksum
How to use checksums
41c99b1dd9ad89645e04a176281f1fdd3d9f70e0ab061200e082cfbb34eee7c9
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 12, 2026.

Transparency log

Security for xconn 0.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.

Full provenance

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

Select from 4 files

Attestation for xconn-0.6.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 Nov 12, 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