pusher

Pusher Channels HTTP API library for Python

Showing:

Popularity

Downloads/wk

0

GitHub Stars

331

Maintenance

Last Commit

5mos ago

Contributors

48

Package

Dependencies

9

License

MIT

Categories

Readme

Pusher Channels HTTP Python Library

Build Status

This package lets you trigger events to your client and query the state of your channels. When used with a server, you can validate webhooks and authenticate private- or presence- channels.

In order to use this library, you need to have a free account on http://pusher.com. After registering, you will need the application credentials for your app.

Supported Platforms

  • Python - supports Python versions 2.7, 3.6, 3.7 and 3.8

Features

  • Adapters for various http libraries like requests, urlfetch, aiohttp (requires Python >= 3.5.3) and tornado.
  • WebHook validation
  • Signature generation for socket subscriptions

Table of Contents

Installation

You can install this module using your package management method or choice, normally easy_install or pip. For example:

pip install pusher

Users on Python 2.x and older versions of pip may get a warning, due to pip compiling the optional pusher.aiohttp module, which uses Python 3 syntax. However, as pusher.aiohttp is not used by default, this does not affect the library's functionality. See our Github issue, as well as this issue from Gunicorn for more details.

On Linux, you must ensure that OpenSSL is installed, e.g. on Debian/Ubuntu:

$ sudo apt-get install build-essential libssl-dev libffi-dev

Getting started

The minimum configuration required to use the Pusher object are the three constructor arguments which identify your Pusher Channels app. You can find them by going to "API Keys" on your app at https://app.pusher.com.

import pusher
pusher_client = pusher.Pusher(app_id=u'4', key=u'key', secret=u'secret', cluster=u'cluster')

You can then trigger events to channels. Channel and event names may only contain alphanumeric characters, - and _:

pusher_client.trigger(u'a_channel', u'an_event', {u'some': u'data'})

Configuration

import pusher
pusher_client = pusher.Pusher(app_id, key, secret, cluster=u'cluster')
ArgumentDescription
app_id StringRequired
The Pusher Channels application ID
key StringRequired
The Pusher Channels application key
secret StringRequired
The Pusher Channels application secret token
cluster StringDefault:mt1
The pusher application cluster. Will be overwritten if host is set
host StringDefault:None
The host to connect to
port intDefault:None
Which port to connect to
ssl boolDefault:True
Use HTTPS
encryption_master_key StringDefault:None
Deprecated, see encryption_master_key_base64
encryption_master_key_base64 StringDefault:None
The encryption master key for End-to-end Encryption
backend Objectan object that responds to the send_request(request) method. If none is provided, a pusher.requests.RequestsBackend instance is created.
json_encoder ObjectDefault: None
Custom JSON encoder.
json_decoder ObjectDefault: None
Custom JSON decoder.

The constructor will throw a TypeError if it is called with parameters that don’t match the types listed above.

Example
import pusher
pusher_client = pusher.Pusher(app_id=u'4', key=u'key', secret=u'secret', ssl=True, cluster=u'cluster')

Triggering Events

To trigger an event on one or more channels, use the trigger method on the Pusher object.

Pusher::trigger

ArgumentDescription
channels String or CollectionRequired
The name or list of names of the channel you wish to trigger events on
event StringRequired
The name of the event you wish to trigger.
data JSONable dataRequired
The event's payload
socket_id StringDefault:None
The socket_id of the connection you wish to exclude from receiving the event. You can read more here.
Return ValuesDescription
buffered_events DictA parsed response that includes the event_id for each event published to a channel. See example.

Pusher::trigger will throw a TypeError if called with parameters of the wrong type; or a ValueError if called on more than 100 channels, with an event name longer than 200 characters, or with more than 10240 characters of data (post JSON serialisation).

Example

This call will trigger to 'a_channel' and 'another_channel', and exclude the recipient with socket_id "1234.12".

pusher_client.trigger([u'a_channel', u'another_channel'], u'an_event', {u'some': u'data'}, "1234.12")

Pusher::trigger_batch

It's also possible to send distinct messages in batches to limit the overhead of HTTP headers. There is a current limit of 10 events per batch on our multi-tenant clusters.

ArgumentDescription
batch Array of DictRequired
A list of events to trigger

Events are a Dict with keys:

ArgumentDescription
channel StringRequired
The name of the channel to publish to.
name StringRequired
The name of the event you wish to trigger.
data JSONable dataRequired
The event's payload
socket_id StringDefault:None
The socket_id of the connection you wish to exclude from receiving the event. You can read more here.
Return ValuesDescription
DictAn empty dict on success

Pusher::trigger_batch will throw a TypeError if the data parameter is not JSONable.

Example
pusher_client.trigger_batch([
  { u'channel': u'a_channel', u'name': u'an_event', u'data': {u'some': u'data'}, u'socket_id': '1234.12'},
  { u'channel': u'a_channel', u'name': u'an_event', u'data': {u'some': u'other data'}}
])

Querying Application State

Getting Information For All Channels

Pusher::channels_info

ArgumentDescription
prefix_filter StringDefault: None
Filter the channels returned by their prefix
attributes CollectionDefault: []
A collection of attributes which should be returned for each channel. If empty, an empty dictionary of attributes will be returned for each channel.
Available attributes: "user_count".
Return ValuesDescription
channels DictA parsed response from the HTTP API. See example.

Pusher::channels_info will throw a TypeError if prefix_filter is not a String.

Example
channels = pusher_client.channels_info(u"presence-", [u'user_count'])

#=> {u'channels': {u'presence-chatroom': {u'user_count': 2}, u'presence-notifications': {u'user_count': 1}}}

Getting Information For A Specific Channel

Pusher::channel_info

ArgumentDescription
channel StringRequired
The name of the channel you wish to query
attributes CollectionDefault: []
A collection of attributes to be returned for the channel.

Available attributes:
"user_count" : Number of distinct users currently subscribed. Applicable only to presence channels.
"subscription_count": [BETA]: Number of connections currently subscribed to the channel. Please contact us to enable this feature.
Return ValuesDescription
channel DictA parsed response from the HTTP API. See example.

Pusher::channel_info will throw a ValueError if channel is not a valid channel.

Example
channel = pusher_client.channel_info(u'presence-chatroom', [u"user_count"])
#=> {u'user_count': 42, u'occupied': True}

Getting User Information For A Presence Channel

Pusher::users_info

ArgumentDescription
channel StringRequired
The name of the presence channel you wish to query
Return ValuesDescription
users DictA parsed response from the HTTP API. See example.

Pusher::users_info will throw a ValueError if channel is not a valid channel.

Example
pusher_client.users_info(u'presence-chatroom')
#=> {u'users': [{u'id': u'1035'}, {u'id': u'4821'}]}

Authenticating Channel Subscription

Pusher::authenticate

In order for users to subscribe to a private- or presence-channel, they must be authenticated by your server.

The client will make a POST request to an endpoint (either "/pusher/auth" or any which you specify) with a body consisting of the channel's name and socket_id.

Using your Pusher instance, with which you initialized Pusher, you can generate an authentication signature. Having responded to the request with this signature, the subscription will be authenticated.

ArgumentDescription
channel StringRequired
The name of the channel, sent to you in the POST request
socket_id StringRequired
The channel's socket_id, also sent to you in the POST request
custom_data DictRequired for presence channels
This will be a dictionary containing the data you want associated with a member of a presence channel. A "user_id" key is required, and you can optionally pass in a "user_info" key. See the example below.
Return ValuesDescription
response DictA dictionary to send as a response to the authentication request.

Pusher::authenticate will throw a ValueError if the channel or socket_id that it’s called with are invalid.

Example
Private Channels
auth = pusher_client.authenticate(

  channel=u"private-channel",

  socket_id=u"1234.12"
)
# return `auth` as a response
Presence Channels
auth = pusher_client.authenticate(

  channel=u"presence-channel",

  socket_id=u"1234.12",

  custom_data={
    u'user_id': u'1',
    u'user_info': {
      u'twitter': '@pusher'
    }
  }
)
# return `auth` as a response

End to End Encryption

This library supports end to end encryption of your private channels. This means that only you and your connected clients will be able to read your messages. Pusher cannot decrypt them. You can enable this feature by following these steps:

  1. You should first set up Private channels. This involves creating an authentication endpoint on your server.

  2. Next, generate a 32 byte master encryption key, base64 encode it and store it securely.

    This is secret and you should never share this with anyone. Not even Pusher.

    To generate a suitable key from a secure random source, you could use:

    openssl rand -base64 32
    
  3. Pass your master key to the SDK constructor

    import pusher
    
    pusher_client = pusher.Pusher(
      app_id='yourappid',
      key='yourkey',
      secret='yoursecret',
      encryption_master_key_base64='<output from command above>',
      cluster='yourclustername',
      ssl=True
    )
    
    pusher_client.trigger('private-encrypted-my-channel', 'my-event', {
      'message': 'hello world'
    })
    
  4. Channels where you wish to use end to end encryption must be prefixed with private-encrypted-.

  5. Subscribe to these channels in your client, and you're done! You can verify it is working by checking out the debug console on the https://dashboard.pusher.com/ and seeing the scrambled ciphertext.

Important note: This will not encrypt messages on channels that are not prefixed by private-encrypted-.

More info on End-to-end Encrypted Channels here.

Receiving Webhooks

If you have webhooks set up to POST a payload to a specified endpoint, you may wish to validate that these are actually from Pusher. The Pusher object achieves this by checking the authentication signature in the request body using your application credentials.

Pusher::validate_webhook

ArgumentDescription
key StringRequired
Pass in the value sent in the request headers under the key "X-PUSHER-KEY". The method will check this matches your app key.
signature StringRequired
This is the value in the request headers under the key "X-PUSHER-SIGNATURE". The method will verify that this is the result of signing the request body against your app secret.
body StringRequired
The JSON string of the request body received.
Return ValuesDescription
body_data DictIf validation was successful, the return value will be the parsed payload. Otherwise, it will be None.

Pusher::validate_webhook will raise a TypeError if it is called with any parameters of the wrong type.

Example
webhook = pusher_client.validate_webhook(

  key="key_sent_in_header",

  signature="signature_sent_in_header",

  body="{ \"time_ms\": 1327078148132  \"events\": [ { \"name\": \"event_name\", \"some\": \"data\" }  ]}"
)

print webhook["events"]

Request Library Configuration

Users can configure the library to use different backends to send calls to our API. The HTTP libraries we support are:

  • Requests (pusher.requests.RequestsBackend). This is used by default.
  • Tornado (pusher.tornado.TornadoBackend).
  • AsyncIO (pusher.aiohttp.AsyncIOBackend).
  • Google App Engine (pusher.gae.GAEBackend).

Upon initializing a Pusher instance, pass in any of these options to the backend keyword argument.

Google App Engine

GAE users are advised to use the pusher.gae.GAEBackend backend to ensure compatability.

Feature Support

FeatureSupported
Trigger event on single channel
Trigger event on multiple channels
Excluding recipients from events
Authenticating private channels
Authenticating presence channels
Get the list of channels in an application
Get the state of a single channel
Get a list of users in a presence channel
WebHook validation
Heroku add-on support
Debugging & Logging
Cluster configuration
Timeouts
HTTPS
End-to-end Encryption
HTTP Proxy configuration
HTTP KeepAlive

Helper Functionality

These are helpers that have been implemented to to ensure interactions with the HTTP API only occur if they will not be rejected e.g. channel naming conventions.

Helper FunctionalitySupported
Channel name validation
Limit to 100 channels per trigger
Limit event name length to 200 chars

Running the tests

To run the tests run python setup.py test

License

Copyright (c) 2015 Pusher Ltd. See LICENSE for details.

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100
No reviews found
Be the first to rate

Alternatives

No alternatives found

Tutorials

No tutorials found
Add a tutorial