Merge branch 'master' into dev-edition

Author: Jeff-Meadows

HISTORY.rst

@@ -6,6 +6,11 @@ Release History
 Upcoming
 ++++++++
 
+1.4.1 (2016-02-11)
+++++++++++++++++++
+
+- Files now support getting a direct download url.
+
 1.4.0 (2016-01-05)
 ++++++++++++++++++
 

README.rst

@@ -18,6 +18,11 @@ box-python-sdk
     :target: https://pypi.python.org/pypi/boxsdk
 
 
+
+.. contents:: :depth: 1
+
+
+
 Installing
 ----------
 
@@ -123,13 +128,20 @@ Create subfolder
     # creates folder structure /L1/L2/L3
     client.folder(folder_id='0').create_subfolder('L1').create_subfolder('L2').create_subfolder('L3')
 
-Get shared link
-~~~~~~~~~~~~~~~
+Get shared link (file or folder)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: python
 
     shared_link = client.folder(folder_id='SOME_FOLDER_ID').get_shared_link()
 
+Get shared link direct download URL (files only)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    download_url = client.file(file_id='SOME_FILE_ID').get_shared_link_download_url()
+
 Get file name
 ~~~~~~~~~~~~~
 
@@ -173,6 +185,22 @@ Search
 
     client.search('some_query', limit=100, offset=0)
 
+Metadata Search
+~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+    from boxsdk.object.search import MetadataSearchFilter, MetadataSearchFilters
+
+    metadata_search_filter = MetadataSearchFilter(template_key='marketingCollateral', scope='enterprise')
+    metadata_search_filter.add_value_based_filter(field_key='documentType', value='datasheet')
+    metadata_search_filter.add_value_based_filter(field_key='clientNumber', value='a123')
+
+    metadata_search_filters = MetadataSearchFilters()
+    metadata_search_filters.add_filter(metadata_search_filter)
+
+    client.search('some_query', limit=100, offset=0, metadata_filters=metadata_search_filters)
+
 Events
 ~~~~~~
 
@@ -208,9 +236,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.
@@ -225,6 +253,30 @@ See https://box-content.readme.io/#as-user-1 for more information about how this
     # Same thing, but using file's as_user method
     client.file(file_id='SOME_FILE_ID').as_user(user).rename('bar-2.txt')
 
+Other Requests
+~~~~~~~~~~~~~~
+
+The Box API is continually evolving. As such, there are API endpoints available that are not specifically
+supported by the SDK. You can still use these endpoints by using the ``make_request`` method of the ``Client``.
+
+.. code-block:: python
+
+    # https://box-content.readme.io/reference#get-metadata-schema
+    from boxsdk.config import API
+    # Returns a Python dictionary containing the result of the API request
+    json_response = client.make_request(
+        'GET',
+        '{0}/metadata_templates/enterprise/customer/schema'.format(API.BASE_API_URL),
+    ).json()
+
+``make_request()`` takes two parameters:
+
+- ``method`` -an HTTP verb like ``GET`` or ``POST``
+- ``url`` - the URL of the requested API endpoint
+
+``boxsdk.config.API`` is an object specifying which URLs to use in order to access the Box API. It can be used for
+formatting the URLs to use with ``make_request``. Box objects also have a ``get_url`` method. Pass it an endpoint
+to get the correct URL for use with that object and endpoint.
 
 Box Developer Edition
 ---------------------
@@ -238,8 +290,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
 
@@ -279,26 +331,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/__init__.py

@@ -2,19 +2,7 @@
 
 from __future__ import unicode_literals
 
-import six
+from six.moves import map   # pylint:disable=redefined-builtin
 
 
-__all__ = [
-    'collaboration',
-    'events',
-    'file',
-    'folder',
-    'group',
-    'group_membership',
-    'search',
-    'user',
-]
-
-if six.PY2:
-    __all__ = [unicode.encode(x, 'utf-8') for x in __all__]
+__all__ = list(map(str, ['collaboration', 'events', 'file', 'folder', 'group', 'group_membership', 'search', 'user']))

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]