A Python client library for www.ably.io, the realtime messaging service.
Works with Python 2.7 and 3.4 onwards.
User support for older Python 3.2 and 3.3 versions is still provided through Github issues and pull requests.
Visit https://www.ably.io/documentation for a complete API reference and more examples.
The client library is available as a PyPI package.
pip install ably
Or, if you need encryption features:
pip install 'ably[crypto]'
git clone https://github.com/ably/ably-python.git
cd ably-python
python setup.py install
All examples assume a client and/or channel has been created as follows:
from ably import AblyRest
client = AblyRest('api:key')
channel = client.channels.get('channel_name')
channel.publish('event', 'message')
message_page = channel.history() # Returns a PaginatedResult
message_page.items # List with messages from this page
message_page.has_next() # => True, indicates there is another page
message_page.next().items # List with messages from the second page
members_page = channel.presence.get() # Returns a PaginatedResult
members_page.items
members_page.items[0].client_id # client_id of first member present
presence_page = channel.presence.history() # Returns a PaginatedResult
presence_page.items
presence_page.items[0].client_id # client_id of first member
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 = channel.history()
messages_page.items[0].data #=> "sensitive data"
Tokens are issued by Ably and are readily usable by any client to connect to Ably:
token_details = client.auth.request_token()
token_details.token # => "xVLyHw.CLchevH3hF....MDh9ZC_Q"
new_client = AblyRest(token=token_details)
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 = client.auth.create_token_request(
{
'client_id': 'jim',
'capability': {'channel1': '"*"'},
'ttl': 3600,
}
)
# => {"id": ...,
# "clientId": "jim",
# "ttl": 3600,
# "timestamp": ...,
# "capability": "{\"*\":[\"*\"]}",
# "nonce": ...,
# "mac": ...}
new_client = AblyRest(token=token_request)
stats = client.stats() # Returns a PaginatedResult
stats.items
client.time()
Please visit http://support.ably.io/ for access to our knowledgebase 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.
git submodule init
git submodule update
pip install -r requirements-test.txt
pytest test
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Ensure you have added suitable tests and the test suite is passing(
py.test
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
- Update
setup.py
with the new version number - Run
python setup.py sdist upload -r pypi
to build and upload this new package to PyPi - Run
github_changelog_generator
to automate the update of the CHANGELOG. Once the CHANGELOG has completed, manually change theUnreleased
heading and link with the current version number such asv1.0.0
. Also ensure that theFull Changelog
link points to the new version tag instead of theHEAD
. Commit this change. - Tag the new version such as
git tag v1.0.0
- Visit https://github.com/ably/ably-python/tags and add release notes for the release including links to the changelog entry.
- Push the tag to origin
git push origin v1.0.0
Copyright (c) 2016 Ably Real-time Ltd, Licensed under the Apache License, Version 2.0. Refer to LICENSE for the license terms.