Add support for automated rate-limit handling

Refactor RestSession class to provide support for automatic retries on
receiving rate-limit responses from Cisco Spark.

Deprecate package-level `timeout` setting and recommend the use of the
more descriptive `single_request_timeout`.

Add test cases for new timers.

Author: cmlccie

ciscosparkapi/__init__.py

@@ -16,7 +16,11 @@
 import os
 
 from ciscosparkapi.exceptions import ciscosparkapiException, SparkApiError
-from ciscosparkapi.restsession import RestSession
+from ciscosparkapi.restsession import (
+    DEFAULT_SINGLE_REQUEST_TIMEOUT,
+    DEFAULT_RATE_LIMIT_TIMEOUT,
+    RestSession,
+)
 from ciscosparkapi.api.people import Person, PeopleAPI
 from ciscosparkapi.api.rooms import Room, RoomsAPI
 from ciscosparkapi.api.memberships import Membership, MembershipsAPI
@@ -45,8 +49,8 @@
 del get_versions
 
 
+# Package Constants
 DEFAULT_BASE_URL = 'https://api.ciscospark.com/v1/'
-DEFAULT_TIMEOUT = 60
 ACCESS_TOKEN_ENVIRONMENT_VARIABLE = 'SPARK_ACCESS_TOKEN'
 
 
@@ -91,7 +95,9 @@ class CiscoSparkAPI(object):
     """
 
     def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
-                 timeout=DEFAULT_TIMEOUT):
+                 timeout=None,
+                 single_request_timeout=DEFAULT_SINGLE_REQUEST_TIMEOUT,
+                 rate_limit_timeout=DEFAULT_RATE_LIMIT_TIMEOUT):
         """Create a new CiscoSparkAPI object.
 
         An access token must be used when interacting with the Cisco Spark API.
@@ -126,25 +132,27 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
                 variable.
 
         """
-        # Process args
         assert access_token is None or isinstance(access_token, basestring)
-        assert isinstance(base_url, basestring)
-        assert isinstance(timeout, int)
-        spark_access_token = os.environ.get(ACCESS_TOKEN_ENVIRONMENT_VARIABLE)
-        access_token = access_token if access_token else spark_access_token
+        env_access_token = os.environ.get(ACCESS_TOKEN_ENVIRONMENT_VARIABLE)
+        access_token = access_token if access_token else env_access_token
         if not access_token:
             error_message = "You must provide an Spark access token to " \
                             "interact with the Cisco Spark APIs, either via " \
                             "a SPARK_ACCESS_TOKEN environment variable " \
                             "or via the access_token argument."
             raise ciscosparkapiException(error_message)
-        session_args = {u'timeout': timeout}
 
         # Create the API session
         # All of the API calls associated with a CiscoSparkAPI object will
         # leverage a single RESTful 'session' connecting to the Cisco Spark
         # cloud.
-        self._session = RestSession(access_token, base_url, **session_args)
+        self._session = RestSession(
+                access_token,
+                base_url,
+                timeout=timeout,
+                single_request_timeout=single_request_timeout,
+                rate_limit_timeout=rate_limit_timeout,
+        )
 
         # Spark API wrappers
         self.people = PeopleAPI(self._session)
@@ -170,3 +178,11 @@ def base_url(self):
     @property
     def timeout(self):
         return self._session.timeout
+
+    @property
+    def single_request_timeout(self):
+        return self._session.single_request_timeout
+
+    @property
+    def rate_limit_timeout(self):
+        return self._session.rate_limit_timeout

ciscosparkapi/exceptions.py

@@ -33,6 +33,7 @@
     409: "The request could not be processed because it conflicts with some "
          "established rule of the system. For example, a person may not be "
          "added to a room more than once.",
+    429: "Rate limit exceeded.",
     500: "Something went wrong on the server.",
     503: "Server is overloaded with requests. Try again later."
 }