Python
Use the async sockudo-python realtime client with Protocol V2, protected channels, recovery, filters, deltas, history, and encrypted payloads.
sockudo-python is the official asynchronous realtime client for Python. It
holds a WebSocket connection to Sockudo, subscribes to channels, and delivers
events to your handlers. Use it in long-running services, AI agents, workers,
CLIs, and any other asyncio application that needs to receive (or send
client) events in real time.
It is a different package from sockudo-http-python,
the trusted server-side HTTP SDK that publishes events, signs authorization
responses, and validates webhooks. The realtime client only ever holds the
public app key; the HTTP SDK holds the app secret.
| Package | sockudo-python (import name sockudo_python) |
| Python | 3.10 or newer, asyncio |
| Default protocol | Protocol V2 (set protocol_version=1 for Pusher compatibility) |
| Wire formats | JSON, MessagePack, Protobuf |
| Runtime dependencies | websockets, httpx, msgpack, PyNaCl, vcdiff-decoder |
Install
python -m pip install sockudo-pythonFor development from this monorepo, install the package in editable mode:
python -m pip install -e client-sdks/sockudo-pythonConnect
A client (SockudoClient) owns one WebSocket connection and its reconnect
policy. A channel is a named stream of events on that connection; you
subscribe to channels and bind handlers to event names. Create one client per
application process, bind handlers, connect, and disconnect during shutdown.
import asyncio
from sockudo_python import SockudoClient, SockudoOptions
async def main() -> None: client = SockudoClient( "app-key", SockudoOptions( cluster="local", ws_host="127.0.0.1", ws_port=6001, force_tls=False, protocol_version=2, connection_recovery=True, ), )
client.bind( "state_change", lambda change, _: print(f"connection: {change['previous']} -> {change['current']}"), )
channel = client.subscribe("public-updates") channel.bind( "sockudo:subscription_succeeded", lambda *_: print("subscribed to public-updates"), ) channel.bind("price-updated", lambda payload, meta: print("price:", payload))
try: await client.connect() await asyncio.Event().wait() finally: await client.disconnect()
asyncio.run(main())Run it against a local server and publish a price-updated event to
public-updates with any server SDK:
connection: initialized -> connectingconnection: connecting -> connectedsubscribed to public-updatesprice: {'price': 67210}connect() returns once the WebSocket is open; the connected state follows
when Sockudo sends the connection handshake. Channels subscribed before that
point are sent to the server automatically as soon as the connection is
established, so you can call subscribe() before or after connect().
Connection options
The values below are the SockudoOptions defaults in the SDK source.
| Option | Type | Default | Description |
|---|---|---|---|
cluster | str | required | Must be non-empty. Used to derive the host only when ws_host is not set. |
ws_host | str or None | None | WebSocket host without a scheme. Set it to your public ingress or load-balancer hostname when self-hosting. |
ws_port | int | 80 | Port for ws:// connections. |
wss_port | int | 443 | Port for wss:// connections. |
ws_path | str | "" | Path prefix placed before /app/<key>. |
force_tls | bool or None | None | TLS is used unless this is explicitly False. Set False only for local plaintext development. |
enabled_transports / disabled_transports | list of SockudoTransport or None | None | Restrict the ws / wss transports the client may use. |
protocol_version | int | 2 | 2 for Sockudo-native features; 1 for Pusher compatibility. |
connection_recovery | bool | False | Track stream_id and serial per channel and resume after reconnects. |
message_deduplication | bool | True | Drop repeated messages by message_id. |
message_deduplication_capacity | int | 1000 | Number of recent message_id values remembered. |
echo_messages | bool | True | Protocol V2: whether this connection receives its own published messages. |
wire_format | SockudoWireFormat | SockudoWireFormat.JSON | JSON, MESSAGEPACK, or PROTOBUF (Protocol V2). |
activity_timeout | float | 120.0 | Seconds of inactivity before the client sends a ping. |
unavailable_timeout | float | 10.0 | Seconds a connection attempt may take before the state becomes unavailable. |
max_reconnect_attempts | int or None | 6 | Retry limit for unexpected disconnects; None means unlimited. |
max_reconnect_gap_in_seconds | float | 120.0 | Upper bound on the quadratic backoff delay. |
reconnect_jitter | float | 0.0 | Fraction (0 to 1) of each backoff delay to randomize. |
channel_authorization | ChannelAuthorizationOptions | endpoint /sockudo/auth | Private, presence, and encrypted channel auth. |
user_authentication | UserAuthenticationOptions | endpoint /sockudo/user-auth | User sign-in auth. |
token / auth_callback | str / callable | None | Protocol V2 capability-token authentication. |
auth_refresh_leeway_seconds | float | 30.0 | Refresh leeway for capability tokens. |
delta_compression | DeltaOptions or None | None | Enables delta negotiation and payload reconstruction. |
channel_history / presence_history / versioned_messages | proxy options or None | None | Backend proxy endpoints for history and mutable messages. |
append_mode | AppendMode | AppendMode.DELTA | Protocol V2 append delivery mode: DELTA or FULL. |
append_rollup_window | int or None | None | Protocol V2 append rollup window; must be one of 0, 20, 40, 100, 500. |
Subscribe and bind events
client.subscribe(name, options=None) returns a channel object; the channel
type is chosen from the name prefix:
| Name prefix | Channel | Needs auth endpoint |
|---|---|---|
none (for example orders) | public | no |
private- | private | yes |
presence- | presence (member list) | yes, plus a user identity |
private-encrypted- | end-to-end encrypted | yes, plus a shared_secret |
Every handler receives (data, metadata). metadata is an EventMetadata
whose user_id is set when the server attaches one (for example, client events
on presence channels).
def on_order(data, meta) -> None: print("order:", data, "from user:", meta.user_id if meta else None)
orders = client.subscribe("orders")token = orders.bind("order.created", on_order)
# Every event on the channel, including sockudo: system events.orders.bind_global(lambda event_name, data: print(event_name, data))
# Remove one handler with its token, or every handler for an event.orders.unbind("order.created", token)orders.unbind("order.created")
# Leave the channel entirely.await client.unsubscribe("orders")client.bind(...) receives connection events and every non-internal channel
event, and client.channel(name) returns an existing subscription.
Subscription state
A connected socket does not mean every channel is subscribed. Wait for the
channel’s subscription result before treating it as live. With Protocol V2 the
events use the sockudo: prefix; with protocol_version=1 they use pusher:.
orders.bind("sockudo:subscription_succeeded", lambda data, _: print("live"))orders.bind( "sockudo:subscription_error", lambda error, _: print("subscription failed:", error),)When the auth request fails, the SDK emits sockudo:subscription_error with
{"type": "AuthError", "error": "<message>"} on that channel.
Client events
Private and presence channels can relay client- events directly between
subscribers when client events are enabled for the app:
private_room = client.subscribe("private-room-1")await private_room.trigger("client-typing", {"user": "ada"})trigger() raises BadEventName when the name does not start with client-,
and returns False if there is no open socket. Encrypted channels do not
support client events.
Private and presence channels
Public channels are open to anyone with the app key. Private, presence, and encrypted channels are protected: before subscribing, the client asks your backend to approve that exact channel for this connection. Your backend checks the user’s session, decides whether they may access the channel, and signs a response with the app secret using a server SDK. Because only the backend has the secret, a client cannot forge access to a channel it was not granted.
- The client connects and receives its
socket_id. - On
subscribe("private-orders"), the SDK sends an HTTPPOSTtochannel_authorization.endpointwith a form-encoded body containingsocket_id,channel_name, and any configuredparams. - Your backend authenticates the caller, authorizes that
channel_name, and returns JSON withauth(pluschannel_datafor presence andshared_secretfor encrypted channels). - The SDK sends the subscribe request to Sockudo with the signed
auth.
from sockudo_python import ( ChannelAuthorizationOptions, SockudoClient, SockudoOptions,)
client = SockudoClient( "app-key", SockudoOptions( cluster="local", ws_host="realtime.example.com", force_tls=True, channel_authorization=ChannelAuthorizationOptions( endpoint="https://api.example.com/sockudo/auth", headers={"X-Client": "worker"}, ), ),)
private_orders = client.subscribe("private-orders")private_orders.bind("order-placed", lambda data, _: print(data))ChannelAuthorizationOptions also accepts params, headers_provider and
params_provider callables (evaluated per request, useful for short-lived
session tokens), and custom_handler, an async function that receives a
ChannelAuthorizationRequest (socket_id, channel_name) and returns
ChannelAuthorizationData without the built-in HTTP call.
Presence channels
Presence channels add a member list. On Protocol V2, subscription success delivers the member set, and later joins, leaves, and data updates arrive as separate events:
presence = client.subscribe("presence-lobby")
presence.bind( "sockudo:subscription_succeeded", lambda members, _: print("members:", members.count, "me:", members.me),)presence.bind("sockudo:member_added", lambda member, _: print("joined:", member.id, member.info))presence.bind("sockudo:member_removed", lambda member, _: print("left:", member.id))presence.bind("sockudo:presence_update", lambda member, _: print("updated:", member.id, member.info))
await client.connect()await presence.update({"status": "editing"})The subscription-succeeded payload is the channel’s member collection (with
count, me, and member(id)); member events deliver a PresenceMember with
id and info. The same collection is available as presence.members.
update() is a Protocol V2 presence update. It changes the member’s data
without a leave and rejoin cycle.
Capability-token authentication
Protocol V2 can also authorize the WebSocket connection itself with a scoped
capability token, issued by your backend. Pass a static token, or an
auth_callback (sync or async) so the client can obtain fresh credentials:
from sockudo_python import SockudoClient, SockudoOptions, TokenAuthData
async def fetch_token() -> TokenAuthData: response = await call_your_backend() return TokenAuthData( token=response["token"], expires_in=response["expires_in"], )
client = SockudoClient( "app-key", SockudoOptions( cluster="local", ws_host="realtime.example.com", force_tls=True, auth_callback=fetch_token, ),)- The callback may return a plain token string or
TokenAuthData. Expiry metadata (expires_in,expires_at,expires_at_ms,exp) lets the SDK schedule a refresh at 80% of the token lifetime, orauth_refresh_leeway_secondsbefore expiry if that is earlier, and send it over the open socket withsockudo:auth. - Opaque callback tokens without expiry metadata are refreshed after code
40142and before reconnects. - Static tokens are never resent, and revocation code
40160is not retried in place.
User sign-in
Configure a user-auth endpoint when using user-targeted events or watchlists:
from sockudo_python import UserAuthenticationOptions
client = SockudoClient( "app-key", SockudoOptions( cluster="local", user_authentication=UserAuthenticationOptions( endpoint="https://api.example.com/sockudo/user-auth", ), ),)
# Events sent to this user (server-to-user channel).client.user.bind("account-updated", lambda data, _: print(data))
await client.connect()await client.user.sign_in() # or: await client.signin()The SDK posts socket_id to the endpoint and expects auth and user_data
in the JSON response. The backend must bind the authenticated application user
to the current socket_id; never accept a user ID supplied by the client
without checking the session.
Protocol V2 features
Protocol V2 is the default for this SDK. It adds continuity metadata
(message_id, stream_id, serial) and Sockudo-native features on top of the
familiar channel model. See Protocol V2 for the
wire-level contract.
Recovery
With connection_recovery=True, the client records the last serial,
stream_id, and message_id per channel. After a reconnect it sends those
positions with sockudo:resume, and Sockudo replays what the channel missed if
continuity can be proven.
client.bind("sockudo:resume_success", lambda data, _: print("recovered:", data))client.bind("sockudo:resume_failed", lambda data, _: print("rebuild:", data))On sockudo:resume_failed, the SDK clears the stored position and delta state
for that channel and resubscribes it automatically.
Rewind
Rewind asks the server for a bounded amount of earlier history at subscription time, either by count or by age:
from sockudo_python import SubscriptionOptions, SubscriptionRewind
market = client.subscribe( "market:btc", options=SubscriptionOptions( rewind=SubscriptionRewind.seconds_back(30), # or SubscriptionRewind.count_messages(50) ),)market.bind("sockudo:rewind_complete", lambda data, _: print(data))Channel history and late joins
For gap-free late joins, proxy channel history through your backend and request history only up to the subscription’s attach point:
from sockudo_python import ChannelHistoryOptions, ChannelHistoryParams
client = SockudoClient( "app-key", SockudoOptions( cluster="local", channel_history=ChannelHistoryOptions( endpoint="https://api.example.com/sockudo/channel-history", ), ),)
channel = client.subscribe("orders")page = await channel.history( ChannelHistoryParams(limit=50, until_attach=True),)for item in page.items: print(item)if page.has_next(): older = await page.next()until_attach=True uses the attach_serial received with
subscription_succeeded when available, so history and live events join
without a gap or duplicate. The proxy receives a JSON POST of
{channel, params, action}, owns Sockudo credentials, and validates which
channels the requesting user may read.
Presence history and snapshots
Presence history is also proxy-backed. The endpoint receives a channel, action, and parameters, then calls the signed server REST API:
from sockudo_python.client import ( PresenceHistoryOptions, PresenceHistoryParams, PresenceSnapshotParams,)
client = SockudoClient( "app-key", SockudoOptions( cluster="local", presence_history=PresenceHistoryOptions( endpoint="https://api.example.com/sockudo/presence-history", ), ),)
presence = client.subscribe("presence-lobby")page = await presence.history( PresenceHistoryParams(limit=50, direction="newest_first"),)if page.has_next(): next_page = await page.next()
snapshot = await presence.snapshot(PresenceSnapshotParams(at_serial=4))Use current membership for live UI, history for audit or timelines, and a snapshot to reconstruct membership at a specific serial. See Presence history.
Filters and event selection
Protocol V2 subscriptions can combine event names, tag filters, and a bounded expression. The server evaluates them and delivers only messages where every supplied condition matches:
from sockudo_python import Filter, SubscriptionOptions
market = client.subscribe( "price:btc", options=SubscriptionOptions( events=["price.updated"], filter=Filter.and_( Filter.eq("market", "spot"), Filter.gt("spread", "0"), ), expression="data.price >= `100`", ),)Filter provides eq, neq, inside, not_in, exists, not_exists,
starts_with, ends_with, contains, gt, gte, lt, lte, and the
combinators and_, or_, and not_. Tag values are strings.
validate_filter(node) returns an error message, or None if the filter is
valid.
Delta compression
Delta compression sends only the difference from a previous message on the same channel. The SDK reconstructs the full payload before invoking your handler, using Fossil or Xdelta3/VCDIFF.
from sockudo_python import ( ChannelDeltaSettings, DeltaAlgorithm, DeltaOptions, SockudoClient, SockudoOptions, SubscriptionOptions,)
client = SockudoClient( "app-key", SockudoOptions( cluster="local", ws_host="127.0.0.1", ws_port=6001, force_tls=False, delta_compression=DeltaOptions(enabled=True), ),)
book = client.subscribe( "orderbook:btc-usd", options=SubscriptionOptions( delta=ChannelDeltaSettings( enabled=True, algorithm=DeltaAlgorithm.XDELTA3, ), ),)book.bind("snapshot", lambda data, _: print(data))
stats = client.get_delta_stats()if stats: print(stats.bandwidth_saved_percent, stats.errors)DeltaOptions also accepts algorithms (default Fossil and Xdelta3), debug,
and on_stats / on_error callbacks. Use deltas for frequently changing,
structurally similar payloads such as order books; monitor get_delta_stats()
and reload full state if base continuity is lost. Delta settings are ignored
for encrypted channels. See Filters and delta compression.
Versioned messages
Create and mutate versioned messages through a trusted proxy. These helpers do not expose app credentials or send mutation frames over the WebSocket; the proxy performs the signed HTTP request and returns the server acknowledgement.
from sockudo_python import VersionedMessageOptions
client = SockudoClient( "app-key", SockudoOptions( cluster="local", versioned_messages=VersionedMessageOptions( endpoint="https://api.example.com/sockudo/versioned-messages", ), ),)
ack = await client.versioned_messages.create( "chat:room-1", "message.created", {"text": "hello"},)if ack.message_id is None: raise RuntimeError("Sockudo did not return a message_id")
await client.versioned_messages.append( "chat:room-1", ack.message_id, {"text": " world"},)await client.versioned_messages.update( "chat:room-1", ack.message_id, {"text": "hello world"},)await client.versioned_messages.delete("chat:room-1", ack.message_id)The same operations exist on a channel as create_versioned_message,
append_versioned_message, update_versioned_message, and
delete_versioned_message. Each accepts optional extras (a MessageExtras
or dict) and a per-call timeout; VersionedMessageOptions.timeout defaults
to 10.0 seconds.
Apply mutations in serial order. If an append arrives before its base, fetch the latest visible message from the proxy before applying later appends. See Mutable messages.
Binary wire formats
Protocol V2 can negotiate MessagePack or Protobuf with
wire_format=SockudoWireFormat.MESSAGEPACK or SockudoWireFormat.PROTOBUF.
Both preserve bytes message data as native binary. MessagePack uses the
additive ["binary", <bin>] tagged value; existing string and JSON variants
are unchanged. Use a binary format only when every endpoint that touches the
stream supports it.
Encrypted channels
private-encrypted-* subscriptions are decrypted automatically. The
authorization response must include a base64 shared_secret derived by your
trusted backend; the SDK fails the subscription if it is missing.
encrypted = client.subscribe("private-encrypted-documents")encrypted.bind("doc-updated", lambda data, _: print(data)) # already decryptedEncryption protects event content end to end. It does not replace TLS, authorization, channel naming policy, or secret rotation.
Connection lifecycle and reconnection
The client moves through the ConnectionState values initialized,
connecting, connected, reconnecting, unavailable, disconnected, and
failed. Each change emits state_change with previous and current, plus
an event named after the new state.
def on_state_change(change, _) -> None: print(f"connection: {change['previous']} -> {change['current']}")
client.bind("state_change", on_state_change)client.bind( "connected", lambda data, _: print("socket id:", data.get("socket_id")),)client.bind("connecting", lambda *_: print("connecting"))client.bind("reconnecting", lambda *_: print("reconnecting"))client.bind("unavailable", lambda *_: print("unavailable"))client.bind("disconnected", lambda *_: print("disconnected"))client.bind("error", lambda error, _: print("error:", error))The current state is also available as client.connection_state, and the
socket ID as client.socket_id.
| Situation | Behavior |
|---|---|
| Unexpected transport failure | Retries with quadratic backoff (0s, 1s, 4s, 9s, …) capped by max_reconnect_gap_in_seconds, emitting reconnecting. |
Protocol retry close codes (4200-4299) | Reconnect immediately. |
TLS-upgrade close code (4000) | Switches to TLS and reconnects immediately. |
Backoff close codes (4100-4199) | Reconnect with backoff. |
Refused close codes (4001-4099, 4300+) | No reconnect; state becomes disconnected. |
| Retry limit reached | State becomes disconnected. |
No handshake within unavailable_timeout | State becomes unavailable. |
await client.disconnect() | Stops reconnect and refresh timers and closes the socket. |
The attempt counter resets after a successful connection and on explicit
connect() or disconnect() calls. reconnect_jitter randomizes each delay
by that fraction so clients dropped by one event do not return in lockstep:
0.5 picks uniformly from 50-100% of the delay, 1.0 from 0-100%. The default
0.0 keeps delays exact.
Remove a subscription when its consumer goes away. This also clears the channel’s recovery and delta state:
await client.unsubscribe("public-updates")await client.close() is an alias for disconnect(), which also closes the
SDK’s HTTP client used for auth and proxy calls.
Error handling
Errors surface in two ways: exceptions from awaited calls, and error events
for problems that happen inside the receive loop.
| Exception | Raised when |
|---|---|
SockudoException | Base class for every SDK error; also raised for failed or invalid proxy (history, presence history, versioned message) responses. |
InvalidAppKey | The app key passed to SockudoClient is empty. |
InvalidOptions | cluster is empty, token auth is configured with Protocol V1, or append_rollup_window is not an allowed value. |
AuthFailure | An auth endpoint returns a status of 400 or above or invalid JSON; carries status_code. |
BadEventName | trigger() is called with a name that does not start with client-. |
UnsupportedFeature | trigger() is called on an encrypted channel. |
Only SockudoException is exported from the package root; import the
subclasses from sockudo_python.client.
from sockudo_python import SockudoExceptionfrom sockudo_python.client import AuthFailure
client.bind("error", lambda error, _: print("connection or server error:", error))
try: page = await channel.history()except SockudoException as exc: print("history unavailable:", exc)- Auth failures during subscribe do not raise; they emit
sockudo:subscription_erroron the channel. Treat401/403as an application-permission problem, not a reason to retry in a loop. - Server
sockudo:errorframes are emitted toclient.bind("error", ...)with the error payload. - Exceptions raised inside message handlers are caught by the receive loop and
emitted as
errorevents with the exception object, so a faulty handler does not kill the connection. - Close reasons sent by the server are emitted as
errorevents.
Platform notes
- One client per process. Share a single
SockudoClientacross tasks; it multiplexes all channels over one socket. - Event loop. Create, connect, and disconnect the client on the same running event loop. Keep callbacks fast and move blocking work off the loop.
- Shutdown. Always
await client.disconnect()(for example in afinallyblock or your framework’s shutdown hook) so timers, the socket, and the HTTP client are released. - Idempotent handlers. Reconnects and application retries can repeat work
even with
message_iddeduplication enabled. - Proxy endpoints. Put timeouts and authentication on every auth and proxy endpoint, and use TLS with a public load-balancer hostname outside local development.
- Publishing. Use the HTTP Python server SDK for publishing, signing auth, webhooks, history administration, and push.