Add support for batch events

Author: zimbatm

README.md

@@ -118,6 +118,38 @@ This call will trigger to `'a_channel'` and `'another_channel'`, and exclude the
 pusher.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.
+
+|Argument   |Description   |
+|:-:|:-:|
+|batch `Array` of `Dict`  |**Required** <br> A list of events to trigger   |
+
+Events are a `Dict` with keys:
+|Argument   |Description   |
+|:-:|:-:|
+|channel `String`| **Required** <br> The name of the channel to publish to. |
+|name `String`| **Required** <br> The name of the event you wish to trigger. |
+|data `JSONable data` | **Required** <br> The event's payload |
+|socket_id `String` | **Default:`None`** <br> The socket_id of the connection you wish to exclude from receiving the event. You can read more [here](http://pusher.com/docs/duplicates). |
+
+|Return Values   |Description   |
+|:-:|:-:|
+|`Dict`| An empty dict on success |
+
+
+##### Example
+
+```python
+pusher.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'}}
+])
+```
+
 #### Event Buffer
 
 Version 1.0.0 of the library introduced support for event buffering. The purpose of this functionality is to ensure that events that are triggered during whilst a client is offline for a short period of time will still be delivered upon reconnection.

pusher/pusher.py

@@ -143,10 +143,7 @@ def trigger(self, channels, event_name, data, socket_id=None):
         if len(event_name) > 200:
             raise ValueError("event_name too long")
 
-        if isinstance(data, six.string_types):
-            data = ensure_text(data, "data")
-        else:
-            data = json.dumps(data, cls=self._json_encoder)
+        data = self._data_to_string(data)
 
         if len(data) > 10240:
             raise ValueError("Too much data")
@@ -161,6 +158,24 @@ def trigger(self, channels, event_name, data, socket_id=None):
 
         return Request(self, POST, "/apps/%s/events" % self.app_id, params)
 
+    @request_method
+    def trigger_batch(self, batch=[], already_encoded=False):
+        '''
+        Trigger multiple events with a single HTTP call.
+
+        http://pusher.com/docs/rest_api#method-post-batch-events
+        '''
+
+        if not already_encoded:
+            for event in batch:
+                event['data'] = self._data_to_string(event['data'])
+
+        params = {
+            'batch': batch
+        }
+
+        return Request(self, POST, "/apps/%s/batch_events" % self.app_id, params)
+
     @request_method
     def channels_info(self, prefix_filter=None, attributes=[]):
         '''
@@ -295,3 +310,11 @@ def ssl(self):
     @property
     def scheme(self):
         return 'https' if self.ssl else 'http'
+
+    def _data_to_string(self, data):
+        if isinstance(data, six.string_types):
+            return ensure_text(data, "data")
+        else:
+            return json.dumps(data, cls=self._json_encoder)
+
+

pusher_tests/test_pusher.py

@@ -87,6 +87,28 @@ def test_trigger_with_channel_string_success_case(self):
 
             self.assertEqual(request.params, expected_params)
 
+    def test_trigger_batch_success_case(self):
+        json_dumped = u'{"message": "something"}'
+
+        with mock.patch('json.dumps', return_value=json_dumped) as json_dumps_mock:
+
+            request = self.pusher.trigger_batch.make_request([{
+                        u'channel': u'my-chan',
+                        u'name': u'my-event',
+                        u'data': {u'message': u'something'}
+                    }])
+
+            expected_params = {
+                u'batch': [{
+                    u'channel': u'my-chan',
+                    u'name': u'my-event',
+                    u'data': json_dumped
+                }]
+            }
+
+            self.assertEqual(request.params, expected_params)
+
+
     def test_trigger_disallow_non_string_or_list_channels(self):
         self.assertRaises(TypeError, lambda:
             self.pusher.trigger.make_request({u'channels': u'test_channel'}, u'some_event', {u'message': u'hello world'}))