Merge branch 'master' into jwt

Author: Jeff-Meadows

.pylintrc

@@ -7,9 +7,6 @@
 # pygtk.require().
 #init-hook=
 
-# Profiled execution.
-profile=no
-
 # Add files or directories to the blacklist. They should be base names, not
 # paths.
 #ignore=CVS
@@ -68,20 +65,13 @@ reports=no
 # (RP0004).
 evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
 
-# Add a comment according to your evaluation note. This is used by the global
-# evaluation report (RP0004).
-comment=no
-
 # Template used to display messages. This is a python new-style format string
 # used to format the massage information. See doc for all details
 msg-template={module}:{line}:{column}: [{msg_id}({symbol}), {obj}] {msg}
 
 
 [BASIC]
 
-# Required attributes for module, separated by a comma
-required-attributes=
-
 # List of builtins function names that should not be used, separated by a comma
 bad-functions=map,filter,apply,input
 
@@ -131,6 +121,8 @@ no-docstring-rgx=__.*__
 # ones are exempt.
 docstring-min-length=-1
 
+# Maximum number of nested blocks for function / method body
+max-nested-blocks=6
 
 [FORMAT]
 
@@ -180,10 +172,6 @@ ignore-mixin-members=yes
 #ignored-classes=SQLObject
 ignored-classes=pytest, _pytest
 
-# When zope mode is activated, add a predefined set of Zope acquired attributes
-# to generated-members.
-zope=no
-
 # List of members which are set dynamically and missed by pylint inference
 # system, and so shouldn't trigger E0201 when accessed. Python regular
 # expressions are accepted.
@@ -206,10 +194,6 @@ additional-builtins=
 
 [CLASSES]
 
-# List of interface methods to ignore, separated by a comma. This is used for
-# instance to not check methods defines in Zope's Interface base class.
-ignore-iface-methods=
-
 # List of method names used to declare (i.e. assign) instance attributes.
 defining-attr-methods=__init__,__new__,setUp
 

.travis.yml

@@ -21,7 +21,7 @@ matrix:
     - python: 3.5
       env: TOX_ENV=py35
     - python: pypy
-      env: TOX_ENV=pypy
+      env: TOX_ENV=pypy PYPY_VERSION='4.0.0'
     - python: 2.7
       env: TOX_ENV=pep8
     - python: 2.7

.travis/install.sh

@@ -42,21 +42,21 @@ if [[ "$(uname -s)" == 'Darwin' ]]; then
             pyenv global 3.5.0
             ;;
         pypy)
-            pyenv install pypy-2.6.0
-            pyenv global pypy-2.6.0
+            pyenv install "pypy-${PYPY_VERSION}"
+            pyenv global "pypy-${PYPY_VERSION}"
             ;;
     esac
     pyenv rehash
     python -m pip install -U --user virtualenv
 else
-    # temporary pyenv installation to get pypy-2.6 before container infra upgrade
+    # pyenv installation to get specified pypy version (Travis may only have older version(s))
     if [[ "${TOX_ENV}" == "pypy" ]]; then
         git clone https://github.com/yyuu/pyenv.git $PWD/.pyenv
         export PYENV_ROOT="$PWD/.pyenv"
         export PATH="$PYENV_ROOT/bin:$PATH"
         eval "$(pyenv init -)"
-        pyenv install pypy-2.6.0
-        pyenv global pypy-2.6.0
+        pyenv install "pypy-${PYPY_VERSION}"
+        pyenv global "pypy-${PYPY_VERSION}"
     fi
     pip install -U virtualenv
 fi

.travis/run.sh

@@ -14,7 +14,7 @@ else
         export PYENV_ROOT="$PWD/.pyenv"
         export PATH="$PYENV_ROOT/bin:$PATH"
         eval "$(pyenv init -)"
-        pyenv global pypy-2.6.0
+        pyenv global "pypy-${PYPY_VERSION}"
     fi
 fi
 source $PWD/.venv/bin/activate

HISTORY.rst

@@ -6,11 +6,46 @@ Release History
 Upcoming
 ++++++++
 
+1.3.3 (2016-01-04)
+++++++++++++++++++
+
+**Bugfixes**
+
+- Fixed import error for installations that don't have redis installed.
+- Fixed use of ``raw_input`` in the developer token auth for py3 compatibility.
+
+
+1.3.3 (2015-12-22)
+++++++++++++++++++
+
+- Added a new class, ``DeveloperTokenClient`` that makes it easy to get started using the SDK with a Box developer
+  token. It uses another new class, ``DeveloperTokenAuth`` for auth.
+
+**Bugfixes**
+
+- Added limit, offset, and filter_term parameters to ``client.users()`` to match up with the Box API.
+
+1.3.2 (2015-11-16)
+++++++++++++++++++
+
+- Fix ``boxsdk.util.log.setup_logging()`` on Python 3.
+
+1.3.1 (2015-11-06)
+++++++++++++++++++
+
+- Add requests-toolbelt to setup.py (it was accidentally missing from 1.3.0).
+
+1.3.0 (2015-11-05)
+++++++++++++++++++
+
 - 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.
+- Stream uploads of files from disk.
 
-1.2.1 (2015-07-22)
+1.2.2 (2015-07-22)
 ++++++++++++++++++
 
 - The SDK now supports setting a password when creating a shared link.
@@ -26,11 +61,11 @@ Upcoming
 ++++++++++++++++++
 
 - Added support for Box Developer Edition. This includes JWT auth (auth as enterprise or as app user),
-  and `create_user` functionality.
+  and ``create_user`` functionality.
 - Added support for setting shared link expiration dates.
 - Added support for setting shared link permissions.
 - Added support for 'As-User' requests. See https://box-content.readme.io/#as-user-1
-- Improved support for accessing shared items. Items returned from the `client.get_shared_item` method will
+- Improved support for accessing shared items. Items returned from the ``client.get_shared_item`` method will
   remember the shared link (and the optionally provided shared link password) so methods called on the returned
   items will be properly authorized.
 
@@ -65,7 +100,7 @@ Upcoming
 1.1.3 (2015-03-26)
 ++++++++++++++++++
 
-- Added support for the /shared_items endpoint. `client.get_shared_item` can be used to get information about
+- Added support for the /shared_items endpoint. ``client.get_shared_item`` can be used to get information about
   a shared link. See https://developers.box.com/docs/#shared-items
 
 1.1.2 (2015-03-20)

README.rst

@@ -63,8 +63,8 @@ Authenticate (get access/refresh token)
 
 If you navigate the user to the auth_url, the user will eventually get
 redirected to http://YOUR_REDIRECT_URL?code=YOUR_AUTH_CODE.  After
-getting the code, you will be able to use the code to exchange for
-access token and fresh token.
+getting the code, you will be able to use the code to exchange for an
+access token and refresh token.
 
 The SDK handles all the work for you; all you need to do is run:
 
@@ -248,7 +248,7 @@ instead use an instance of `JWTAuth`.
     auth = JWTAuth(
         client_id='YOUR_CLIENT_ID',
         client_secret='YOUR_CLIENT_SECRET',
-        enterprise_token='YOUR_ENTERPRISE_TOKEN',
+        enterprise_id='YOUR_ENTERPRISE_ID',
         rsa_private_key_file_sys_path='CERT.PEM',
         store_tokens=your_store_tokens_callback_method,
     )
@@ -272,7 +272,7 @@ These users can then be authenticated:
     ned_auth = JWTAuth(
        client_id='YOUR_CLIENT_ID',
        client_secret='YOUR_CLIENT_SECRET',
-       enterprise_token='YOUR_ENTERPRISE_TOKEN',
+       enterprise_id='YOUR_ENTERPRISE_ID',
        rsa_private_key_file_sys_path='CERT.PEM',
        store_tokens=your_store_tokens_callback_method,
    )
@@ -282,6 +282,31 @@ 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:
+
+- `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
+  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
 ------------
@@ -312,7 +337,7 @@ Run all tests using -
 The tox tests include code style checks via pep8 and pylint.
 
 The tox tests are configured to run on Python 2.6, 2.7, 3.3, 3.4, 3.5, and
-PyPy 2.6.
+PyPy (our CI is configured to run PyPy tests on PyPy 4.0).
 
 
 Support

boxsdk/__init__.py

@@ -2,10 +2,6 @@
 
 from __future__ import unicode_literals
 
-try:
-    from .auth.jwt_auth import JWTAuth
-except ImportError:
-    JWTAuth = None  # If extras are not installed, JWTAuth won't be available.
-from .auth.oauth2 import OAuth2
-from .client import Client
+from .auth import JWTAuth, OAuth2
+from .client import Client, DeveloperTokenClient
 from .object import *  # pylint:disable=wildcard-import,redefined-builtin

boxsdk/auth/__init__.py

@@ -1,3 +1,20 @@
 # coding: utf-8
 
 from __future__ import unicode_literals
+
+from .cooperatively_managed_oauth2 import CooperativelyManagedOAuth2
+from .developer_token_auth import DeveloperTokenAuth
+try:
+    from .jwt_auth import JWTAuth
+except ImportError:
+    JWTAuth = None  # If extras[jwt] are not installed, JWTAuth won't be available.
+from .oauth2 import OAuth2
+try:
+    from .redis_managed_oauth2 import RedisManagedOAuth2
+except ImportError:
+    RedisManagedOAuth2 = None  # If extras[redis] are not installed, RedisManagedOAuth2 won't be available.
+try:
+    from .redis_managed_jwt_auth import RedisManagedJWTAuth
+except ImportError:
+    RedisManagedJWTAuth = None  # If extras[jwt,redis] are not installed, RedisManagedJWTAuth won't be available.
+from .remote_managed_oauth2 import RemoteOAuth2

boxsdk/auth/cooperatively_managed_oauth2.py

@@ -0,0 +1,35 @@
+# coding: utf-8
+
+from __future__ import unicode_literals
+from .oauth2 import OAuth2
+
+
+class CooperativelyManagedOAuth2Mixin(OAuth2):
+    """
+    Box SDK OAuth2 mixin.
+    Allows for sharing auth tokens between multiple clients.
+    """
+    def __init__(self, retrieve_tokens=None, *args, **kwargs):
+        """
+        :param retrieve_tokens:
+            Callback to get the current access/refresh token pair.
+        :type retrieve_tokens:
+            `callable` of () => (`unicode`, `unicode`)
+        """
+        self._retrieve_tokens = retrieve_tokens
+        super(CooperativelyManagedOAuth2Mixin, self).__init__(*args, **kwargs)
+
+    def _get_tokens(self):
+        """
+        Base class override. Get the tokens from the user-specified callback.
+        """
+        return self._retrieve_tokens()
+
+
+class CooperativelyManagedOAuth2(CooperativelyManagedOAuth2Mixin):
+    """
+    Box SDK OAuth2 subclass.
+    Allows for sharing auth tokens between multiple clients. The retrieve_tokens callback should
+    return the current access/refresh token pair.
+    """
+    pass

boxsdk/auth/developer_token_auth.py

@@ -0,0 +1,34 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+from six.moves import input  # pylint:disable=redefined-builtin
+
+from .oauth2 import OAuth2
+
+
+class DeveloperTokenAuth(OAuth2):
+    ENTER_TOKEN_PROMPT = 'Enter developer token: '
+
+    def __init__(self, get_new_token_callback=None, **kwargs):
+        self._get_new_token = get_new_token_callback
+        super(DeveloperTokenAuth, self).__init__(
+            client_id=None,
+            client_secret=None,
+            access_token=self._refresh_developer_token(),
+            **kwargs
+        )
+
+    def _refresh_developer_token(self):
+        if self._get_new_token is not None:
+            return self._get_new_token()
+        else:
+            return input(self.ENTER_TOKEN_PROMPT)
+
+    def _refresh(self, access_token):
+        """
+        Base class override.
+        Ask for a new developer token.
+        """
+        self._access_token = self._refresh_developer_token()
+        return self._access_token, None