Ably Python SDK

3.1.2 verified Sun Apr 12 auth: no python

The Ably Python SDK provides a client library for the Ably realtime messaging service, enabling developers to build applications with features like Pub/Sub messaging, presence, and message history. Currently at version 3.1.2, it's an actively developed library with frequent patch releases, designed to offer high performance, reliability, and scalability, including support for production AI infrastructure.

pip install ably

Common errors

error ModuleNotFoundError: No module named 'ably' ↓

cause The 'ably' package is not installed in the Python environment.

fix

Install the Ably package using pip: 'pip install ably'.

error ImportError: cannot import name 'Realtime' from 'ably' ↓

cause The 'ably' module does not contain a 'Realtime' class; the correct class is 'AblyRealtime'.

fix

Import the correct class: 'from ably import AblyRealtime'.

error AttributeError: module 'ably' has no attribute 'Realtime' ↓

cause Attempting to access a non-existent 'Realtime' attribute in the 'ably' module.

fix

Use the correct attribute: 'from ably import AblyRealtime'.

error TypeError: AblyRealtime() takes no arguments ↓

cause Incorrect instantiation of the 'AblyRealtime' class without required parameters.

fix

Initialize 'AblyRealtime' with the API key: 'realtime = AblyRealtime('your-api-key')'.

error ValueError: Invalid API key ↓

cause The provided API key is incorrect or improperly formatted.

fix

Ensure the API key is correct and properly formatted: 'realtime = AblyRealtime('your-api-key')'.

Warnings

breaking Version 3.0.0 introduced significant breaking changes, notably adding full Realtime publish support, presence, and mutable messages over WebSockets. This brings Python to feature parity with other SDKs but requires migration for users upgrading from v2.x or earlier, which had limited Realtime capabilities or required an MQTT adapter. ↓

fix Refer to the official Ably documentation for a detailed migration guide when upgrading from v2 to v3. Update import paths and Realtime client usage according to v3 API.

gotcha Using raw API keys directly in your application code, especially in production, is a security risk. API keys in quickstarts are for demonstration purposes only. ↓

fix Always use token authentication in production environments, generated by a trusted backend. If using API keys for development, load them securely from environment variables (e.g., `os.environ`) or a secrets management system.

gotcha Versions of the SDK prior to `3.1.2` (including `2.1.4`) had a bug where message 'extras' (metadata) might not be preserved correctly in message update methods, potentially leading to data loss. [v3.1.2 release notes] ↓

fix Upgrade to `ably` version `3.1.2` or later to ensure proper preservation of message extras during updates.

gotcha Older versions of the SDK (e.g., prior to `3.1.1` and `2.1.4`) contained issues with handling normal WebSocket close frames and improving reconnection logic, which could lead to unexpected connection drops or delayed re-establishment. [v3.1.1 release notes, v2.1.4 release notes] ↓

fix Ensure you are using `ably` version `3.1.1` or later to benefit from improved WebSocket handling and reconnection stability. If on v2, upgrade to `2.1.4` or later.

Imports

AblyRealtime
wrong
```
from ably.realtime import AblyRealtime
```
correct
```
from ably import AblyRealtime
```
The primary asynchronous Realtime client is imported directly from the top-level `ably` package in v3.x. Older patterns might involve submodules.
AblyRest
wrong
```
from ably.rest import AblyRest
```
correct
```
from ably import AblyRest
```
The synchronous REST client is imported directly from the top-level `ably` package in v3.x. Older patterns might involve submodules.

Quickstart

This quickstart demonstrates how to connect to Ably using the `AblyRealtime` client, subscribe to a channel, and publish a message. It leverages Python's `asyncio` for asynchronous operations. Remember to replace the placeholder API key with your actual Ably API key, ideally retrieved from an environment variable for production applications.

import asyncio
import os
from ably import AblyRealtime

async def main():
    api_key = os.environ.get('ABLY_API_API_KEY', 'your_ably_api_key:YOUR_SECRET_KEY')
    if api_key == 'your_ably_api_key:YOUR_SECRET_KEY':
        print("WARNING: Replace 'your_ably_api_key:YOUR_SECRET_KEY' with your actual Ably API key or set ABLY_API_API_KEY environment variable.")
        print("You can obtain a demo key from your Ably dashboard (https://ably.com/dashboard).")

    async with AblyRealtime(api_key, client_id='my-python-client') as ably_realtime:
        # Wait for connection to be established
        await ably_realtime.connection.once_async('connected')
        print('Connected to Ably!')

        channel = ably_realtime.channels.get('my-test-channel')

        # Subscribe to messages
        def on_message(message):
            print(f"Received message: {message.data}")

        await channel.subscribe_async(on_message)
        print("Subscribed to 'my-test-channel'")

        # Publish a message
        await channel.publish('greeting', 'Hello from Ably Python SDK!')
        print("Published 'Hello from Ably Python SDK!' to 'my-test-channel'")

        # Keep the connection open for a bit to receive the message
        await asyncio.sleep(5)


if __name__ == '__main__':
    asyncio.run(main())