ably-python

Overview

This is a Python client library for Ably. The library currently targets the Ably 1.1 client library specification.

Running example

importasynciofromablyimportAblyRestasyncdefmain():
asyncwithAblyRest('api:key') asably:
channel=ably.channels.get("channel_name")
if__name__=="__main__":
asyncio.run(main())

Installation

Via PyPI

The client library is available as a PyPI package.

pip install ably

Or, if you need encryption features:

pip install 'ably[crypto]'

Via GitHub

git clone --recurse-submodules https://github.com/ably/ably-python.git
cd ably-python
python setup.py install

Breaking API Changes in Version 1.2.0

Please see our Upgrade / Migration Guide for notes on changes you need to make to your code to update it to use the new API introduced by version 1.2.0.

Usage

All examples assume a client and/or channel has been created in one of the following ways:

With closing the client manually:

fromablyimportAblyRestasyncdefmain(): client=AblyRest('api:key')
channel=client.channels.get('channel_name')
awaitclient.close()

When using the client as a context manager, this will ensure that client is properly closed while leaving the with block:

fromablyimportAblyRestasyncdefmain():
asyncwithAblyRest('api:key') asably:
channel=ably.channels.get("channel_name")

You can define the logging level for the whole library, and override for a specific module:

importloggingimportablylogging.getLogger('ably').setLevel(logging.WARNING)
logging.getLogger('ably.rest.auth').setLevel(logging.INFO)

You need to add a handler to see any output:

logger=logging.getLogger('ably')
logger.addHandler(logging.StreamHandler())

Publishing a message to a channel

awaitchannel.publish('event', 'message')

Querying the History

message_page=awaitchannel.history() # Returns a PaginatedResultmessage_page.items# List with messages from this pagemessage_page.has_next() # => True, indicates there is another pagenext_page=awaitmessage_page.next() # Returns a next pagenext_page.items# List with messages from the second page

Current presence members on a channel

members_page=awaitchannel.presence.get() # Returns a PaginatedResultmembers_page.itemsmembers_page.items[0].client_id# client_id of first member present

Querying the presence history

presence_page=awaitchannel.presence.history() # Returns a PaginatedResultpresence_page.itemspresence_page.items[0].client_id# client_id of first member

Getting the channel status

channel_status=awaitchannel.status() # Returns a ChannelDetails objectchannel_status.channel_id# Channel identifierchannel_status.status# ChannelStatus objectchannel_status.status.occupancy# ChannelOccupancy objectchannel_status.status.occupancy.metrics# ChannelMetrics object

Symmetric end-to-end encrypted payloads on a channel

When a 128 bit or 256 bit key is provided to the library, all payloads are encrypted and decrypted automatically using that key on the channel. The secret key is never transmitted to Ably and thus it is the developer's responsibility to distribute a secret key to both publishers and subscribers.

key=ably.util.crypto.generate_random_key()
channel=rest.channels.get('communication', cipher={'key': key})
channel.publish(u'unencrypted', u'encrypted secret payload')
messages_page=awaitchannel.history()
messages_page.items[0].data#=> "sensitive data"

Generate a Token

Tokens are issued by Ably and are readily usable by any client to connect to Ably:

token_details=awaitclient.auth.request_token()
token_details.token# => "xVLyHw.CLchevH3hF....MDh9ZC_Q"new_client=AblyRest(token=token_details)
awaitnew_client.close()

Generate a TokenRequest

Token requests are issued by your servers and signed using your private API key. This is the preferred method of authentication as no secrets are ever shared, and the token request can be issued to trusted clients without communicating with Ably.

token_request=awaitclient.auth.create_token_request(
{
'client_id': 'jim',
'capability': {'channel1': '"*"'},
'ttl': 3600*1000, # ms
}
)
# => {"id": ...,# "clientId": "jim",# "ttl": 3600000,# "timestamp": ...,# "capability": "{\"*\":[\"*\"]}",# "nonce": ...,# "mac": ...}new_client=AblyRest(token=token_request)
awaitnew_client.close()

Fetching your application's stats

stats=awaitclient.stats() # Returns a PaginatedResultstats.itemsawaitclient.close()

Fetching the Ably service time

awaitclient.time()
awaitclient.close()

Resources

Visit https://ably.com/docs for a complete API reference and more examples.

Requirements

This SDK supports Python 3.7+.

We regression-test the SDK against a selection of Python versions (which we update over time, but usually consists of mainstream and widely used versions). Please refer to check.yml for the set of versions that currently undergo CI testing.

Known Limitations

Currently, this SDK only supports Ably REST. However, you can use the MQTT adapter to implement Ably's Realtime features using Python.

See our roadmap for this SDK for more information.

Support, feedback and troubleshooting

Please visit https://ably.com/support for access to our knowledge base and to ask for any assistance.

You can also view the community reported GitHub issues.

To see what has changed in recent versions of Bundler, see the CHANGELOG.

If you find any compatibility issues, please do raise an issue in this repository or contact Ably customer support for advice.

Contributing

For guidance on how to contribute to this project, see CONTRIBUTING.md