Automatic Rate-Limit Handling & CI Testing

Added automatic rate-limit handling and CI Testing through (TravisCI).

Author: cmlccie

Makefile

@@ -31,15 +31,19 @@ tests: toxtest lint ;
 
 .PHONY : ci
 ci :
-	pytest
+	pytest -m "not ratelimit"
 
 .PHONY : toxtest
 toxtest : local/environment.sh tox.ini
 	source local/environment.sh && tox
 
 .PHONY : pytest
 pytest : local/environment.sh
-	source local/environment.sh && pytest
+	source local/environment.sh && pytest -m "not ratelimit"
+
+.PHONY : pytest-rate-limit
+pytest-rate-limit : local/environment.sh
+	source local/environment.sh && pytest -m "ratelimit"
 
 .PHONY : lint
 lint :

README.rst

@@ -4,8 +4,12 @@ ciscosparkapi
 
 *Simple, lightweight, scalable Python API wrapper for the Cisco Spark APIs*
 
+.. image:: https://img.shields.io/badge/license-MIT-blue.svg
+    :target: https://github.com/CiscoDevNet/ciscosparkapi/blob/master/LICENSE
 .. image:: https://img.shields.io/pypi/v/ciscosparkapi.svg
     :target: https://pypi.python.org/pypi/ciscosparkapi
+.. image:: https://travis-ci.org/CiscoDevNet/ciscosparkapi.svg?branch=master
+    :target: https://travis-ci.org/CiscoDevNet/ciscosparkapi
 .. image:: https://readthedocs.org/projects/ciscosparkapi/badge/?version=latest
     :target: http://ciscosparkapi.readthedocs.io/en/latest/?badge=latest
 
@@ -74,6 +78,8 @@ ciscosparkapi does all of this for you...
 
 + **Automatic and transparent pagination!**
 
++ **Automatic rate-limit handling!** *(wait|retry)*
+
 + Multipart encoding and uploading of local files
 
 + Auto-completion in your favorite IDE, descriptive exceptions, and so much

ciscosparkapi/__init__.py

@@ -12,10 +12,15 @@
 from builtins import *
 from past.builtins import basestring
 
+import logging
 import os
 
 from ciscosparkapi.exceptions import ciscosparkapiException, SparkApiError
-from ciscosparkapi.restsession import RestSession
+from ciscosparkapi.restsession import (
+    DEFAULT_SINGLE_REQUEST_TIMEOUT,
+    DEFAULT_WAIT_ON_RATE_LIMIT,
+    RestSession,
+)
 from ciscosparkapi.api.people import Person, PeopleAPI
 from ciscosparkapi.api.rooms import Room, RoomsAPI
 from ciscosparkapi.api.memberships import Membership, MembershipsAPI
@@ -44,11 +49,17 @@
 del get_versions
 
 
+# Package Constants
 DEFAULT_BASE_URL = 'https://api.ciscospark.com/v1/'
-DEFAULT_TIMEOUT = 60
 ACCESS_TOKEN_ENVIRONMENT_VARIABLE = 'SPARK_ACCESS_TOKEN'
 
 
+# Initialize Package Logging
+logger = logging.getLogger(__name__)
+logger.addHandler(logging.NullHandler())
+
+
+# Main Package Interface
 class CiscoSparkAPI(object):
     """Cisco Spark API wrapper.
 
@@ -84,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,
+                 wait_on_rate_limit=DEFAULT_WAIT_ON_RATE_LIMIT):
         """Create a new CiscoSparkAPI object.
 
         An access token must be used when interacting with the Cisco Spark API.
@@ -106,8 +119,13 @@ def __init__(self, access_token=None, base_url=DEFAULT_BASE_URL,
             base_url(basestring): The base URL to be prefixed to the
                 individual API endpoint suffixes.
                 Defaults to ciscosparkapi.DEFAULT_BASE_URL.
-            timeout(int): Timeout (in seconds) for RESTful HTTP requests.
-                Defaults to ciscosparkapi.DEFAULT_TIMEOUT.
+            timeout(int): [deprecated] Timeout (in seconds) for RESTful HTTP
+                requests. Defaults to ciscosparkapi.DEFAULT_TIMEOUT.
+            single_request_timeout(int): Timeout (in seconds) for RESTful HTTP
+                requests. Defaults to
+                ciscosparkapi.DEFAULT_SINGLE_REQUEST_TIMEOUT.
+            wait_on_rate_limit(bool): Enables or disables automatic rate-limit
+                handling. Defaults to ciscosparkapi.DEFAULT_WAIT_ON_RATE_LIMIT.
 
         Returns:
             CiscoSparkAPI: A new CiscoSparkAPI object.
@@ -119,25 +137,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,
+            wait_on_rate_limit=wait_on_rate_limit
+        )
 
         # Spark API wrappers
         self.people = PeopleAPI(self._session)
@@ -163,3 +183,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 wait_on_rate_limit(self):
+        return self._session.wait_on_rate_limit

ciscosparkapi/api/accesstokens.py

@@ -28,11 +28,11 @@
 
 from ciscosparkapi.sparkdata import SparkData
 from ciscosparkapi.utils import (
-    ERC,
     validate_base_url,
     check_response_code,
     extract_and_parse_json,
 )
+from ciscosparkapi.responsecodes import EXPECTED_RESPONSE_CODE
 
 
 __author__ = "Chris Lunsford"
@@ -156,7 +156,7 @@ def get(self, client_id, client_secret, code, redirect_uri):
         # API request
         response = requests.post(self._endpoint_url, data=data,
                                  **self._request_kwargs)
-        check_response_code(response, ERC['POST'])
+        check_response_code(response, EXPECTED_RESPONSE_CODE['POST'])
         json_data = extract_and_parse_json(response)
         # Return a AccessToken object created from the response JSON data
         return AccessToken(json_data)
@@ -194,7 +194,7 @@ def refresh(self, client_id, client_secret, refresh_token):
         # API request
         response = requests.post(self._endpoint_url, data=data,
                                  **self._request_kwargs)
-        check_response_code(response, ERC['POST'])
+        check_response_code(response, EXPECTED_RESPONSE_CODE['POST'])
         json_data = extract_and_parse_json(response)
         # Return a AccessToken object created from the response JSON data
         return AccessToken(json_data)

ciscosparkapi/exceptions.py

@@ -12,53 +12,105 @@
 from builtins import *
 from past.builtins import basestring
 
+import json
+
+import requests
+
+from collections import OrderedDict
+
+from ciscosparkapi.responsecodes import SPARK_RESPONSE_CODES
+
 
 __author__ = "Chris Lunsford"
 __author_email__ = "[email protected]"
 __copyright__ = "Copyright (c) 2016 Cisco Systems, Inc."
 __license__ = "MIT"
 
 
-SPARK_RESPONSE_CODES = {
-    200: "OK",
-    204: "Member deleted.",
-    400: "The request was invalid or cannot be otherwise served. An "
-         "accompanying error message will explain further.",
-    401: "Authentication credentials were missing or incorrect.",
-    403: "The request is understood, but it has been refused or access is not "
-         "allowed.",
-    404: "The URI requested is invalid or the resource requested, such as a "
-         "user, does not exist. Also returned when the requested format is "
-         "not supported by the requested method.",
-    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.",
-    500: "Something went wrong on the server.",
-    503: "Server is overloaded with requests. Try again later."
-}
-
-
 class ciscosparkapiException(Exception):
     """Base class for all ciscosparkapi package exceptions."""
 
-    def __init__(self, *args, **kwargs):
-        super(ciscosparkapiException, self).__init__(*args, **kwargs)
+    def __init__(self, *error_message_args, **error_data):
+        super(ciscosparkapiException, self).__init__()
+
+        self.error_message_args = error_message_args
+        self.error_data = OrderedDict(error_data)
+
+    @property
+    def error_message(self):
+        """The error message created from the error message arguments."""
+        if not self.error_message_args:
+            return ""
+        elif len(self.error_message_args) == 1:
+            return str(self.error_message_args[0])
+        elif len(self.error_message_args) > 1 \
+                and isinstance(self.error_message_args[0], basestring):
+            return self.error_message_args[0] % self.error_message_args[1:]
+        else:
+            return "; ".join(self.error_message_args)
+
+    def __repr__(self):
+        """String representation of the exception."""
+        arg_list = self.error_message_args
+        kwarg_list = [str(key) + "=" + repr(value)
+                      for key, value in self.error_data.items()]
+        arg_string = ", ".join(arg_list + kwarg_list)
+
+        return self.__class__.__name__ + "(" + arg_string + ")"
+
+    def __str__(self):
+        """Human readable string representation of the exception."""
+        return self.error_message + '\n' + \
+            json.dumps(self.error_data, indent=4)
 
 
 class SparkApiError(ciscosparkapiException):
     """Errors returned by requests to the Cisco Spark cloud APIs."""
 
-    def __init__(self, response_code, request=None, response=None):
-        assert isinstance(response_code, int)
-        self.response_code = response_code
-        self.request = request
+    def __init__(self, response):
+        assert isinstance(response, requests.Response)
+
+        super(SparkApiError, self).__init__()
+
+        # Convenience data attributes
+        self.request = response.request
         self.response = response
-        response_text = SPARK_RESPONSE_CODES.get(response_code)
-        if response_text:
-            self.response_text = response_text
-            error_message = "Response Code [{!s}] - {}".format(response_code,
-                                                               response_text)
-        else:
-            error_message = "Response Code [{!s}] - " \
-                            "Unknown Response Code".format(response_code)
-        super(SparkApiError, self).__init__(error_message)
+        self.response_code = response.status_code
+        self.response_text = SPARK_RESPONSE_CODES.get(self.response_code,
+                                                      "Unknown Response Code")
+
+        # Error message and parameters
+        self.error_message_args = [
+            "Response Code [%s] - %s",
+            self.response_code,
+            self.response_text
+        ]
+
+        # Error Data
+        self.error_data["response_code"] = self.response_code
+        self.error_data["description"] = self.response_text
+        if response.text:
+            try:
+                response_data = json.loads(response.text,
+                                           object_pairs_hook=OrderedDict)
+            except ValueError:
+                self.error_data["response_body"] = response.text
+            else:
+                self.error_data["response_body"] = response_data
+
+
+class SparkRateLimitError(SparkApiError):
+    """Cisco Spark Rate-Limit exceeded Error."""
+
+    def __init__(self, response):
+        assert isinstance(response, requests.Response)
+
+        super(SparkRateLimitError, self).__init__(response)
+
+        retry_after = response.headers.get('Retry-After')
+        if retry_after:
+            # Convenience data attributes
+            self.retry_after = float(retry_after)
+
+            # Error Data
+            self.error_data["retry_after"] = self.retry_after

ciscosparkapi/responsecodes.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""Cisco Spark Response Codes."""
+
+
+# Use future for Python v2 and v3 compatibility
+from __future__ import (
+    absolute_import,
+    division,
+    print_function,
+    unicode_literals,
+)
+from builtins import *
+from past.builtins import basestring
+
+
+SPARK_RESPONSE_CODES = {
+    200: "OK",
+    204: "Member deleted.",
+    400: "The request was invalid or cannot be otherwise served. An "
+         "accompanying error message will explain further.",
+    401: "Authentication credentials were missing or incorrect.",
+    403: "The request is understood, but it has been refused or access is not "
+         "allowed.",
+    404: "The URI requested is invalid or the resource requested, such as a "
+         "user, does not exist. Also returned when the requested format is "
+         "not supported by the requested method.",
+    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: "Too many requests have been sent in a given amount of time and the "
+         "request has been rate limited. A Retry-After header should be "
+         "present that specifies how many seconds you need to wait before a "
+         "successful request can be made.",
+    500: "Something went wrong on the server.",
+    503: "Server is overloaded with requests. Try again later."
+}
+
+RATE_LIMIT_RESPONSE_CODE = 429
+
+EXPECTED_RESPONSE_CODE = {
+    'GET': 200,
+    'POST': 200,
+    'PUT': 200,
+    'DELETE': 204
+}