python-backoff 2.3.0__tar.gz → 2.4.0__tar.gz

{python_backoff-2.3.0 → python_backoff-2.4.0}/.gitignore

@@ -1,6 +1,6 @@
 __pycache__/
 *.pyc
-.coverage
+.coverage*
 virtualenv
 MANIFEST
 build/
@@ -19,8 +19,6 @@ site/
 __MACOSX/
 .AppleDouble
 .LSOverride
-Icon[
-]
 
 # Thumbnails
 ._*

{python_backoff-2.3.0 → python_backoff-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-backoff
-Version: 2.3.0
+Version: 2.4.0
 Summary: Function decoration for backoff and retry
 Project-URL: Documentation, https://python-backoff.github.io/backoff
 Project-URL: Repository, https://github.com/python-backoff/backoff
@@ -11,12 +11,10 @@ License-File: LICENSE
 Keywords: backoff,decorators,retry
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -27,7 +25,7 @@ Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 
 backoff
@@ -58,7 +56,7 @@ for asynchronous code.
 Examples
 ========
 
-Since Kenneth Reitz's `requests <http://python-requests.org>`_ module
+Since Kenneth Reitz's `requests <https://requests.readthedocs.io>`_ module
 has become a defacto standard for synchronous HTTP clients in Python,
 networking examples below are written using it, but it is in no way required
 by the backoff module.
@@ -72,8 +70,10 @@ is raised. Here's an example using exponential backoff when any
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -82,9 +82,13 @@ the same backoff behavior is desired for more than one exception type:
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          (requests.exceptions.Timeout,
-                           requests.exceptions.ConnectionError))
+    @backoff.on_exception(
+        backoff.expo,
+        (
+            requests.exceptions.Timeout,
+            requests.exceptions.ConnectionError,
+        ),
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -98,9 +102,11 @@ of total time in seconds that can elapse before giving up.
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          max_time=60)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        max_time=60,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -110,10 +116,12 @@ to make to the target function before giving up.
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          max_tries=8,
-                          jitter=None)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        max_tries=8,
+        jitter=None,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -129,10 +137,13 @@ be retried:
     def fatal_code(e):
         return 400 <= e.response.status_code < 500
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          max_time=300,
-                          giveup=fatal_code)
+
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        max_time=300,
+        giveup=fatal_code,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -150,11 +161,14 @@ case, regardless of the logic in the `on_exception` handler.
     def fatal_code(e):
         return 400 <= e.response.status_code < 500
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          max_time=300,
-                          raise_on_giveup=False,
-                          giveup=fatal_code)
+
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        max_time=300,
+        raise_on_giveup=False,
+        giveup=fatal_code,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -174,7 +188,11 @@ return value of the target function is the empty list:
 
 .. code-block:: python
 
-    @backoff.on_predicate(backoff.fibo, lambda x: x == [], max_value=13)
+    @backoff.on_predicate(
+        backoff.fibo,
+        lambda x: x == [],
+        max_value=13,
+    )
     def poll_for_messages(queue):
         return queue.get()
 
@@ -196,7 +214,11 @@ gets a non-falsey result could be defined like like this:
 
 .. code-block:: python
 
-    @backoff.on_predicate(backoff.constant, jitter=None, interval=1)
+    @backoff.on_predicate(
+        backoff.constant,
+        jitter=None,
+        interval=1,
+    )
     def poll_for_message(queue):
         return queue.get()
 
@@ -249,12 +271,16 @@ backoff behavior for different cases:
 .. code-block:: python
 
     @backoff.on_predicate(backoff.fibo, max_value=13)
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.HTTPError,
-                          max_time=60)
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.Timeout,
-                          max_time=300)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.HTTPError,
+        max_time=60,
+    )
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.Timeout,
+        max_time=300,
+    )
     def poll_for_message(queue):
         return queue.get()
 
@@ -277,9 +303,13 @@ runtime to obtain the value:
         # and that it has a dictionary-like 'config' property
         return app.config["BACKOFF_MAX_TIME"]
 
-    @backoff.on_exception(backoff.expo,
-                          ValueError,
-                          max_time=lookup_max_time)
+
+    @backoff.on_exception(
+        backoff.expo,
+        ValueError,
+        max_time=lookup_max_time,
+    )
+    def my_function(): ...
 
 Event handlers
 --------------
@@ -307,13 +337,18 @@ implemented like so:
 .. code-block:: python
 
     def backoff_hdlr(details):
-        print ("Backing off {wait:0.1f} seconds after {tries} tries "
-               "calling function {target} with args {args} and kwargs "
-               "{kwargs}".format(**details))
+        print(
+            "Backing off {wait:0.1f} seconds after {tries} tries "
+            "calling function {target} with args {args} and kwargs "
+            "{kwargs}".format(**details)
+        )
+
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          on_backoff=backoff_hdlr)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        on_backoff=backoff_hdlr,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -325,9 +360,14 @@ handler functions as the value of the ``on_backoff`` keyword arg:
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          on_backoff=[backoff_hdlr1, backoff_hdlr2])
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        on_backoff=[
+            backoff_hdlr1,
+            backoff_hdlr2,
+        ],
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -358,9 +398,13 @@ asynchronous HTTP client/server library.
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo, aiohttp.ClientError, max_time=60)
+    @backoff.on_exception(
+        backoff.expo,
+        aiohttp.ClientError,
+        max_time=60,
+    )
     async def get_url(url):
-        async with aiohttp.ClientSession(raise_for_status=True) as session:
+        async with aiohttp.ClientSession(raise_for_status=True) as session:  # ruff:ignore[multiple-with-statements]
             async with session.get(url) as response:
                 return await response.text()
 
@@ -375,7 +419,7 @@ as:
 
 .. code-block:: python
 
-    logging.getLogger('backoff').addHandler(logging.StreamHandler())
+    logging.getLogger("backoff").addHandler(logging.StreamHandler())
 
 The default logging level is INFO, which corresponds to logging
 anytime a retry event occurs. If you would instead like to log
@@ -383,7 +427,7 @@ only when a giveup event occurs, set the logger level to ERROR.
 
 .. code-block:: python
 
-    logging.getLogger('backoff').setLevel(logging.ERROR)
+    logging.getLogger("backoff").setLevel(logging.ERROR)
 
 It is also possible to specify an alternate logger with the ``logger``
 keyword argument.  If a string value is specified the logger will be
@@ -391,25 +435,30 @@ looked up by name.
 
 .. code-block:: python
 
-   @backoff.on_exception(backoff.expo,
-                         requests.exceptions.RequestException,
-			 logger='my_logger')
-   # ...
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        logger="my_logger",
+    )
+    def my_function(): ...
 
 It is also supported to specify a Logger (or LoggerAdapter) object
 directly.
 
 .. code-block:: python
 
-    my_logger = logging.getLogger('my_logger')
+    my_logger = logging.getLogger("my_logger")
     my_handler = logging.StreamHandler()
     my_logger.addHandler(my_handler)
     my_logger.setLevel(logging.ERROR)
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-			  logger=my_logger)
-    # ...
+
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        logger=my_logger,
+    )
+    def my_function(): ...
 
 Default logging can be disabled all together by specifying
 ``logger=None``. In this case, if desired alternative logging behavior

{python_backoff-2.3.0 → python_backoff-2.4.0}/README.rst

@@ -26,7 +26,7 @@ for asynchronous code.
 Examples
 ========
 
-Since Kenneth Reitz's `requests <http://python-requests.org>`_ module
+Since Kenneth Reitz's `requests <https://requests.readthedocs.io>`_ module
 has become a defacto standard for synchronous HTTP clients in Python,
 networking examples below are written using it, but it is in no way required
 by the backoff module.
@@ -40,8 +40,10 @@ is raised. Here's an example using exponential backoff when any
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -50,9 +52,13 @@ the same backoff behavior is desired for more than one exception type:
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          (requests.exceptions.Timeout,
-                           requests.exceptions.ConnectionError))
+    @backoff.on_exception(
+        backoff.expo,
+        (
+            requests.exceptions.Timeout,
+            requests.exceptions.ConnectionError,
+        ),
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -66,9 +72,11 @@ of total time in seconds that can elapse before giving up.
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          max_time=60)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        max_time=60,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -78,10 +86,12 @@ to make to the target function before giving up.
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          max_tries=8,
-                          jitter=None)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        max_tries=8,
+        jitter=None,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -97,10 +107,13 @@ be retried:
     def fatal_code(e):
         return 400 <= e.response.status_code < 500
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          max_time=300,
-                          giveup=fatal_code)
+
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        max_time=300,
+        giveup=fatal_code,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -118,11 +131,14 @@ case, regardless of the logic in the `on_exception` handler.
     def fatal_code(e):
         return 400 <= e.response.status_code < 500
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          max_time=300,
-                          raise_on_giveup=False,
-                          giveup=fatal_code)
+
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        max_time=300,
+        raise_on_giveup=False,
+        giveup=fatal_code,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -142,7 +158,11 @@ return value of the target function is the empty list:
 
 .. code-block:: python
 
-    @backoff.on_predicate(backoff.fibo, lambda x: x == [], max_value=13)
+    @backoff.on_predicate(
+        backoff.fibo,
+        lambda x: x == [],
+        max_value=13,
+    )
     def poll_for_messages(queue):
         return queue.get()
 
@@ -164,7 +184,11 @@ gets a non-falsey result could be defined like like this:
 
 .. code-block:: python
 
-    @backoff.on_predicate(backoff.constant, jitter=None, interval=1)
+    @backoff.on_predicate(
+        backoff.constant,
+        jitter=None,
+        interval=1,
+    )
     def poll_for_message(queue):
         return queue.get()
 
@@ -217,12 +241,16 @@ backoff behavior for different cases:
 .. code-block:: python
 
     @backoff.on_predicate(backoff.fibo, max_value=13)
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.HTTPError,
-                          max_time=60)
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.Timeout,
-                          max_time=300)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.HTTPError,
+        max_time=60,
+    )
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.Timeout,
+        max_time=300,
+    )
     def poll_for_message(queue):
         return queue.get()
 
@@ -245,9 +273,13 @@ runtime to obtain the value:
         # and that it has a dictionary-like 'config' property
         return app.config["BACKOFF_MAX_TIME"]
 
-    @backoff.on_exception(backoff.expo,
-                          ValueError,
-                          max_time=lookup_max_time)
+
+    @backoff.on_exception(
+        backoff.expo,
+        ValueError,
+        max_time=lookup_max_time,
+    )
+    def my_function(): ...
 
 Event handlers
 --------------
@@ -275,13 +307,18 @@ implemented like so:
 .. code-block:: python
 
     def backoff_hdlr(details):
-        print ("Backing off {wait:0.1f} seconds after {tries} tries "
-               "calling function {target} with args {args} and kwargs "
-               "{kwargs}".format(**details))
+        print(
+            "Backing off {wait:0.1f} seconds after {tries} tries "
+            "calling function {target} with args {args} and kwargs "
+            "{kwargs}".format(**details)
+        )
+
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          on_backoff=backoff_hdlr)
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        on_backoff=backoff_hdlr,
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -293,9 +330,14 @@ handler functions as the value of the ``on_backoff`` keyword arg:
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-                          on_backoff=[backoff_hdlr1, backoff_hdlr2])
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        on_backoff=[
+            backoff_hdlr1,
+            backoff_hdlr2,
+        ],
+    )
     def get_url(url):
         return requests.get(url)
 
@@ -326,9 +368,13 @@ asynchronous HTTP client/server library.
 
 .. code-block:: python
 
-    @backoff.on_exception(backoff.expo, aiohttp.ClientError, max_time=60)
+    @backoff.on_exception(
+        backoff.expo,
+        aiohttp.ClientError,
+        max_time=60,
+    )
     async def get_url(url):
-        async with aiohttp.ClientSession(raise_for_status=True) as session:
+        async with aiohttp.ClientSession(raise_for_status=True) as session:  # ruff:ignore[multiple-with-statements]
             async with session.get(url) as response:
                 return await response.text()
 
@@ -343,7 +389,7 @@ as:
 
 .. code-block:: python
 
-    logging.getLogger('backoff').addHandler(logging.StreamHandler())
+    logging.getLogger("backoff").addHandler(logging.StreamHandler())
 
 The default logging level is INFO, which corresponds to logging
 anytime a retry event occurs. If you would instead like to log
@@ -351,7 +397,7 @@ only when a giveup event occurs, set the logger level to ERROR.
 
 .. code-block:: python
 
-    logging.getLogger('backoff').setLevel(logging.ERROR)
+    logging.getLogger("backoff").setLevel(logging.ERROR)
 
 It is also possible to specify an alternate logger with the ``logger``
 keyword argument.  If a string value is specified the logger will be
@@ -359,25 +405,30 @@ looked up by name.
 
 .. code-block:: python
 
-   @backoff.on_exception(backoff.expo,
-                         requests.exceptions.RequestException,
-			 logger='my_logger')
-   # ...
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        logger="my_logger",
+    )
+    def my_function(): ...
 
 It is also supported to specify a Logger (or LoggerAdapter) object
 directly.
 
 .. code-block:: python
 
-    my_logger = logging.getLogger('my_logger')
+    my_logger = logging.getLogger("my_logger")
     my_handler = logging.StreamHandler()
     my_logger.addHandler(my_handler)
     my_logger.setLevel(logging.ERROR)
 
-    @backoff.on_exception(backoff.expo,
-                          requests.exceptions.RequestException,
-			  logger=my_logger)
-    # ...
+
+    @backoff.on_exception(
+        backoff.expo,
+        requests.exceptions.RequestException,
+        logger=my_logger,
+    )
+    def my_function(): ...
 
 Default logging can be disabled all together by specifying
 ``logger=None``. In this case, if desired alternative logging behavior

{python_backoff-2.3.0 → python_backoff-2.4.0}/backoff/__init__.py

@@ -1,4 +1,3 @@
-# coding:utf-8
 """
 Function decoration for backoff and retry
 
@@ -12,20 +11,23 @@ polling resources for externally generated content.
 For examples and full documentation see the README at
 https://github.com/python-backoff/backoff
 """
-from backoff._decorator import on_exception, on_predicate
+
+from backoff._decorator import aretry_context, on_exception, on_predicate, retry_context
 from backoff._jitter import full_jitter, random_jitter
-from backoff._wait_gen import constant, expo, fibo, runtime, decay
+from backoff._wait_gen import constant, decay, expo, fibo, runtime
 
 __all__ = [
-    'on_predicate',
-    'on_exception',
-    'constant',
-    'expo',
-    'decay',
-    'fibo',
-    'runtime',
-    'full_jitter',
-    'random_jitter',
+    "aretry_context",
+    "constant",
+    "decay",
+    "expo",
+    "fibo",
+    "full_jitter",
+    "on_exception",
+    "on_predicate",
+    "random_jitter",
+    "retry_context",
+    "runtime",
 ]
 
-__version__ = "2.2.1"
+__version__ = "2.4.0"