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(); no explicit subscription is needed for that stream. Use additional named segments when you need separate topics.

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 --pre useceleris-client
pip install --pre useceleris-server

Install the server package only where the signing secret may live. It depends on the client; the client never includes signing facilities.

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

Follow the guides

1. Connecting 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 they are reported.
6. Server-side usage: sign credentials, and connect from a trusted backend.

Read Reconnection and Recovery for 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()), and use a channel only from that loop's thread.
• Listeners are plain functions, called synchronously in registration order as events arrive. async def listeners are refused; start a task from a listener for asynchronous work.
• Cancellation is asyncio's own. Cancelling the task awaiting connect(), publish() or presence_list() abandons that operation and raises CancelledError.

Working 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