Prepare for next 2.0.0 alpha release (#183)

Bump version to 2.0.0a3.

Add new release notes.

Start running tests against the development build of Python 3.6
(which is currently in a feature-freeze beta).

gitignore more patterns for Python virtualenv directories.

`six.with_metaclass()` doesn't work with `enum.EnumMeta` in
Python 3.6, because of logic that was added to
`EnumMeta.__prepare__()`. The six bug actually applies to all
versions of Python 3, but I guess it was never noticed until
now.

This adds our own `with_metaclass()` helper function, with the
fix applied to it. Later I'll submit the same patch to six.
Explanation of the bug and the fix are in the docstring.

jsonpatch is not currently compatible with Python 3.6. If we
can't load it during functional testing, then
`@chaos_utils.patch()` will be a no-op.

Author: jmoldow

.gitignore

@@ -11,7 +11,7 @@ __pycache__/
 # Distribution / packaging
 bin/
 .Python
-env/
+env*/
 build/
 develop-eggs/
 dist/
@@ -27,8 +27,10 @@ var/
 *.egg
 MANIFEST
 .eggs/
+.env*/
 .pyenv/
-.venv/
+venv*/
+.venv*/
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

.pylintrc

@@ -201,7 +201,7 @@ defining-attr-methods=__init__,__new__,setUp
 valid-classmethod-first-arg=cls
 
 # List of valid names for the first argument in a metaclass class method.
-valid-metaclass-classmethod-first-arg=mcs
+valid-metaclass-classmethod-first-arg=mcs,metacls
 
 
 [DESIGN]

.travis.yml

@@ -20,6 +20,8 @@ matrix:
       env: TOX_ENV=py34
     - python: 3.5
       env: TOX_ENV=py35
+    - python: "3.6-dev"
+      env: TOX_ENV=py36
     - python: pypy
       env: TOX_ENV=pypy PYPY_VERSION='4.0.0'
     - python: 2.7

.travis/install.sh

@@ -41,6 +41,10 @@ if [[ "$(uname -s)" == 'Darwin' ]]; then
             pyenv install 3.5.0
             pyenv global 3.5.0
             ;;
+        py36)
+            pyenv install 3.6-dev
+            pyenv global 3.6-dev
+            ;;
         pypy)
             pyenv install "pypy-${PYPY_VERSION}"
             pyenv global "pypy-${PYPY_VERSION}"

HISTORY.rst

@@ -22,6 +22,15 @@ Release History
   + Migration: If you still need to treat an ``Event`` as a ``dict``, you can get a deepcopy of the original ``dict``
     using the new property on ``BaseAPIJSONObject``, ``response_object``.
 
+- The logging format strings in ``LoggingNetwork`` have changed in a way that
+  will break logging for any applications that have overridden any of these
+  strings. They now use keyword format placeholders instead of positional
+  placeholders. All custom format strings will now have to use the same keyword
+  format placeholders. Though this is a breaking change, the good news is that
+  using keyword format placeholders means that any future changes will be
+  automatically backwards-compatibile (as long as there aren't any changes to
+  change/remove any of the keywords).
+
 **Features**
 
 - Added more flexibility to the object translation system:
@@ -35,8 +44,36 @@ Release History
     referenced by the ``BoxSession``, instead of directly using the global
     default ``Translator``.
 
+- When the ``auto_session_renewal`` is ``True`` when calling any of the request
+  methods on ``BoxSession``, if there is no access token, ``BoxSession`` will
+  renew the token _before_ making the request. This saves an API call.
+- Various enhancements to the ``JWTAuth`` baseclass:
+
+  - The ``authenticate_app_user()`` method is renamed to
+    ``authenticate_user()``, to reflect that it may now be used to authenticate
+    managed users as well. See the method docstring for details.
+    ``authenticate_app_user()`` is now an alias of ``authenticate_user()``, in
+    order to not introduce an unnecessary backwards-incompatibility.
+  - The ``user`` argument to ``authenticate_user()`` may now be either a user
+    ID string or a ``User`` instance. Before it had to be a ``User`` instance.
+  - The constructor now accepts an optional ``user`` keyword argument, which
+    may be a user ID string or a ``User`` instance. When this is passed,
+    ``authenticate_user()`` and can be called without passing a value for the
+    ``user`` argument. More importantly, this means that ``refresh()`` can be
+    called immediately after construction, with no need for a manual call to
+    ``authenticate_user()``. Combined with the aforementioned improvement to
+    the ``auto_session_renewal`` functionality of ``BoxSession``, this means
+    that authentication for ``JWTAuth`` objects can be done completely
+    automatically, at the time of first API call.
+  - Document that the ``enterprise_id`` argument to ``JWTAuth`` is allowed to
+    be ``None``.
+  - ``authenticate_instance()`` now accepts an ``enterprise`` argument, which
+    can be used to set and authenticate as the enterprise service account user,
+    if ``None`` was passed for ``enterprise_id`` at construction time.
+
 - Added an ``Event`` class.
-- Moved `metadata` method to `Item` so it's now available for `Folder` as well as `File`.
+- Moved ``metadata()`` method to ``Item`` so it's now available for ``Folder``
+  as well as ``File``.
 
 **Other**
 
@@ -47,7 +84,20 @@ Release History
   ``BaseObject`` is the parent of all objects that are a part of the REST API.  Another subclass of
   ``BaseAPIJSONObject``, ``APIJSONObject``, was created to represent pseudo-smart objects such as ``Event`` that are not
   directly accessible through an API endpoint.
+- Added ``network_response_constructor`` as an optional property on the
+  ``Network`` interface. Implementations are encouraged to override this
+  property, and use it to construct ``NetworkResponse`` instances. That way,
+  subclass implementations can easily extend the functionality of the
+  ``NetworkResponse``, by re-overriding this property. This property is defined
+  and used in the ``DefaultNetwork`` implementation.
+- Move response logging to a new ``LoggingNetworkResponse`` class (which is
+  made possible by the aforementioned ``network_response_constructor``
+  property). Now the SDK decides whether to log the response body, based on
+  whether the caller reads or streams the content.
+- Add more information to the request/response logs from ``LoggingNetwork``.
+- Add logging for request exceptions in ``LoggingNetwork``.
 - Fixed an exception that was being raised from ``ExtendableEnumMeta.__dir__()``.
+- CPython 3.6 support.
 
 1.5.3 (2016-05-26)
 ++++++++++++++++++

README.rst

@@ -445,7 +445,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
+The tox tests are configured to run on Python 2.6, 2.7, 3.3, 3.4, 3.5, 3.6, and
 PyPy (our CI is configured to run PyPy tests on PyPy 4.0).
 
 

boxsdk/object/api_json_object.py

@@ -1,11 +1,12 @@
 # coding: utf-8
 
 from __future__ import unicode_literals, absolute_import
+
 from collections import Mapping
 from abc import ABCMeta
-import six
 
 from .base_api_json_object import BaseAPIJSONObject, BaseAPIJSONObjectMeta
+from ..util.compat import with_metaclass
 
 
 class APIJSONObjectMeta(BaseAPIJSONObjectMeta, ABCMeta):
@@ -16,7 +17,7 @@ class APIJSONObjectMeta(BaseAPIJSONObjectMeta, ABCMeta):
     pass
 
 
-class APIJSONObject(six.with_metaclass(APIJSONObjectMeta, BaseAPIJSONObject, Mapping)):
+class APIJSONObject(with_metaclass(APIJSONObjectMeta, BaseAPIJSONObject, Mapping)):
     """Class representing objects that are not part of the REST API."""
 
     def __len__(self):

boxsdk/object/events.py

@@ -2,10 +2,10 @@
 
 from __future__ import unicode_literals, absolute_import
 from requests.exceptions import Timeout
-from six import with_metaclass
 
 from .base_endpoint import BaseEndpoint
 from ..util.api_call_decorator import api_call
+from ..util.compat import with_metaclass
 from ..util.enum import ExtendableEnumMeta
 from ..util.lru_cache import LRUCache
 from ..util.text_enum import TextEnum

boxsdk/util/compat.py

@@ -1,10 +1,12 @@
 # coding: utf-8
 
-from __future__ import division, unicode_literals
-
+from __future__ import absolute_import, division, unicode_literals
 
 from datetime import timedelta
 
+import six
+
+
 if not hasattr(timedelta, 'total_seconds'):
     def total_seconds(delta):
         """
@@ -15,3 +17,61 @@ def total_seconds(delta):
 else:
     def total_seconds(delta):
         return delta.total_seconds()
+
+
+def with_metaclass(meta, *bases, **with_metaclass_kwargs):
+    """Extends the behavior of six.with_metaclass.
+
+    The normal usage (expanded to include temporaries, to make the illustration
+    easier) is:
+
+    .. code-block:: python
+
+        temporary_class = six.with_metaclass(meta, *bases)
+        temporary_metaclass = type(temporary_class)
+
+        class Subclass(temporary_class):
+            ...
+
+        SubclassMeta = type(Subclass)
+
+    In this example:
+
+    - ``temporary_class`` is a class with ``(object,)`` as its bases.
+    - ``temporary_metaclass`` is a metaclass with ``(meta,)`` as its bases.
+    - ``Subclass`` is a class with ``bases`` as its bases.
+    - ``SubclassMeta`` is ``meta``.
+
+    ``six.with_metaclass()`` is defined in such a way that it can make sure
+    that ``Subclass`` has the correct metaclass and bases, while only using
+    syntax which is common to both Python 2 and Python 3.
+    ``temporary_metaclass()`` returns an instance of ``meta``, rather than an
+    instance of itself / a subclass of ``temporary_class``, which is how
+    ``SubclassMeta`` ends up being ``meta``, and how the temporaries don't
+    appear anywhere in the final subclass.
+
+    There are two problems with the current (as of six==1.10.0) implementation
+    of ``six.with_metaclass()``, which this function solves.
+
+    ``six.with_metaclass()`` does not define ``__prepare__()`` on the temporary
+    metaclass. This means that ``meta.__prepare__()`` gets called directly,
+    with bases set to ``(object,)``. If it needed to actually receive
+    ``bases``, then errors might occur. For example, this was a problem when
+    used with ``enum.EnumMeta`` in Python 3.6. Here we make sure that
+    ``__prepare__()`` is defined on the temporary metaclass, and pass ``bases``
+    to ``meta.__prepare__()``.
+
+    Since ``temporary_class`` doesn't have the correct bases, in theory this
+    could cause other problems, besides the previous one, in certain edge
+    cases. To make sure that doesn't become a problem, we make sure that
+    ``temporary_class`` has ``bases`` as its bases, just like the final class.
+    """
+    temporary_class = six.with_metaclass(meta, *bases, **with_metaclass_kwargs)
+    temporary_metaclass = type(temporary_class)
+
+    class TemporaryMetaSubclass(temporary_metaclass):
+        @classmethod
+        def __prepare__(cls, name, this_bases, **kwds):  # pylint:disable=unused-argument
+            return meta.__prepare__(name, bases, **kwds)
+
+    return type.__new__(TemporaryMetaSubclass, str('temporary_class'), bases, {})

boxsdk/util/enum.py

@@ -20,7 +20,9 @@ class ExtendableEnumMeta(EnumMeta):
 
     This allows you to define hierarchies such as this:
 
-        class EnumBase(six.with_metaclass(ExtendableEnumMeta, Enum)): pass
+        from box.util.compat import with_metaclass
+
+        class EnumBase(with_metaclass(ExtendableEnumMeta, Enum)): pass
 
         class Enum1(EnumBase):
             A = 'A'