Bump version to 1.5.0.

* Use custom user agent for requests to Box.
* Add LoggingClient and DevelopmentClient classes.

Author: Jeff-Meadows

HISTORY.rst

@@ -6,6 +6,20 @@ Release History
 Upcoming
 ++++++++
 
+
+1.5.0 (2016-02-26)
+++++++++++++++++++
+
+- Added a new class, ``LoggingClient``. It's a ``Client`` that uses the ``LoggingNetwork`` class so that
+  requests to the Box API and its responses are logged.
+- Added a new class, ``DevelopmentClient`` that combines ``LoggingClient`` with the existing
+  ``DeveloperTokenClient``. This client is ideal for exploring the Box API or for use when developing your application.
+- Made the ``oauth`` parameter to ``Client`` optional. The constructor now accepts new parameters that it will use
+  to construct the ``OAuth2`` instance it needs to auth with the Box API.
+- Changed the default User Agent string sent with requests to the Box API. It is now 'box-python-sdk-<version>'.
+
+
+
 1.4.2 (2016-02-23)
 ++++++++++++++++++
 

README.rst

@@ -349,18 +349,47 @@ For advanced uses of the SDK, two additional auth classes are provided:
   multiple machines) to share access tokens while synchronizing token refresh. This could be useful for a multiprocess
   web server, for example.
 
-Other Network Options
----------------------
+Other Client Options
+--------------------
+
+Logging Client
+~~~~~~~~~~~~~~
 
-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 ``LoggingClient`` class. This class logs
 information about network requests and responses made to the Box API.
 
-.. code-block:: python
+.. code-block:: pycon
+
+    >>> from boxsdk import LoggingClient
+    >>> client = LoggingClient()
+    >>> client.user().get()
+    GET https://api.box.com/2.0/users/me {'headers': {u'Authorization': u'Bearer ---------------------------kBjp',
+                 u'User-Agent': u'box-python-sdk-1.5.0'},
+     'params': None}
+    {"type":"user","id":"..","name":"Jeffrey Meadows","login":"..",..}
+    <boxsdk.object.user.User at 0x10615b8d0>
+
+For more control over how the information is logged, use the ``LoggingNetwork`` class directly.
+
+.. code-block:: pycon
 
     from boxsdk import Client
     from boxsdk.network.logging_network import LoggingNetwork
 
-    client = Client(oauth, network_layer=LoggingNetwork())
+    # Use a custom logger
+    client = Client(oauth, network_layer=LoggingNetwork(logger))
+
+Development Client
+~~~~~~~~~~~~~~~~~~
+
+For exploring the Box API, or to quickly get going using the SDK, the ``DevelopmentClient`` class combines the
+``LoggingClient`` with the ``DeveloperTokenClient``.
+
+Developer Token Client
+~~~~~~~~~~~~~~~~~~~~~~
+
+The Box Developer Console allows for the creation of short-lived developer tokens. The SDK makes it easy to use these
+tokens. Use the
 
 Contributing
 ------------

boxsdk/__init__.py

@@ -3,5 +3,7 @@
 from __future__ import unicode_literals
 
 from .auth import JWTAuth, OAuth2
-from .client import Client, DeveloperTokenClient
+from .client import *  # pylint:disable=wildcard-import,redefined-builtin
 from .object import *  # pylint:disable=wildcard-import,redefined-builtin
+from .config import Version
+__version__ = Version.VERSION

boxsdk/client/__init__.py

@@ -0,0 +1,15 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+from .client import Client
+from .developer_token_client import DeveloperTokenClient
+from .logging_client import LoggingClient
+
+
+class DevelopmentClient(DeveloperTokenClient, LoggingClient):
+    """
+    Client subclass that uses developer token auth and logs requests and responses.
+    Great for use in development!
+    """
+    pass

boxsdk/client.py renamed to boxsdk/client/client.py

@@ -3,24 +3,33 @@
 from __future__ import unicode_literals
 import json
 
-from .auth import DeveloperTokenAuth
-from .config import API
-from .session.box_session import BoxSession
-from .network.default_network import DefaultNetwork
-from .object.user import User
-from .object.folder import Folder
-from .object.search import Search
-from .object.events import Events
-from .object.file import File
-from .object.group import Group
-from .object.group_membership import GroupMembership
-from .util.shared_link import get_shared_link_header
-from .util.translator import Translator
+from ..auth import OAuth2
+from ..config import API
+from ..session.box_session import BoxSession
+from ..network.default_network import DefaultNetwork
+from ..object.user import User
+from ..object.folder import Folder
+from ..object.search import Search
+from ..object.events import Events
+from ..object.file import File
+from ..object.group import Group
+from ..object.group_membership import GroupMembership
+from ..util.shared_link import get_shared_link_header
+from ..util.translator import Translator
 
 
 class Client(object):
 
-    def __init__(self, oauth, network_layer=None, session=None):
+    def __init__(
+            self,
+            oauth=None,
+            network_layer=None,
+            session=None,
+            client_id=None,
+            client_secret=None,
+            store_tokens=None,
+            **kwargs
+    ):
         """
         :param oauth:
             OAuth2 object used by the session to authorize requests.
@@ -34,12 +43,37 @@ def __init__(self, oauth, network_layer=None, session=None):
             The session object to use. If None is provided then an instance of :class:`BoxSession` will be used.
         :type session:
             :class:`BoxSession`
+        :param client_id:
+            Box API key used for identifying the application the user is authenticating with.
+            Ignored if oauth instance is passed into this constructor.
+        :type client_id:
+            `unicode`
+        :param client_secret:
+            Box API secret used for making OAuth2 requests.
+            Ignored if oauth instance is passed into this constructor.
+        :type client_secret:
+            `unicode`
+        :param store_tokens:
+            Optional callback for getting access to tokens for storing them.
+            Ignored if oauth instance is passed into this constructor.
+        :type store_tokens:
+            `callable`
         """
         network_layer = network_layer or DefaultNetwork()
-        self._oauth = oauth
+        self._oauth = oauth or OAuth2(client_id, client_secret, store_tokens=store_tokens, **kwargs)
         self._network = network_layer
         self._session = session or BoxSession(oauth=oauth, network_layer=network_layer)
 
+    @property
+    def auth(self):
+        """
+        Get the :class:`OAuth2` instance the client is using for auth to Box.
+
+        :rtype:
+            :class:`OAuth2`
+        """
+        return self._oauth
+
     def folder(self, folder_id):
         """
         Initialize a :class:`Folder` object, whose box id is folder_id.
@@ -359,11 +393,3 @@ def with_shared_link(self, shared_link, shared_link_password):
             self._network,
             self._session.with_shared_link(shared_link, shared_link_password),
         )
-
-
-class DeveloperTokenClient(Client):
-    """
-    Box client subclass which authorizes with a developer token.
-    """
-    def __init__(self, oauth=None, network_layer=None, session=None):
-        super(DeveloperTokenClient, self).__init__(oauth or DeveloperTokenAuth(), network_layer, session)

boxsdk/client/developer_token_client.py

@@ -0,0 +1,19 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+from ..auth import DeveloperTokenAuth
+from .client import Client
+
+
+class DeveloperTokenClient(Client):
+    """
+    Box client subclass which authorizes with a developer token.
+    """
+    def __init__(self, oauth=None, network_layer=None, session=None, **kwargs):
+        super(DeveloperTokenClient, self).__init__(
+            oauth=oauth or DeveloperTokenAuth(),
+            network_layer=network_layer,
+            session=session,
+            **kwargs
+        )

boxsdk/client/logging_client.py

@@ -0,0 +1,19 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+from .client import Client
+from ..network.logging_network import LoggingNetwork
+
+
+class LoggingClient(Client):
+    """
+    Box client subclass which logs requests and responses.
+    """
+    def __init__(self, oauth=None, network_layer=None, session=None, **kwargs):
+        super(LoggingClient, self).__init__(
+            oauth,
+            network_layer=network_layer or LoggingNetwork(),
+            session=session,
+            **kwargs
+        )

boxsdk/config.py

@@ -9,3 +9,9 @@ class API(object):
     UPLOAD_URL = 'https://upload.box.com/api/2.0'
     OAUTH2_API_URL = 'https://api.box.com/oauth2'  # <https://developers.box.com/docs/#oauth-2>
     OAUTH2_AUTHORIZE_URL = 'https://app.box.com/api/oauth2/authorize'  # <https://developers.box.com/docs/#oauth-2-authorize>
+
+
+class Version(object):
+    """Configuration object containing the package version and user agent string."""
+    VERSION = '1.4.3'
+    USER_AGENT_STRING = 'box-python-sdk-{0}'.format(VERSION)

boxsdk/session/box_session.py

@@ -2,6 +2,7 @@
 
 from __future__ import unicode_literals
 
+from boxsdk.config import Version
 from boxsdk.exception import BoxAPIException
 from boxsdk.util.multipart_stream import MultipartStream
 from boxsdk.util.shared_link import get_shared_link_header
@@ -81,7 +82,7 @@ def __init__(self, oauth, network_layer, default_headers=None):
         """
         self._oauth = oauth
         self._network_layer = network_layer
-        self._default_headers = default_headers or {}
+        self._default_headers = default_headers or {'User-Agent': Version.USER_AGENT_STRING}
 
     def as_user(self, user):
         """

docs/source/boxsdk.client.rst

@@ -0,0 +1,38 @@
+boxsdk.client package
+=====================
+
+Submodules
+----------
+
+boxsdk.client.client module
+---------------------------
+
+.. automodule:: boxsdk.client.client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+boxsdk.client.developer_token_client module
+-------------------------------------------
+
+.. automodule:: boxsdk.client.developer_token_client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+boxsdk.client.logging_client module
+-----------------------------------
+
+.. automodule:: boxsdk.client.logging_client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: boxsdk.client
+    :members:
+    :undoc-members:
+    :show-inheritance: