Announcing v1 of the Python Library

We are excited to announce that we have published a major release of our Python HTTP library. We’re the first to admit that the previous version of the library didn’t get as much love as it should have. So, after attending PyCon 2015 and ahead of our sponsorship of DjangoCon, we decided to finish off a version we’ve been working on for a while and are very pleased to ship v1. You can fork it on GitHub and pip install pusher via PyPI.

There are a number of major differences from the previous version of the library (0.8), namely that the new version offers far more core interactions with our HTTP API. As well as triggering events and authenticating private and presence channels subscriptions, you are now able to:

• Querying the state of your channels using dedicated methods.
• Validate webhooks sent from Pusher.
• Use various HTTP libraries to send API requests, such as Requests, Tornado, AsyncIO, and URLFetch. The latter adapter allows for use with Google App Engine.

This version of the library is now compatible with Python versions 2.6, 2.7 and 3.3. We’ve also spent some time making sure the docs are much more complete so the Pusher Python HTTP library README has been updated as have the Pusher site docs.

What’s Changed?

Triggering Events

Whereas in the previous version one would trigger events using the indexing operator (pusher['channel_name'].trigger('event_name', payload), one now passes the channel_name as an argument to the Pusher::trigger method.

from pusher import Pusher

pusher = Pusher(app_id=u'app_id', key=u'key', secret=u'secret')

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

Pusher::trigger is documented here.

Querying Application State

We’ve introduced a bunch of new methods for getting information from your Pusher channels. These are:

• Pusher::channels_info: for getting information about all your channels.
• Pusher::channel_info: for getting information about a specific channel.
• Pusher::users_info: for getting information about users subscribed to a presence-channel.

These methods are documented here.

Authenticating Private- and Presence-Channels

When authenticating private- or presence- channels you now use the Pusher::authenticate method instead of using the indexing operator we mentioned earlier. This example uses Flask to demonstrate how to authenticate private-channels:

@app.route("/pusher/auth", methods=['POST'])
def pusher_authentication():

  auth = pusher.authenticate(
    channel=request.form['channel_name'],
    socket_id=request.form['socket_id']
  )
  return json.dumps(auth)

For presence-channels, simply pass in a dictionary containing the user’s user_id, along with any optional user_info, to a custom_data field.

Validating Webhooks

Pusher::validate_webhook can check that an incoming webhook is indeed from Pusher, and not from an unknown origin, as shown in this example:

@app.route("/webhook", methods=['POST'])
def pusher_webhook():
  webhook = pusher.validate_webhook(
    key=request.headers.get('X-Pusher-Key'),
    signature=request.headers.get('X-Pusher-Signature'),
    body=request.data
  )

  for event in webhook['events']:
    if event['name'] == "channel_occupied":
      print("Channel occupied: %s" % event["channel"])
    elif event['name'] == "channel_vacated":
      print("Channel vacated: %s" % event["channel"])

  return "ok"

Webhook validation is documented here.

Contributing

You can find out much more via the Github repo. If you find anything lacking in the library, or room for improvement, please do send us a pull request!