Merge pull request #121 from Jeff-Meadows/docs

Docs

Author: Jeff-Meadows

AUTHORS.rst

@@ -0,0 +1,9 @@
+The Box Python SDK is an open source project supported by `Box <https://box.com>`_
+used to interact with the Box API. This is a list of contributors.
+
+- `@Jeff-Meadows <https://github.com/Jeff-Meadows>`_
+- `@jmoldow <https://github.com/jmoldow>`_
+- `@aptxkid <https://github.com/aptxkid>`_
+- `@hnguyen08 <https://github.com/hnguyen08>`_
+- `@potrebic <https://github.com/potrebic>`_
+- `@nsundareswaran <https://github.com/nsundareswaran>`_

CONTRIBUTING.rst

@@ -53,7 +53,7 @@ To add an upstream source for this project, type:
 
     git remote add upstream [email protected]:box/box-python-sdk.git
 
-This will come in useful later.
+This will become useful later.
 
 Step 4: Create a feature branch
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -103,3 +103,7 @@ a description that lets us know what work you did.
 Keep in mind that we like to see one issue addressed per pull request,
 as this helps keep our git history clean and we can more easily track
 down issues.
+
+Finally, please add a note in HISTORY.rst under the Upcoming section detailing what's new in your change.
+These will become the release notes for the next release.
+In addition, feel free to add yourself to AUTHORS.rst if you aren't already listed.

HISTORY.rst

@@ -6,6 +6,24 @@ Release History
 Upcoming
 ++++++++
 
+
+
+1.5.0 (2016-03-17)
+++++++++++++++++++
+
+- 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>'.
+- Box objects have an improved ``__repr__``, making them easier to identify during debugging sessions.
+- Box objects now implement ``__dir__``, making them easier to explore. When created with a Box API response,
+  these objects will now include the API response fields as attributes.
+
+
+
 1.4.2 (2016-02-23)
 ++++++++++++++++++
 

README.rst

@@ -262,20 +262,18 @@ supported by the SDK. You can still use these endpoints by using the ``make_requ
 .. 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),
+        client.get_url('metadata_templates', 'enterprise', 'customer', 'schema'),
     ).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
+The ``Client`` class and Box objects have a ``get_url`` method. Pass it an endpoint
 to get the correct URL for use with that object and endpoint.
 
 Box Developer Edition
@@ -349,18 +347,48 @@ 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))
+
+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 ``get_new_token_callback`` parameter to control how the client will get new developer tokens as
+needed. The default is to prompt standard input for a token.
+
+Development Client
+~~~~~~~~~~~~~~~~~~
+
+For exploring the Box API, or to quickly get going using the SDK, the ``DevelopmentClient`` class combines the
+``LoggingClient`` with the ``DeveloperTokenClient``.
 
 Contributing
 ------------

boxsdk/__init__.py

@@ -1,7 +1,8 @@
 # coding: utf-8
 
-from __future__ import unicode_literals
+from __future__ import unicode_literals, absolute_import
 
 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 .version import __version__

boxsdk/client/__init__.py

@@ -0,0 +1,8 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+from .client import Client
+from .developer_token_client import DeveloperTokenClient
+from .development_client import DevelopmentClient
+from .logging_client import LoggingClient

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

@@ -1,26 +1,30 @@
 # coding: utf-8
 
-from __future__ import unicode_literals
+from __future__ import unicode_literals, absolute_import
 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 ..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,
+    ):
         """
         :param oauth:
             OAuth2 object used by the session to authorize requests.
@@ -40,6 +44,16 @@ def __init__(self, oauth, network_layer=None, session=None):
         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.
@@ -360,10 +374,20 @@ def with_shared_link(self, shared_link, shared_link_password):
             self._session.with_shared_link(shared_link, shared_link_password),
         )
 
+    def get_url(self, endpoint, *args):
+        """
+        Return the URL for the given Box API endpoint.
 
-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)
+        :param endpoint:
+            The name of the endpoint.
+        :type endpoint:
+            `url`
+        :param args:
+            Additional parts of the endpoint URL.
+        :type args:
+            `Iterable`
+        :rtype:
+            `unicode`
+        """
+        # pylint:disable=no-self-use
+        return self._session.get_url(endpoint, *args)

boxsdk/client/developer_token_client.py

@@ -0,0 +1,18 @@
+# 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):
+        super(DeveloperTokenClient, self).__init__(
+            oauth=oauth or DeveloperTokenAuth(),
+            network_layer=network_layer,
+            session=session,
+        )

boxsdk/client/development_client.py

@@ -0,0 +1,14 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+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/logging_client.py

@@ -0,0 +1,18 @@
+# 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):
+        super(LoggingClient, self).__init__(
+            oauth=oauth,
+            network_layer=network_layer or LoggingNetwork(),
+            session=session,
+        )