Python SDK

The Python SDK brings Celeris to asyncio programs: backend services, workers, command-line tools, and desktop applications. It behaves like the JavaScript SDK, with Python names and asyncio idioms.

Each channel connection automatically joins a segment named default. Access it with channel.default_segment(). That stream does not need an explicit subscription. Use additional named segments when you need separate topics. Messaging explains the listener and permission setup.

Two packages

• useceleris-client manages connections, messages, subscriptions, and presence.
• useceleris-server signs credentials from your application's access decisions. It runs on trusted servers only.

pip install useceleris-client
pip install useceleris-server

Install the server package only on servers that hold the signing secret. It depends on useceleris-client 1.0.0 or later. The client does not include signing facilities.

Both packages support Python 3.10 to 3.14 and include type information (py.typed). The client depends on pydantic, websockets, and typing-extensions.

Follow the guides

1. Connection and lifecycle: obtain credentials, connect, observe state, recover, and clean up.
2. Messaging: subscribe, publish, receive, and understand delivery.
3. Payload formats: text, validated JSON, and custom serializers.
4. Presence: list connections and watch presence events.
5. Errors and troubleshooting: handle failures where the SDK reports them.
6. Server-side usage: sign credentials, and connect from a trusted backend.

Read Reconnection and Recovery for the shared explanation of retries, replay, and application reconciliation. Exact signatures live in the Python client API and Python server API.

asyncio in brief

• Run the SDK inside an event loop, for example with asyncio.run(main()). Use a channel only from that loop's thread.
• Listeners are plain functions. The SDK calls them synchronously, in registration order, when events arrive. The SDK refuses async def listeners. Start a task from a listener for asynchronous work.
• Each connection does its network work on its own thread. A listener that blocks your event loop does not stop the heartbeat pings.
• Cancellation comes from asyncio itself. When you cancel the task that awaits connect(), publish(), or presence_list(), that operation stops and the await raises CancelledError.

Work with SDK values

Every number is an int. Timestamps delivered with messages, notices, and presence are Unix milliseconds. Convert one with datetime.fromtimestamp(timestamp / 1000, tz=timezone.utc). Payloads are bytes.

Vocabulary