[Rest] Support exponential backoff and retry

Uses the urllib3 builtin Retry mechanism.
We only support retrying on HTTP return status,
not on any of the other retries that that class
defines (e.g. connection problems, redirects).

The usual use case for this is to handle 429
responses from the Atlassian Cloud API which
has request limits that are easily hit by
scripts iterating over objects like Jira
issues or Bitbucket pull requests.

Based on earlier work by jp-harvey.

Co-authored-by: jp-harvey <jpharvey@cloudquarterback.com>
Signed-off-by: Frank Lichtenheld <frank@lichtenheld.com>

Author: flichtenheld

atlassian/rest_client.py

@@ -3,6 +3,7 @@
 from json import dumps
 
 import requests
+from requests.adapters import HTTPAdapter
 
 try:
     from oauthlib.oauth1.rfc5849 import SIGNATURE_RSA_SHA512 as SIGNATURE_RSA
@@ -11,6 +12,7 @@
 from requests import HTTPError
 from requests_oauthlib import OAuth1, OAuth2
 from six.moves.urllib.parse import urlencode
+from urllib3.util import Retry
 
 from atlassian.request_utils import get_default_logger
 
@@ -61,7 +63,44 @@ def __init__(
         proxies=None,
         token=None,
         cert=None,
+        backoff_and_retry=False,
+        retry_status_codes=[413, 429, 503],
+        max_backoff_seconds=1800,
+        max_backoff_retries=1000,
     ):
+        """
+        init function for the AtlassianRestAPI object.
+
+        :param url: The url to be used in the request.
+        :param username: Username. Defaults to None.
+        :param password: Password. Defaults to None.
+        :param timeout: Request timeout. Defaults to 75.
+        :param api_root: Root for the api requests. Defaults to "rest/api".
+        :param api_version: Version of the API to use. Defaults to "latest".
+        :param verify_ssl: Turn on / off SSL verification. Defaults to True.
+        :param session: Pass an existing Python requests session object. Defaults to None.
+        :param oauth: oauth. Defaults to None.
+        :param oauth2: oauth2. Defaults to None.
+        :param cookies: Cookies to send with the request. Defaults to None.
+        :param advanced_mode: Return results in advanced mode. Defaults to None.
+        :param kerberos: Kerberos. Defaults to None.
+        :param cloud: Specify if using Atlassian Cloud. Defaults to False.
+        :param proxies: Specify proxies to use. Defaults to None.
+        :param token: Atlassian / Jira auth token. Defaults to None.
+        :param cert: Client-side certificate to use. Defaults to None.
+        :param backoff_and_retry: Enable exponential backoff and retry.
+                This will retry the request if there is a predefined failure. Primarily
+                designed for Atlassian Cloud where API limits are commonly hit if doing
+                operations on many issues, and the limits require a cooling off period.
+                The wait period before the next request increases exponentially with each
+                failed retry. Defaults to False.
+        :param retry_status_codes: Errors to match, passed as a list of HTTP
+                response codes. Defaults to [413, 429, 503].
+        :param max_backoff_seconds: Max backoff seconds. When backing off, requests won't
+                wait any longer than this. Defaults to 1800.
+        :param max_backoff_retries: Maximum number of retries to try before
+                continuing. Defaults to 1000.
+        """
         self.url = url
         self.username = username
         self.password = password
@@ -78,6 +117,18 @@ def __init__(
             self._session = requests.Session()
         else:
             self._session = session
+        if backoff_and_retry:
+            # Note: we only retry on status and not on any of the
+            # other supported reasons
+            retries = Retry(
+                total=None,
+                status=max_backoff_retries,
+                allowed_methods=None,
+                status_forcelist=retry_status_codes,
+                backoff_factor=1,
+                backoff_jitter=1,
+                backoff_max=max_backoff_seconds)
+            self._session.mount(self.url, HTTPAdapter(max_retries=retries))
         if username and password:
             self._create_basic_session(username, password)
         elif token is not None: