Python

Use the async sockudo-python realtime client with Protocol V2, protected channels, recovery, filters, deltas, history, and encrypted payloads.

12 min read
View .mdEdit on GitHub

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.

Packagesockudo-python (import name sockudo_python)
Python3.10 or newer, asyncio
Default protocolProtocol V2 (set protocol_version=1 for Pusher compatibility)
Wire formatsJSON, MessagePack, Protobuf
Runtime dependencieswebsockets, httpx, msgpack, PyNaCl, vcdiff-decoder

Install

Terminal window
python -m pip install sockudo-python

For development from this monorepo, install the package in editable mode:

Terminal window
python -m pip install -e client-sdks/sockudo-python

Connect

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.

realtime.py
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 -> connecting
connection: connecting -> connected
subscribed to public-updates
price: {'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.

OptionTypeDefaultDescription
clusterstrrequiredMust be non-empty. Used to derive the host only when ws_host is not set.
ws_hoststr or NoneNoneWebSocket host without a scheme. Set it to your public ingress or load-balancer hostname when self-hosting.
ws_portint80Port for ws:// connections.
wss_portint443Port for wss:// connections.
ws_pathstr""Path prefix placed before /app/<key>.
force_tlsbool or NoneNoneTLS is used unless this is explicitly False. Set False only for local plaintext development.
enabled_transports / disabled_transportslist of SockudoTransport or NoneNoneRestrict the ws / wss transports the client may use.
protocol_versionint22 for Sockudo-native features; 1 for Pusher compatibility.
connection_recoveryboolFalseTrack stream_id and serial per channel and resume after reconnects.
message_deduplicationboolTrueDrop repeated messages by message_id.
message_deduplication_capacityint1000Number of recent message_id values remembered.
echo_messagesboolTrueProtocol V2: whether this connection receives its own published messages.
wire_formatSockudoWireFormatSockudoWireFormat.JSONJSON, MESSAGEPACK, or PROTOBUF (Protocol V2).
activity_timeoutfloat120.0Seconds of inactivity before the client sends a ping.
unavailable_timeoutfloat10.0Seconds a connection attempt may take before the state becomes unavailable.
max_reconnect_attemptsint or None6Retry limit for unexpected disconnects; None means unlimited.
max_reconnect_gap_in_secondsfloat120.0Upper bound on the quadratic backoff delay.
reconnect_jitterfloat0.0Fraction (0 to 1) of each backoff delay to randomize.
channel_authorizationChannelAuthorizationOptionsendpoint /sockudo/authPrivate, presence, and encrypted channel auth.
user_authenticationUserAuthenticationOptionsendpoint /sockudo/user-authUser sign-in auth.
token / auth_callbackstr / callableNoneProtocol V2 capability-token authentication.
auth_refresh_leeway_secondsfloat30.0Refresh leeway for capability tokens.
delta_compressionDeltaOptions or NoneNoneEnables delta negotiation and payload reconstruction.
channel_history / presence_history / versioned_messagesproxy options or NoneNoneBackend proxy endpoints for history and mutable messages.
append_modeAppendModeAppendMode.DELTAProtocol V2 append delivery mode: DELTA or FULL.
append_rollup_windowint or NoneNoneProtocol 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 prefixChannelNeeds auth endpoint
none (for example orders)publicno
private-privateyes
presence-presence (member list)yes, plus a user identity
private-encrypted-end-to-end encryptedyes, 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).

handlers.py
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.

  1. The client connects and receives its socket_id.
  2. On subscribe("private-orders"), the SDK sends an HTTP POST to channel_authorization.endpoint with a form-encoded body containing socket_id, channel_name, and any configured params.
  3. Your backend authenticates the caller, authorizes that channel_name, and returns JSON with auth (plus channel_data for presence and shared_secret for encrypted channels).
  4. The SDK sends the subscribe request to Sockudo with the signed auth.
private_channel.py
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.py
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:

token_auth.py
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, or auth_refresh_leeway_seconds before expiry if that is earlier, and send it over the open socket with sockudo:auth.
  • Opaque callback tokens without expiry metadata are refreshed after code 40142 and before reconnects.
  • Static tokens are never resent, and revocation code 40160 is not retried in place.

User sign-in

Configure a user-auth endpoint when using user-targeted events or watchlists:

signin.py
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.

recovery.py
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:

rewind.py
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:

history.py
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:

presence_history.py
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:

filters.py
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.

deltas.py
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.

versioned.py
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.py
encrypted = client.subscribe("private-encrypted-documents")
encrypted.bind("doc-updated", lambda data, _: print(data)) # already decrypted

Encryption 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.

lifecycle.py
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.

SituationBehavior
Unexpected transport failureRetries 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 reachedState becomes disconnected.
No handshake within unavailable_timeoutState 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.

ExceptionRaised when
SockudoExceptionBase class for every SDK error; also raised for failed or invalid proxy (history, presence history, versioned message) responses.
InvalidAppKeyThe app key passed to SockudoClient is empty.
InvalidOptionscluster is empty, token auth is configured with Protocol V1, or append_rollup_window is not an allowed value.
AuthFailureAn auth endpoint returns a status of 400 or above or invalid JSON; carries status_code.
BadEventNametrigger() is called with a name that does not start with client-.
UnsupportedFeaturetrigger() is called on an encrypted channel.

Only SockudoException is exported from the package root; import the subclasses from sockudo_python.client.

errors.py
from sockudo_python import SockudoException
from 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_error on the channel. Treat 401/403 as an application-permission problem, not a reason to retry in a loop.
  • Server sockudo:error frames are emitted to client.bind("error", ...) with the error payload.
  • Exceptions raised inside message handlers are caught by the receive loop and emitted as error events with the exception object, so a faulty handler does not kill the connection.
  • Close reasons sent by the server are emitted as error events.

Platform notes

  • One client per process. Share a single SockudoClient across 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 a finally block 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_id deduplication 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.

Next steps