Merge pull request #109 from box/long_poll_stream_type

Add stream_type param for events long polling

Author: jmoldow

README.rst

@@ -18,6 +18,11 @@ box-python-sdk
     :target: https://pypi.python.org/pypi/boxsdk
 
 
+
+.. contents:: :depth: 1
+
+
+
 Installing
 ----------
 
@@ -224,9 +229,9 @@ Metadata
 As-User
 ~~~~~~~
 
-The `Client` class and all Box objects also have an `as_user` method.
+The ``Client`` class and all Box objects also have an ``as_user`` method.
 
-`as-user` returns a copy of the object on which it was called that will make Box API requests
+``as-user`` returns a copy of the object on which it was called that will make Box API requests
 as though the specified user was making it.
 
 See https://box-content.readme.io/#as-user-1 for more information about how this works via the Box API.
@@ -254,8 +259,8 @@ Developer Edition support requires some extra dependencies. To get them, simply
 
     pip install boxsdk[jwt]
 
-Instead of instantiating your `Client` with an instance of `OAuth2`,
-instead use an instance of `JWTAuth`.
+Instead of instantiating your ``Client`` with an instance of ``OAuth2``,
+instead use an instance of ``JWTAuth``.
 
 .. code-block:: python
 
@@ -295,26 +300,26 @@ These users can then be authenticated:
    ned_auth.authenticate_app_user(ned_stark_user)
    ned_client = Client(ned_auth)
 
-Requests made with `ned_client` (or objects returned from `ned_client`'s methods)
+Requests made with ``ned_client`` (or objects returned from ``ned_client``'s methods)
 will be performed on behalf of the newly created app user.
 
 Other Auth Options
 ------------------
 
 For advanced uses of the SDK, two additional auth classes are provided:
 
-- `CooperativelyManagedOAuth2`: Allows multiple auth instances to share tokens.
-- `RemoteOAuth2`: Allows use of the SDK on clients without access to your application's client secret. Instead, you
-  provide a `retrieve_access_token` callback. That callback should perform the token refresh, perhaps on your server
+- ``CooperativelyManagedOAuth2``: Allows multiple auth instances to share tokens.
+- ``RemoteOAuth2``: Allows use of the SDK on clients without access to your application's client secret. Instead, you
+  provide a ``retrieve_access_token`` callback. That callback should perform the token refresh, perhaps on your server
   that does have access to the client secret.
-- `RedisManagedOAuth2`: Stores access and refresh tokens in Redis. This allows multiple processes (possibly spanning
+- ``RedisManagedOAuth2``: Stores access and refresh tokens in Redis. This allows multiple processes (possibly spanning
   multiple machines) to share access tokens while synchronizing token refresh. This could be useful for a multiprocess
   web server, for example.
 
 Other Network Options
 ---------------------
 
-For more insight into the network calls the SDK is making, you can use the `LoggingNetwork` class. This class logs
+For more insight into the network calls the SDK is making, you can use the ``LoggingNetwork`` class. This class logs
 information about network requests and responses made to the Box API.
 
 .. code-block:: python

boxsdk/object/events.py

@@ -1,10 +1,53 @@
 # coding: utf-8
 
 from __future__ import unicode_literals
+
 from requests.exceptions import Timeout
+from six import with_metaclass
 
 from boxsdk.object.base_endpoint import BaseEndpoint
+from boxsdk.util.enum import ExtendableEnumMeta
 from boxsdk.util.lru_cache import LRUCache
+from boxsdk.util.text_enum import TextEnum
+
+
+# pylint:disable=too-many-ancestors
+class EventsStreamType(with_metaclass(ExtendableEnumMeta, TextEnum)):
+    """An enum of all possible values of the `stream_type` parameter for user events.
+
+    The value of the `stream_type` parameter determines the type of events
+    returned by the endpoint.
+
+    <https://box-content.readme.io/reference#events>
+    """
+
+
+class UserEventsStreamType(EventsStreamType):
+    """An enum of all possible values of the `stream_type` parameter for user events.
+
+    - ALL: Returns all user events.
+    - CHANGES: Returns tree changes.
+    - SYNC: Returns tree changes only for sync folders.
+
+    <https://box-content.readme.io/reference#standard-user-events>
+    """
+    ALL = 'all'
+    CHANGES = 'changes'
+    SYNC = 'sync'
+
+
+class EnterpriseEventsStreamType(EventsStreamType):
+    """An enum of all possible values of the `stream_type` parameter for enterprise events.
+
+    - ADMIN_LOGS: Retrieves up to a year's events for all users in the enterprise.
+
+    NOTE: Requires Admin: These stream types will only work with an auth token
+    from an enterprise admin account.
+
+    <https://box-content.readme.io/reference#enterprise-events>
+    """
+    ADMIN_LOGS = 'admin_logs'
+# pylint:enable=too-many-ancestors
 
 
 class Events(BaseEndpoint):
@@ -14,7 +57,7 @@ def get_url(self, *args):
         """Base class override."""
         return super(Events, self).get_url('events', *args)
 
-    def get_events(self, limit=100, stream_position=0, stream_type='all'):
+    def get_events(self, limit=100, stream_position=0, stream_type=UserEventsStreamType.ALL):
         """
         Get Box events from a given stream position for a given stream type.
 
@@ -25,12 +68,16 @@ def get_events(self, limit=100, stream_position=0, stream_type='all'):
         :param stream_position:
             The location in the stream from which to start getting events. 0 is the beginning of time. 'now' will
             return no events and just current stream position.
+
+            NOTE: Currently, 'now' is only valid for user events stream types. The request will fail if an
+            enterprise events stream type is passed.
         :type stream_position:
             `unicode`
         :param stream_type:
-            Which type of events to return. Can be 'all', 'tree', or 'sync'.
+            (optional) Which type of events to return.
+            Defaults to `UserEventsStreamType.ALL`.
         :type stream_type:
-            `unicode`
+            :enum:`EventsStreamType`
         :returns:
             JSON response from the Box /events endpoint. Contains the next stream position to use for the next call,
             along with some number of events.
@@ -46,26 +93,38 @@ def get_events(self, limit=100, stream_position=0, stream_type='all'):
         box_response = self._session.get(url, params=params)
         return box_response.json()
 
-    def get_latest_stream_position(self):
+    def get_latest_stream_position(self, stream_type=UserEventsStreamType.ALL):
         """
         Get the latest stream position. The return value can be used with :meth:`get_events` or
         :meth:`generate_events_with_long_polling`.
 
+        :param stream_type:
+            (optional) Which events stream to query.
+            Defaults to `UserEventsStreamType.ALL`.
+
+            NOTE: Currently, the Box API requires this to be one of the user
+            events stream types. The request will fail if an enterprise events
+            stream type is passed.
+        :type stream_type:
+            :enum:`UserEventsStreamType`
         :returns:
             The latest stream position.
         :rtype:
             `unicode`
         """
-        url = self.get_url()
-        params = {
-            'stream_position': 'now',
-        }
-        return self._session.get(url, params=params).json()['next_stream_position']
+        return self.get_events(limit=0, stream_position='now', stream_type=stream_type)['next_stream_position']
 
-    def _get_all_events_since(self, stream_position):
+    def _get_all_events_since(self, stream_position, stream_type=UserEventsStreamType.ALL):
+        """
+        :param stream_type:
+            (optional) Which type of events to return.
+            Defaults to `UserEventsStreamType.ALL`.
+        :type stream_type:
+            :enum:`EventsStreamType`
+        """
         next_stream_position = stream_position
         while True:
-            events = self.get_events(stream_position=next_stream_position, limit=100)
+            events = self.get_events(stream_position=next_stream_position, limit=100, stream_type=stream_type)
             next_stream_position = events['next_stream_position']
             events = events['entries']
             if not events:
@@ -102,7 +161,7 @@ def long_poll(self, options, stream_position):
         )
         return long_poll_response
 
-    def generate_events_with_long_polling(self, stream_position=None):
+    def generate_events_with_long_polling(self, stream_position=None, stream_type=UserEventsStreamType.ALL):
         """
         Subscribe to events from the given stream position.
 
@@ -111,15 +170,24 @@ def generate_events_with_long_polling(self, stream_position=None):
             return no events and just current stream position.
         :type stream_position:
             `unicode`
+        :param stream_type:
+            (optional) Which type of events to return.
+            Defaults to `UserEventsStreamType.ALL`.
+
+            NOTE: Currently, the Box API requires this to be one of the user
+            events stream types. The request will fail if an enterprise events
+            stream type is passed.
+        :type stream_type:
+            :enum:`UserEventsStreamType`
         :returns:
             Events corresponding to changes on Box in realtime, as they come in.
         :rtype:
             `generator` of :class:`Event`
         """
         event_ids = LRUCache()
-        stream_position = stream_position if stream_position is not None else self.get_latest_stream_position()
+        stream_position = stream_position if stream_position is not None else self.get_latest_stream_position(stream_type=stream_type)
         while True:
-            options = self.get_long_poll_options()
+            options = self.get_long_poll_options(stream_type=stream_type)
             while True:
                 try:
                     long_poll_response = self.long_poll(options, stream_position)
@@ -129,7 +197,7 @@ def generate_events_with_long_polling(self, stream_position=None):
                     message = long_poll_response.json()['message']
                     if message == 'new_change':
                         next_stream_position = stream_position
-                        for event, next_stream_position in self._get_all_events_since(stream_position):
+                        for event, next_stream_position in self._get_all_events_since(stream_position, stream_type=stream_type):
                             try:
                                 event_ids.get(event['event_id'])
                             except KeyError:
@@ -142,10 +210,15 @@ def generate_events_with_long_polling(self, stream_position=None):
                     else:
                         break
 
-    def get_long_poll_options(self):
+    def get_long_poll_options(self, stream_type=UserEventsStreamType.ALL):
         """
         Get the url and retry timeout for setting up a long polling connection.
 
+        :param stream_type:
+            (optional) Which type of events to return.
+            Defaults to `UserEventsStreamType.ALL`.
+        :type stream_type:
+            :enum:`EventsStreamType`
         :returns:
             A `dict` including a long poll url, retry timeout, etc.
             E.g.
@@ -160,5 +233,6 @@ def get_long_poll_options(self):
             `dict`
         """
         url = self.get_url()
-        box_response = self._session.options(url)
+        params = {'stream_type': stream_type}
+        box_response = self._session.options(url, params=params)
         return box_response.json()['entries'][0]