Add stream_type param for events long polling

Add a `stream_type` parameter to the
`generate_events_with_long_polling()` method and its helper
methods. This allows users to listen to other event stream
types. The default is still to listen to the 'all' stream.

In order to differentiate between user and enterprise event
streams, the following enum hierarchy was created, with the help
of a new `ExtendableEnumMeta` metaclass:

    +-- `EventsStreamType`
          |
          +-- `UserEventsStreamType`
          |
          +-- `EnterpriseEventsStreamType`

Unrelatedly, fix up the RST for the README. Add a table of
contents, and fix up backticks (double-backticks are needed to
create code spans, single-backticks aren't enough).

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]