Rework automatic retry. (#253)

Previously, retries were done recursively, which could lead to large
stacks and even stack overflow. This commit comprises a refactoring
of automatic retry.

* BoxResponse is moved to its own module (from box_session)
* A new class, BoxRequest, exists to keep track of information about
  a specific API request while it's being made or retried.
* BoxSession was refactored so that retries happen iteratively:
  - _make_request was renamed _send_request and takes a BoxRequest.
  - _retry_request_if_necessary was renamed _get_retry_request_callable
    and it now returns a callable that can retry a request, rather
    than actually retrying it.
  _prepare_and_send_request now retries failed requests in a loop
* The retry strategy has changed so that 429 responses won't be
  retried indefinitely - we'll give up after 10 failures regardless
  of whether they are 5xx responses or 429s.

Author: Jeff-Meadows

boxsdk/exception.py

@@ -45,15 +45,15 @@ def __init__(
         :param code:
             The 'code' field of the failed response
         :type code:
-            `unicode`
+            `unicode` or None
         :param message:
             A message to associate with the exception, e.g. 'message' field of the json in the failed response
         :type message:
-            `unicode`
+            `unicode` or None
         :param request_id:
             The 'request_id' field of the json in the failed response
         :type request_id:
-            `unicode`
+            `unicode` or None
         :param headers:
             The HTTP headers in the failed response
         :type headers:
@@ -69,7 +69,7 @@ def __init__(
         :param context_info:
             The context_info returned in the failed response.
         :type context_info:
-            `dict`
+            `dict` or None
         :param network_response:
             The failed response
         :type network_response:

boxsdk/session/box_request.py

@@ -0,0 +1,27 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+import attr
+
+
+@attr.s(slots=True)
+class BoxRequest(object):
+    """Represents a Box API request.
+
+    :param url:                     The URL being requested.
+    :type url:                      `unicode`
+    :param method:                  The HTTP method to use for the request.
+    :type method:                   `unicode` or None
+    :param headers:                 HTTP headers to include with the request.
+    :type headers:                  `dict` or None
+    :param auto_session_renewal:    Whether or not the session can be automatically renewed if the request fails.
+    :type auto_session_renewal:     `bool` or None
+    :param expect_json_response:    Whether or not the API response must be JSON.
+    :type expect_json_response:     `bool` or None
+    """
+    url = attr.ib()
+    method = attr.ib(default='GET')
+    headers = attr.ib(default=attr.Factory(dict))
+    auto_session_renewal = attr.ib(default=True)
+    expect_json_response = attr.ib(default=True)

boxsdk/session/box_response.py

@@ -0,0 +1,58 @@
+# coding: utf-8
+
+from __future__ import unicode_literals, absolute_import
+
+
+class BoxResponse(object):
+    """Represents a response to a Box API request."""
+
+    def __init__(self, network_response):
+        self._network_response = network_response
+
+    def json(self):
+        """Return the parsed JSON response.
+
+        :rtype:
+            `dict` or `list` or `str` or `int` or `float`
+        """
+        return self._network_response.json()
+
+    @property
+    def content(self):
+        """Return the content of the response body.
+
+        :rtype:
+            varies
+        """
+        return self._network_response.content
+
+    @property
+    def ok(self):
+        """Return whether or not the request was successful.
+
+        :rtype:
+            `bool`
+        """
+        # pylint:disable=invalid-name
+        return self._network_response.ok
+
+    @property
+    def status_code(self):
+        """Return the HTTP status code of the response.
+
+        :rtype:
+            `int`
+        """
+        return self._network_response.status_code
+
+    @property
+    def network_response(self):
+        """Return the underlying network response.
+
+        :rtype:
+            :class:`NetworkResponse`
+        """
+        return self._network_response
+
+    def __repr__(self):
+        return '<Box Response[{status_code}]>'.format(status_code=self.status_code)