Skip to main content

wse-client

Python client for WSE, the WebSocket engine for reactive user interfaces: topics with message recovery, reconnects, MessagePack, an offline queue, end-to-end encryption and signed messages.

PyPI Python License: MIT

Pure Python, no Rust dependency. It speaks the same protocol as the TypeScript and Rust clients.

Installation

pip install wse-client

Optional extras:

pip install wse-client[crypto]   # E2E encryption
pip install wse-client[msgpack]  # MessagePack wire format (wire_format="msgpack")
pip install wse-client[orjson]   # Faster JSON (de)serialization
pip install wse-client[all]      # Everything

Quick Start

from wse_client import connect

async with connect("ws://localhost:5007/wse", token="<jwt>") as client:
    await client.subscribe(["notifications", "trades"])

    async for event in client:
        print(event.type, event.payload)

Sync

from wse_client import SyncWSEClient

client = SyncWSEClient("ws://localhost:5007/wse", token="<jwt>")
client.connect()
client.subscribe(["notifications"])

event = client.recv(timeout=5.0)
print(event.type, event.payload)

client.close()

Callbacks

from wse_client import SyncWSEClient

client = SyncWSEClient("ws://localhost:5007/wse", token="<jwt>", topics=["notifications"])

# By event type (the "t" of a message), whatever topic it comes on.
@client.on("notification")
def handle(event):
    print(event.payload)

@client.on_any
def catch_all(event):
    print(f"[{event.type}] {event.payload}")

client.connect()
client.run_forever()

Handlers also hear the connection itself: connected (connection_id, user_id, reconnected, recovery) each time the server takes a connection, disconnected (code, reason, reconnecting) when one is lost, and the server's subscription_update replies (success_topics, failed_topics, recovery). The event stream (async for, recv()) carries the server's messages only.

Constructor Parameters

AsyncWSEClient(url, **kwargs) (and SyncWSEClient, which takes the same keywords):

Parameter Type Default Description
url str required WebSocket server URL
token str None JWT token, sent as access_token cookie and Authorization: Bearer header
token_provider callable None Sync or async callable returning the token; called before every connect and reconnect attempt (overrides token)
topics list[str] None Topics to subscribe to after connecting
reconnect ReconnectConfig default config Reconnection strategy
extra_headers dict[str, str] None Additional HTTP headers for the handshake
queue_size int 1000 Events buffered for the iterator / recv(). Once the application reads them, a full buffer stops reading the socket until it has room, so nothing is dropped (the server holds back, or closes a client that stays behind, which then recovers); before that, with handlers only, the oldest is dropped
cookie_name str "access_token" The cookie the token goes in (the server's jwt_cookie_name). Cookies already in extra_headers are kept, and an Authorization header there wins over the token's
encryption bool False Require E2E encryption (needs the [crypto] extra and one of the three below)
e2e_server_keys list[str] None The server's identity public keys (e2e_identity_public_key(), base64) one of which must sign the handshake
e2e_unauthenticated bool False Accept a server without an identity key: safe only from passive listeners
e2e_legacy bool False Speak the first E2E design, for servers before 3.0
e2e_bind_session bool True With signing_key, prove the key inside the session and require the server to confirm it: the token names the key in its cnf claim. False for a key bound with set_client_key()
endpoints list[str] None Additional endpoints for the built-in connection pool / failover
load_balancing LoadBalancingStrategy WEIGHTED_RANDOM Endpoint selection strategy when endpoints is set
rate_limit float | None 100 Outbound limit for send() / send_with_retry() / send_batch() in messages per second; None disables it
rate_limit_burst int 10 x rate_limit Messages that may go out at once before the rate applies
offline_queue bool False Hold messages sent while disconnected and send them once after the next reconnect
max_message_size int | None 16 MiB Largest inbound message, checked on the frame and while inflating compressed frames; None disables it
recovery_timeout float 3.0 Seconds a topic waits for a recovery replay after an offset gap (0 never waits)
wire_format str "json" "msgpack": the server sends this connection MessagePack and the client sends in it too, except inside E2E frames (needs the [msgpack] extra)
signing_key EC key or PEM/DER bytes None This client's ECDSA P-256 key for send(..., signed=True) (needs the [crypto] extra)
server_signing_keys list[str] None The server's signing public keys (signing_public_key(), base64) its signed messages are checked against

The connect(url, **kwargs) factory returns an AsyncWSEClient (not connected yet) to use as an async context manager.

API Reference

AsyncWSEClient

Method Description
connect() Open the connection and complete the handshake (raises on failure, see Error Handling)
disconnect() / close() Close the connection; iteration ends after the queued events
send(type, payload, priority=NORMAL, correlation_id=None) Send a message; returns a SendResult
send_with_retry(type, payload, priority=NORMAL, correlation_id=None, max_retries=5) Send with exponential backoff; one message id across all attempts
send_batch(messages) Send multiple messages in a single frame
subscribe(topics, recover=False) Subscribe to topics, optionally recovering missed messages; while disconnected the topics are subscribed on the next connection
unsubscribe(topics) Unsubscribe from topics (and forget their recovery positions), connected or not
request_snapshot(topics) Request a state snapshot; an identical request within 5 s is not resent
on(event_type) Register event handler (decorator)
on_any(handler) Register a wildcard handler that receives all events
off(event_type, handler) Remove a specific event handler
recv(timeout=None) Receive the next event
force_reconnect() Reconnect now (also revives a client that ended, e.g. after set_token())
change_endpoint(url) Switch to a different server URL; subscribed topics are subscribed again there
set_token(token) Use a new token for the next connect / reconnect
get_stats() Connection statistics, message counts, network quality, recovery counters

send() returns a SendResult (an IntEnum, truthy when the message was accepted):

Value Meaning
SendResult.SENT Written to the socket
SendResult.QUEUED Held by the offline queue (offline_queue=True); sent once after the next reconnect - do not retry it
SendResult.FAILED Neither sent nor queued (not connected, rate limited); the caller decides whether to retry

Properties:

Property Type Description
is_connected bool WebSocket connection is open
is_ready bool server_ready received on the current connection
is_fully_ready bool Connected, server_ready received, and client_hello sent
state ConnectionState Current connection state enum
last_error WSEError | None Why the client ended for good, None while it is healthy
connection_quality ConnectionQuality Network quality assessment
subscribed_topics set[str] Currently subscribed topics
queue_size int Events waiting in the receive queue
recovery_enabled bool Whether the server announced message recovery
recovery_state dict Per-topic recovery anchor {topic: (epoch, offset)}: the last offset delivered in order

Context manager and async iterator:

async with AsyncWSEClient(url) as client:  # auto connect/disconnect
    async for event in client:              # yields WSEEvent objects
        ...

Reconnects are invisible to the iterator: it keeps yielding events across them. It stops after disconnect(), and raises the reason when the client ends for good (WSEAuthError, WSEEncryptionError, or WSEConnectionError once max_attempts is used up).

SyncWSEClient

Same API as AsyncWSEClient but blocking. Runs the async client in a background daemon thread; stats and state reads run on that thread's event loop.

Method Description
run_forever() Block and dispatch events to registered callbacks; returns after close(), raises the reason when the client ends for good
recv(timeout=None) Block until next event (raises WSETimeoutError on timeout)
set_error_handler(handler) Callback (called from the background thread) for the error that ends the client
background_error The error that ended the client, or None
close() Disconnect and shut down the background thread

WSEEvent

@dataclass(frozen=True, slots=True)
class WSEEvent:
    type: str                        # Event type ("t" field)
    payload: dict[str, Any]          # Event data ("p" field)
    id: str | None = None            # Message ID
    sequence: int | None = None      # Sequence number
    timestamp: str | None = None     # ISO 8601 timestamp
    version: int = 1                 # Protocol version
    category: str | None = None      # Message category (system/snapshot/update)
    priority: int | None = None      # Message priority (see MessagePriority)
    correlation_id: str | None = None  # Request correlation ID
    topic: str | None = None         # Recovery stamp: topic ("tp" field)
    epoch: str | None = None         # Recovery stamp: buffer epoch, 8-hex ("e")
    offset: int | None = None        # Recovery stamp: per-topic offset ("o")
    signature: SignatureProof | None = None  # A server-signed message: body, sig, kid, verified

Features

Auto-Reconnection

Four reconnection strategies with configurable parameters:

from wse_client import AsyncWSEClient, ReconnectConfig, ReconnectMode

client = AsyncWSEClient(
    "ws://localhost:5007/wse",
    reconnect=ReconnectConfig(
        mode=ReconnectMode.EXPONENTIAL,  # EXPONENTIAL, LINEAR, FIBONACCI, ADAPTIVE
        base_delay=1.0,                  # Initial delay in seconds
        max_delay=30.0,                  # Maximum delay cap
        factor=1.5,                      # Backoff multiplier
        max_attempts=-1,                 # -1 = retry forever
        jitter=True,                     # Add randomness to prevent thundering herd
    ),
)

ADAPTIVE currently uses the same curve as EXPONENTIAL (kept for API parity with the TS client). Delays never exceed max_delay (and 5 minutes), however long the outage.

Which closes are reconnected:

Close What the client does
disconnect() / close() (client-initiated) Final
Server: 4401 / 4403 / 1008, or HTTP 401 / 403 on the upgrade Final, raises WSEAuthError - with a token_provider, first fetches a fresh token and retries (3 rejections in a row end it)
Server: 1000, 1001 (stop), 1005 (kick), 1011, 1012, 1013, 4300 (drain), 4429, any other code; network loss Reconnect with backoff
A failed reconnect attempt Next attempt with backoff (never terminal); only max_attempts ends the client
Any close before the first handshake of connect() completed connect() raises; nothing reconnects in the background

On every new connection the client subscribes again to all subscribed topics (with recovery positions when the server supports recovery) and, with offline_queue=True, sends the queued messages.

Authentication

client = AsyncWSEClient(url, token="<jwt>")              # fixed token
client = AsyncWSEClient(url, token_provider=get_token)   # fresh token per attempt (sync or async)
client.set_token("<new jwt>")                            # used from the next (re)connect
await client.force_reconnect()                           # ... or right away

A rejected token is kept (not wiped), so force_reconnect() after set_token() revives a client that ended with WSEAuthError.

Message Priority

Five priority levels for message ordering:

from wse_client import MessagePriority

await client.send("alert", {"msg": "critical"}, priority=MessagePriority.CRITICAL)     # 10
await client.send("update", {"data": "..."}, priority=MessagePriority.HIGH)             # 8
await client.send("status", {"ok": True}, priority=MessagePriority.NORMAL)              # 5
await client.send("metric", {"cpu": 42}, priority=MessagePriority.LOW)                  # 3
await client.send("log", {"msg": "debug"}, priority=MessagePriority.BACKGROUND)         # 1

Offline Queue

Off by default. With offline_queue=True, send() called while disconnected returns SendResult.QUEUED and the message goes out once after the next reconnect (highest priority first, up to 1000 messages, dropped after 1 hour). Rate-limited sends are never queued, and send_with_retry() never queues its failed attempts.

Compression

The client inflates compressed frames from the server (C: prefix or raw zlib), bounded by max_message_size: a frame that would inflate past the limit is dropped without being inflated in full. Outbound messages are sent uncompressed.

E2E Encryption

Each frame sealed for the server alone, with the server's identity checked. Requires the cryptography package:

pip install wse-client[crypto]
client = AsyncWSEClient(url, token=token, encryption=True, e2e_server_keys=[SERVER_KEY])

SERVER_KEY is what the server's e2e_identity_public_key() returns; list two during a key rotation. Instead of pinning, e2e_unauthenticated=True accepts any server (safe only from passive listeners), and e2e_legacy=True speaks the first design to servers before 3.0. With encryption=True and none of the three, the client refuses to start. Setup, guarantees and the wire format: SECURITY.md.

Encryption fails closed:

  • After the handshake every frame is sealed, both ways: application messages, subscriptions, recovery requests, pings and PONGs. Messages sent before the handshake completed wait for it; nothing goes out in plaintext, and a heartbeat due meanwhile is skipped.
  • Each connection runs a fresh session; no frame is sealed with the keys of an earlier one.
  • If the server's identity does not check, a frame does not open (replayed, reordered, forged), or the server refuses (KEY_EXCHANGE_FAILED, E2E_UNSUPPORTED, no server_hello within 10 s), the client closes the connection and ends with WSEEncryptionError; it never falls back to plaintext.

Signed Messages

A message that may be disputed (an order) can go signed with this client's own key, and the server's signed messages arrive with their proof. Requires the cryptography package ([crypto] extra).

from wse_client import AsyncWSEClient, generate_signing_key, public_key_jwk

key = generate_signing_key()          # keep it on this device
# Your backend puts public_key_jwk(key) in the token's "cnf" claim. The client
# proves the key inside its end-to-end session, so the token is of no use to
# anyone without the key.

async with AsyncWSEClient(
    url, token=token, signing_key=key, server_signing_keys=[SERVER_SIGNING_KEY],
    encryption=True, e2e_server_keys=[SERVER_KEY],
) as client:
    await client.send("order", {"side": "buy", "qty": "1.5"}, signed=True, nonce="o-17")
    async for event in client:
        if event.type == "receipt":   # the server's signed receipt: event.payload["n"] == "o-17"
            keep(event.signature)     # body, sig, kid: the proof

A backend can bind the key with server.set_client_key() instead and leave it out of the token; the client then sends signed messages with or without encryption, and with encryption needs e2e_bind_session=False.

The server takes a signed message once (nonce, 1 to 128 characters, random by default), within its time window, and refuses anything else with a SIGNATURE_REFUSED error carrying n. A server-signed message no pinned key verifies, or one signed for another topic than the one it came on or for another user, is dropped; without server_signing_keys they arrive unchecked (event.signature.verified is False). Setup and guarantees: SECURITY.md.

Circuit Breaker

Off by default: the backoff alone spaces reconnect attempts, at most max_delay (30 s) apart, so the client is back soon after the server. To pause after failures in a row instead, set ReconnectConfig(circuit_breaker_threshold=5, circuit_breaker_timeout=60.0): after five failed attempts nothing is tried for 60 s, then one attempt, and a failure pauses again. get_stats()["circuit_breaker"] shows whether it is on and its state.

States: CLOSED (normal) -> OPEN (blocking) -> HALF_OPEN (probing) -> CLOSED (recovered)

Rate Limiting

Client-side token bucket for outbound application messages: 100 messages/s with a burst of 1000 by default, set with rate_limit= / rate_limit_burst=, disabled with rate_limit=None. A rate-limited send() returns SendResult.FAILED (one warning every 5 s, counted in get_stats()["rate_limiter"]["rate_limited"]). Protocol frames - heartbeat, PONG, client_hello, subscriptions, recovery requests, health / metrics replies - are never limited. The limiter does not read the server's limits: the server's rate_limit_warning events concern the messages it sends to this connection, and are passed to your handlers.

Idempotent delivery & recovery

Stamped topic messages carry a per-message (topic, epoch, offset) (tp/e/o). Dedup and ordering are driven by the per-topic (epoch, offset), which is authoritative and survives reconnects: a duplicate (offset already seen on the same epoch) is dropped and an in-order message is delivered. An epoch change (server restart) re-baselines the topic. Unstamped messages fall back to a sliding-window id dedup (10,000-entry cache). The server's global seq is a diagnostic only - it is not used for ordering.

A topic never goes dark after an offset gap:

  • When the server supports recovery, the client asks it to replay the topic from the last offset delivered in order, and holds the messages that arrive past the hole for up to recovery_timeout seconds (one request in flight per topic). Replayed messages are delivered in order, then the held ones.
  • If the hole is not filled in time - or the server cannot replay it, does not answer, or recovery is not available - the client delivers the held messages and reports the loss as a recovery_gap event:
@client.on("recovery_gap")
def on_gap(event):
    p = event.payload  # topic, epoch, first_missing, last_missing, missed, reason
    print(f"{p['topic']}: lost {p['missed']} messages ({p['reason']})")

The recovery_gap event also reaches on_any handlers and the iterator. reason is one of unavailable, timeout, not_recovered, incomplete, overflow, epoch_changed, closed. recovery_state reports the last offset delivered per topic (never a server head that was not delivered). Recovery requests are sent as subscription_update messages with recover: true; the server application answers them (see subscribe_with_recovery in the server docs).

Network Quality Monitoring

Real-time network quality assessment based on PING/PONG round-trip measurements:

stats = client.get_stats()
print(stats["network"]["quality"])       # EXCELLENT / GOOD / FAIR / POOR (UNKNOWN until enough samples)
print(stats["network"]["latency_ms"])    # Average round-trip time
print(stats["network"]["jitter_ms"])     # Latency variance
print(stats["network"]["packet_loss"])   # Estimated packet loss (%)
print(stats["recovery"])                 # enabled, pending_gaps, gaps, missed, recovered

Connection Pool

Multi-endpoint support with health scoring and automatic failover:

from wse_client import ConnectionPool, LoadBalancingStrategy

pool = ConnectionPool(
    ["ws://server1:5007/wse", "ws://server2:5007/wse", "ws://server3:5007/wse"],
    strategy=LoadBalancingStrategy.WEIGHTED_RANDOM,  # ROUND_ROBIN, WEIGHTED_RANDOM, LEAST_CONNECTIONS
)
url = pool.select_endpoint()

Endpoints are scored based on connection success rate, latency, and recent failures. Unhealthy endpoints are deprioritized automatically.

Error Handling

from wse_client.errors import (
    WSEError,                # Base exception
    WSEConnectionError,      # Connection failures
    WSETimeoutError,         # Operation timeouts
    WSEAuthError,            # Authentication failures
    WSERateLimitError,       # Rate limit exceeded
    WSEProtocolError,        # Wire protocol violations
    WSECircuitBreakerError,  # Circuit breaker open
    WSEEncryptionError,      # Encryption/decryption failures
)
Error Raised by When
WSEAuthError connect(), iterator, recv(), run_forever() The server rejected the credentials (close 4401 / 4403 / 1008, HTTP 401 / 403), or the token_provider failed during connect()
WSEEncryptionError connect(), send(), iterator, recv() encryption=True and the key exchange failed
WSEConnectionError connect(), iterator, recv() The connection could not be opened or closed during the handshake; reconnect attempts ran out; recv() after disconnect()
WSETimeoutError connect(), SyncWSEClient.connect() / recv() Opening the connection (or the sync recv) timed out
WSECircuitBreakerError connect() The circuit breaker is open

WSERateLimitError and WSEProtocolError are exported for compatibility; the client does not raise them (a rate-limited send returns SendResult.FAILED, an undecodable frame is logged and dropped).

Wire Protocol

The client speaks WSE wire protocol v1:

  • Text frames: JSON with c field for category (WSE, S, U)
  • Binary frames: Codec prefix (C: zlib, M: msgpack, E: E2E sealed) + payload; with wire_format="msgpack" the client asks for ?format=msgpack, decodes M: frames (sealed ones included) and sends its messages as M: frames
  • Handshake: client_hello is the first frame of every connection; the connection is ready at the first server_ready or server_hello (with encryption: once the key exchange completed)
  • Heartbeat: JSON PING/PONG with latency tracking (sealed like every other frame inside an E2E session)

Full protocol specification: PROTOCOL.md

Requirements

  • Python 3.11+
  • websockets >= 13.0

Optional:

  • cryptography >= 43.0 (E2E encryption)
  • msgpack >= 1.0 (MessagePack wire format)
  • orjson >= 3.10 (faster JSON serialization)

License

MIT

Metadata

Release files for wse-client 3.0.1

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

Source distribution (sdist)

Source distribution for wse-client 3.0.1
File Size Uploaded Provenance Actions
wse_client-3.0.1.tar.gz 108.0 kB With provenance Details for wse_client-3.0.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wse-client 3.0.1
File Interpreter ABI Platform Actions
wse_client-3.0.1-py3-none-any.whl Python 3 none any Details for wse_client-3.0.1-py3-none-any.whl

Total release size: 195.0 kB

Release files / wse_client-3.0.1.tar.gz

Download URL wse_client-3.0.1.tar.gz
Size 108.0 kB
Tags Source
SHA-256 checksum
How to use checksums
e990c8380df109383c18a9bc207571fb57ab35a91236be12f2186f91b93c008a
BLAKE2b-256 checksum
How to use checksums
181f5d6b9aea1e4f4554c785c9d9e5074986c163576e77845a2c7456c6de65fe
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 15, 2026.

Transparency log

Release files / wse_client-3.0.1-py3-none-any.whl

Download URL wse_client-3.0.1-py3-none-any.whl
Size 87.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cee2d741873ead21058d166287d283bb6245e639d3b6a3a6eed1b0e436fa0241
BLAKE2b-256 checksum
How to use checksums
e587e72b2ea8b19f761c8a43e5debffc6604548364257ca3eaef8dc21cf7c668
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 15, 2026.

Transparency log

Security for wse-client 3.0.1

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 wse_client-3.0.1.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 15, 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.

Release history Release notifications | RSS feed

This release

3.0.1 This release

2 release files Full provenance

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