Add network and auth subclasses.

-Adds LoggingNetwork to allow clients to see what network calls the SDK is making.
-Adds RemoteOAuth2 to allow auth to occur in a different process or machine from the SDK.
-Adds RedisManagedOAuth2 to allow token storage in Redis, to enable multiple processes or machines to share tokens.

Author: Jeff-Meadows

HISTORY.rst

@@ -9,6 +9,8 @@ Upcoming
 - CPython 3.5 support.
 - Support for cryptography>=1.0 on PyPy 2.6.
 - Travis CI testing for CPython 3.5 and PyPy 2.6.0.
+- Added a logging network class that logs requests and responses.
+- Added new options for auth classes, including storing tokens in Redis and storing them on a remote server.
 
 1.2.1 (2015-07-22)
 ++++++++++++++++++

README.rst

@@ -282,6 +282,30 @@ These users can then be authenticated:
 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:
+
+- `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
+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
+information about network requests and responses made to the Box API.
+
+.. code-block:: python
+
+    from boxsdk import Client
+    from boxsdk.network.logging_network import LoggingNetwork
+
+    client = Client(oauth, network_layer=LoggingNetwork())
 
 Contributing
 ------------

boxsdk/auth/oauth2.py

@@ -65,7 +65,7 @@ def __init__(
         """
         self._client_id = client_id
         self._client_secret = client_secret
-        self._store_tokens = store_tokens
+        self._store_tokens_callback = store_tokens
         self._access_token = access_token
         self._refresh_token = refresh_token
         self._network_layer = network_layer if network_layer else DefaultNetwork()
@@ -158,6 +158,17 @@ def _refresh(self, access_token):
 
         return self.send_token_request(data, access_token)
 
+    def _get_tokens(self):
+        """
+        Get the current access and refresh tokens.
+
+        :return:
+            Tuple containing the current access token and refresh token.
+        :rtype:
+            `tuple` of (`unicode`, `unicode`)
+        """
+        return self._access_token, self._refresh_token
+
     def refresh(self, access_token_to_refresh):
         """
         Refresh the access token and the refresh token and return the access_token, refresh_token tuple. The access
@@ -169,16 +180,17 @@ def refresh(self, access_token_to_refresh):
             `unicode`
         """
         with self._refresh_lock:
+            access_token, refresh_token = self._get_tokens()
             # The lock here is for handling that case that multiple requests fail, due to access token expired, at the
             # same time to avoid multiple session renewals.
-            if access_token_to_refresh == self._access_token:
+            if access_token_to_refresh == access_token:
                 # If the active access token is the same as the token needs to be refreshed, we make the request to
                 # refresh the token.
                 return self._refresh(access_token_to_refresh)
             else:
                 # If the active access token (self._access_token) is not the same as the token needs to be refreshed,
                 # it means the expired token has already been refreshed. Simply return the current active tokens.
-                return self._access_token, self._refresh_token
+                return access_token, refresh_token
 
     @staticmethod
     def _get_state_csrf_token():
@@ -195,6 +207,10 @@ def _get_state_csrf_token():
         ascii_len = len(ascii_alphabet)
         return 'box_csrf_token_' + ''.join(ascii_alphabet[int(system_random.random() * ascii_len)] for _ in range(16))
 
+    def _store_tokens(self, access_token, refresh_token):
+        if self._store_tokens_callback is not None:
+            self._store_tokens_callback(access_token, refresh_token)
+
     def send_token_request(self, data, access_token, expect_refresh_token=True):
         """
         Send the request to acquire or refresh an access token.
@@ -231,6 +247,5 @@ def send_token_request(self, data, access_token, expect_refresh_token=True):
                 raise BoxOAuthException(network_response.status_code, network_response.content, url, 'POST')
         except (ValueError, KeyError):
             raise BoxOAuthException(network_response.status_code, network_response.content, url, 'POST')
-        if self._store_tokens:
-            self._store_tokens(self._access_token, self._refresh_token)
+        self._store_tokens(self._access_token, self._refresh_token)
         return self._access_token, self._refresh_token

boxsdk/auth/redis_managed_oauth2.py

@@ -0,0 +1,76 @@
+# coding: utf-8
+
+from __future__ import unicode_literals
+from redis import StrictRedis
+from redis.lock import Lock
+from uuid import uuid4
+from boxsdk import JWTAuth, OAuth2
+
+
+class RedisManagedOAuth2Mixin(OAuth2):
+    """
+    Box SDK OAuth2 subclass.
+    Allows for storing auth tokens in redis.
+
+    :param unique_id:
+        An identifier for this auth object. Auth instances which wish to share tokens must use the same ID.
+    :type unique_id:
+        `unicode`
+    :param redis_server:
+        An instance of a Redis server, configured to talk to Redis.
+    :type redis_server:
+        :class:`Redis`
+    """
+    def __init__(self, unique_id=uuid4(), redis_server=None, *args, **kwargs):
+        self._unique_id = unique_id
+        self._redis_server = redis_server or StrictRedis()
+        super(RedisManagedOAuth2Mixin, self).__init__(*args, **kwargs)
+        if self._access_token is None:
+            self._update_current_tokens()
+        self._refresh_lock = Lock(redis=self._redis_server, name='{0}_lock'.format(self._unique_id))
+
+    def _update_current_tokens(self):
+        self._access_token, self._refresh_token = self._redis_server.hvals(self._unique_id) or (None, None)
+
+    @property
+    def unique_id(self):
+        """
+        Get the unique ID used by this auth instance. Other instances can share tokens with this instance
+        if they share the ID with this instance.
+        """
+        return self._unique_id
+
+    def _get_tokens(self):
+        """
+        Base class override.
+        Gets the latest tokens from redis before returning them.
+        """
+        self._update_current_tokens()
+        return super(RedisManagedOAuth2Mixin, self)._get_tokens()
+
+    def send_token_request(self, *args, **kwargs):
+        """
+        Base class override.
+        Saves the refreshed tokens in redis.
+        """
+        tokens = super(RedisManagedOAuth2Mixin, self).send_token_request(*args, **kwargs)
+        self._redis_server.hmset(self._unique_id, {'access': tokens[0], 'refresh': tokens[1]})
+        return tokens
+
+
+class RedisManagedOAuth2(RedisManagedOAuth2Mixin):
+    """
+    OAuth2 subclass which uses Redis to manage tokens.
+    """
+    pass
+
+
+class RedisManagedJWTAuth(RedisManagedOAuth2Mixin, JWTAuth):
+    """
+    JWT Auth subclass which uses Redis to manage access tokens.
+    """
+    def _auth_with_jwt(self, sub, sub_type):
+        """
+        Base class override. Returns the access token in a tuple to match the OAuth2 interface.
+        """
+        return super(RedisManagedJWTAuth, self)._auth_with_jwt(sub, sub_type), None

boxsdk/auth/remote_oauth2.py

@@ -0,0 +1,26 @@
+# coding: utf-8
+
+from __future__ import unicode_literals
+from boxsdk import OAuth2
+
+
+class RemoteOAuth2Mixin(OAuth2):
+    """
+    Box SDK OAuth2 subclass.
+    Allows for storing auth tokens remotely.
+
+    :param retrieve_access_token:
+        Callback to exchange an existing access token for a new one.
+    :type retrieve_access_token:
+        `callable` of `unicode` => `unicode`
+    """
+    def __init__(self, retrieve_access_token=None, *args, **kwargs):
+        self._retrieve_access_token = retrieve_access_token
+        super(RemoteOAuth2Mixin, self).__init__(*args, **kwargs)
+
+    def _refresh(self, access_token):
+        """
+        Base class override. Ask the remote host for a new token.
+        """
+        self._access_token = self._retrieve_access_token(access_token)
+        return self._access_token, None

boxsdk/network/logging_network.py

@@ -0,0 +1,70 @@
+# coding: utf-8
+
+from __future__ import unicode_literals
+from pprint import pformat
+from boxsdk.network.default_network import DefaultNetwork
+from boxsdk.util.log import setup_logging
+
+
+class LoggingNetwork(DefaultNetwork):
+    """
+    SDK Network subclass that logs requests and responses.
+    """
+    def __init__(self, logger=None):
+        """
+        :param logger:
+            The logger to use. If you instantiate this class more than once, you should use the same logger
+            to avoid duplicate log entries.
+        :type logger:
+            :class:`Logger`
+        """
+        super(LoggingNetwork, self).__init__()
+        self._logger = logger or setup_logging(name='network')
+
+    @property
+    def logger(self):
+        return self._logger
+
+    def _log_request(self, method, url, **kwargs):
+        """
+        Logs information about the Box API request.
+
+        :param method:
+            The HTTP verb that should be used to make the request.
+        :type method:
+            `unicode`
+        :param url:
+            The URL for the request.
+        :type url:
+            `unicode`
+        :param access_token:
+            The OAuth2 access token used to authorize the request.
+        :type access_token:
+            `unicode`
+        """
+        self._logger.info('\x1b[36m%s %s %s\x1b[0m', method, url, pformat(kwargs))
+
+    def _log_response(self, response):
+        """
+        Logs information about the Box API response.
+
+        :param response: The Box API response.
+        """
+        if response.ok:
+            self._logger.info('\x1b[32m%s\x1b[0m', response.content)
+        else:
+            self._logger.warning(
+                '\x1b[31m%s\n%s\n%s\n\x1b[0m',
+                response.status_code,
+                response.headers,
+                pformat(response.content),
+            )
+
+    def request(self, method, url, access_token, **kwargs):
+        """
+        Base class override. Logs information about an API request and response in addition to making the request.
+        """
+        self._log_request(method, url, **kwargs)
+        response = super(LoggingNetwork, self).request(method, url, access_token, **kwargs)
+        self._log_response(response)
+        return response

boxsdk/util/log.py

@@ -0,0 +1,37 @@
+# coding: utf-8
+
+from __future__ import unicode_literals
+import logging
+import sys
+
+
+def setup_logging(stream_or_file=None, debug=False, name=None):
+    """
+    Create a logger for communicating with the user or writing to log files.
+    By default, creates a root logger that prints to stdout.
+
+    :param stream_or_file:
+        The destination of the log messages. If None, stdout will be used.
+    :type stream_or_file:
+        `unicode` or `file` or None
+    :param debug:
+        Whether or not the logger will be at the DEBUG level (if False, the logger will be at the INFO level).
+    :type debug:
+        `bool` or None
+    :param name:
+        The logging channel. If None, a root logger will be created.
+    :type name:
+        `unicode` or None
+    :return:
+        A logger that's been set up according to the specified parameters.
+    :rtype:
+        :class:`Logger`
+    """
+    logger = logging.getLogger(name)
+    if isinstance(stream_or_file, basestring):
+        handler = logging.FileHandler(stream_or_file, mode='w')
+    else:
+        handler = logging.StreamHandler(stream_or_file or sys.stdout)
+    logger.addHandler(handler)
+    logger.setLevel(logging.DEBUG if debug else logging.INFO)
+    return logger

requirements.txt

@@ -1,4 +1,5 @@
 cryptography>=0.9.2
+redis>=2.10.3
 pyjwt>=1.3.0
 requests>=2.4.3
 six >= 1.4.0

setup.py

@@ -53,6 +53,7 @@ def run_tests(self):
 def main():
     base_dir = dirname(__file__)
     install_requires = ['requests>=2.4.3', 'six>=1.4.0']
+    redis_requires = ['redis>=2.10.3']
     jwt_requires = ['pyjwt>=1.3.0', 'cryptography>=0.9.2']
     if version_info < (3, 4):
         install_requires.append('enum34>=1.0.4')
@@ -68,7 +69,7 @@ def main():
         url='http://opensource.box.com',
         packages=find_packages(exclude=['demo', 'docs', 'test']),
         install_requires=install_requires,
-        extras_require={'jwt': jwt_requires},
+        extras_require={'jwt': jwt_requires, 'redis': redis_requires},
         tests_require=['pytest', 'pytest-xdist', 'mock', 'sqlalchemy', 'bottle', 'jsonpatch'],
         cmdclass={'test': PyTest},
         classifiers=CLASSIFIERS,