Automatic handling of rate limit

Author: bookernath

README.rst

@@ -103,6 +103,30 @@ wrapper around a lower level api in ``bigcommerce.connection``. This can
 be accessed through ``api.connection``, and provides helper methods for
 get/post/put/delete operations.
 
+Managing OAuth Rate Limits
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can optionally pass a ``rate_limiting_management`` object into ``bigcommerce.api.BigcommerceApi`` or ``bigcommerce.connection.OAuthConnection`` for automatic rate limiting management, ex:
+
+.. code:: python
+
+    import bigcommerce
+
+    api = bigcommerce.api.BigcommerceApi(client_id='', store_hash='', access_token=''
+                                         rate_limiting_management= {'min_requests_remaining':2,
+                                                                    'wait':True,
+                                                                    'callback_function':None})
+
+``min_requests_remaining`` will determine the number of requests remaining in the rate limiting window which will invoke the management function
+
+``wait`` determines whether or not we should automatically sleep until the end of the window
+
+``callback_function`` is a function to run when the rate limiting management function fires. It will be invoked *after* the wait, if enabled.
+
+``callback_args`` is an optional parameter which is a dictionary passed as an argument to the callback function.
+
+For simple applications which run API requests in serial (and aren't interacting with many different stores, or use a separate worker for each store) the simple sleep function may work well enough for most purposes. For more complex applications that may be parallelizing API requests on a given store, it's adviseable to write your own callback function for handling the rate limiting, use a ``min_requests_remaining`` higher than your concurrency, and not use the default wait function.
+
 Further documentation
 ---------------------
 

bigcommerce/api.py

@@ -5,14 +5,16 @@
 
 
 class BigcommerceApi(object):
-    def __init__(self, host=None, basic_auth=None, client_id=None, store_hash=None, access_token=None):
+    def __init__(self, host=None, basic_auth=None,
+                 client_id=None, store_hash=None, access_token=None, rate_limiting_management=None):
         self.api_service = os.getenv('BC_API_ENDPOINT', 'api.bigcommerce.com')
         self.auth_service = os.getenv('BC_AUTH_SERVICE', 'login.bigcommerce.com')
 
         if host and basic_auth:
             self.connection = connection.Connection(host, basic_auth)
         elif client_id and store_hash:
-            self.connection = connection.OAuthConnection(client_id, store_hash, access_token, self.api_service)
+            self.connection = connection.OAuthConnection(client_id, store_hash, access_token, self.api_service,
+                                                         rate_limiting_management=rate_limiting_management)
         else:
             raise Exception("Must provide either (client_id and store_hash) or (host and basic_auth)")
 

bigcommerce/connection.py

@@ -16,6 +16,9 @@
 import logging
 import requests
 
+from math import ceil
+from time import sleep
+
 from bigcommerce.exception import *
 
 log = logging.getLogger("bigcommerce.connection")
@@ -183,12 +186,14 @@ class OAuthConnection(Connection):
     The verify_payload method is also provided for authenticating signed payloads passed to an application's load url.
     """
 
-    def __init__(self, client_id, store_hash, access_token=None, host='api.bigcommerce.com', api_path='/stores/{}/v2/{}'):
+    def __init__(self, client_id, store_hash, access_token=None, host='api.bigcommerce.com',
+                 api_path='/stores/{}/v2/{}', rate_limiting_management=None):
         self.client_id = client_id
         self.store_hash = store_hash
         self.host = host
         self.api_path = api_path
         self.timeout = 7.0  # can attach to session?
+        self.rate_limiting_management = rate_limiting_management
 
         self._session = requests.Session()
         self._session.headers = {"Accept": "application/json",
@@ -250,8 +255,20 @@ def _handle_response(self, url, res, suppress_empty=True):
         """
         result = Connection._handle_response(self, url, res, suppress_empty)
         if 'X-Rate-Limit-Time-Reset-Ms' in res.headers:
-            self.rate_limit = dict(ms_until_reset=res.headers['X-Rate-Limit-Time-Reset-Ms'],
-                                   window_size_ms=res.headers['X-Rate-Limit-Time-Window-Ms'],
-                                   requests_remaining=res.headers['X-Rate-Limit-Requests-Left'],
-                                   requests_quota=res.headers['X-Rate-Limit-Requests-Quota'])
+            self.rate_limit = dict(ms_until_reset=int(res.headers['X-Rate-Limit-Time-Reset-Ms']),
+                                   window_size_ms=int(res.headers['X-Rate-Limit-Time-Window-Ms']),
+                                   requests_remaining=int(res.headers['X-Rate-Limit-Requests-Left']),
+                                   requests_quota=int(res.headers['X-Rate-Limit-Requests-Quota']))
+            if self.rate_limiting_management:
+                if self.rate_limiting_management['min_requests_remaining'] >= self.rate_limit['requests_remaining']:
+                    if self.rate_limiting_management['wait']:
+                        sleep(ceil(float(self.rate_limit['ms_until_reset']) / 1000))
+                    if self.rate_limiting_management.get('callback_function'):
+                        callback = self.rate_limiting_management['callback_function']
+                        args_dict = self.rate_limiting_management.get('callback_args')
+                        if args_dict:
+                            callback(args_dict)
+                        else:
+                            callback()
+
         return result