python-backoff 3.0.0__tar.gz → 3.1.0__tar.gz

{python_backoff-3.0.0 → python_backoff-3.1.0}/PKG-INFO

@@ -1,7 +1,8 @@
 Metadata-Version: 2.5
 Name: python-backoff
-Version: 3.0.0
-Summary: Function decoration for backoff and retry
+Version: 3.1.0
+Import-Name: backoff
+Summary: Function decoration and context managers for backoff and retry
 Project-URL: Documentation, https://python-backoff.github.io/backoff
 Project-URL: Repository, https://github.com/python-backoff/backoff
 Author-email: Bob Green <rgreen@aquent.com>
@@ -21,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3.15
+Classifier: Programming Language :: Python :: 3.16
 Classifier: Topic :: Internet :: WWW/HTTP
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
@@ -39,9 +41,11 @@ backoff
 .. image:: https://img.shields.io/github/license/python-backoff/backoff
     :target: https://github.com/python-backoff/backoff/blob/main/LICENSE
 
+*Note: this is an actively maintained fork of https://github.com/litl/backoff.*
+
 **Function decoration for backoff and retry**
 
-This module provides function decorators which can be used to wrap a
+This library provides function decorators which can be used to wrap a
 function such that it will be retried until some condition is met. It
 is meant to be of use when accessing unreliable resources with the
 potential for intermittent failures i.e. network resources and external
@@ -52,6 +56,8 @@ Decorators support both regular functions for synchronous code and
 `asyncio <https://docs.python.org/3/library/asyncio.html>`__'s coroutines
 for asynchronous code.
 
+Context managers are also available to enable retries of arbitrary code blocks.
+
 Examples
 ========
 
@@ -182,7 +188,7 @@ The ``on_predicate`` decorator is used to retry when a particular
 condition is true of the return value of the target function.  This may
 be useful when polling a resource for externally generated content.
 
-Here's an example which uses a fibonacci sequence backoff when the
+Here's an example which uses a Fibonacci sequence backoff when the
 return value of the target function is the empty list:
 
 .. code-block:: python

{python_backoff-3.0.0 → python_backoff-3.1.0}/README.rst

@@ -10,9 +10,11 @@ backoff
 .. image:: https://img.shields.io/github/license/python-backoff/backoff
     :target: https://github.com/python-backoff/backoff/blob/main/LICENSE
 
+*Note: this is an actively maintained fork of https://github.com/litl/backoff.*
+
 **Function decoration for backoff and retry**
 
-This module provides function decorators which can be used to wrap a
+This library provides function decorators which can be used to wrap a
 function such that it will be retried until some condition is met. It
 is meant to be of use when accessing unreliable resources with the
 potential for intermittent failures i.e. network resources and external
@@ -23,6 +25,8 @@ Decorators support both regular functions for synchronous code and
 `asyncio <https://docs.python.org/3/library/asyncio.html>`__'s coroutines
 for asynchronous code.
 
+Context managers are also available to enable retries of arbitrary code blocks.
+
 Examples
 ========
 
@@ -153,7 +157,7 @@ The ``on_predicate`` decorator is used to retry when a particular
 condition is true of the return value of the target function.  This may
 be useful when polling a resource for externally generated content.
 
-Here's an example which uses a fibonacci sequence backoff when the
+Here's an example which uses a Fibonacci sequence backoff when the
 return value of the target function is the empty list:
 
 .. code-block:: python

{python_backoff-3.0.0 → python_backoff-3.1.0}/backoff/__init__.py

@@ -1,5 +1,5 @@
 """
-Function decoration for backoff and retry
+Function decoration for backoff and retry.
 
 This module provides function decorators which can be used to wrap a
 function such that it will be retried until some condition is met. It
@@ -8,18 +8,19 @@ potential for intermittent failures i.e. network resources and external
 APIs. Somewhat more generally, it may also be of use for dynamically
 polling resources for externally generated content.
 
-For examples and full documentation see the README at
-https://github.com/python-backoff/backoff
+For examples and full documentation, see
+[the official documentation](https://backoff.readthedocs.io/en/latest/).
 """
 
 from backoff._common import Attempt
 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, decay, expo, fibo, runtime
+from backoff._wait_gen import capped, constant, decay, expo, fibo, runtime
 
 __all__ = [
     "Attempt",
     "aretry_context",
+    "capped",
     "constant",
     "decay",
     "expo",
@@ -32,4 +33,4 @@ __all__ = [
     "runtime",
 ]
 
-__version__ = "3.0.0"
+__version__ = "3.1.0"

{python_backoff-3.0.0 → python_backoff-3.1.0}/backoff/_common.py

@@ -43,7 +43,7 @@ _HandlerT = TypeVar("_HandlerT")
 def _maybe_call(f: _MaybeCallable[T] | None, *args: Any, **kwargs: Any) -> T | None:
     if callable(f):
         try:
-            return f(*args, **kwargs)  # ty:ignore[call-top-callable, invalid-return-type]
+            return f(*args, **kwargs)  # ty:ignore[invalid-return-type]
         except TypeError:
             return f  # type: ignore[return-value] # ty:ignore[invalid-return-type]
     else:
@@ -212,10 +212,9 @@ def _config_handlers(
 # Default backoff handler
 def _log_backoff(details: Details, logger: _AnyLogger, log_level: int) -> None:
     msg = "Backing off %s(...) for %.1fs (%s)"
-    log_args = [details["target"].__name__, details["wait"]]  # ty:ignore[unresolved-attribute]
+    log_args = [details["target"].__name__, details["wait"]]  # ty:ignore[missing-attribute]
 
-    exc = details.get("exception")
-    if exc is not None:
+    if (exc := details.get("exception")) is not None:
         exc_fmt = traceback.format_exception_only(type(exc), exc)[-1]
         log_args.append(exc_fmt.rstrip("\n"))
     else:
@@ -226,10 +225,9 @@ def _log_backoff(details: Details, logger: _AnyLogger, log_level: int) -> None:
 # Default giveup handler
 def _log_giveup(details: Details, logger: _AnyLogger, log_level: int) -> None:
     msg = "Giving up %s(...) after %d tries (%s)"
-    log_args = [details["target"].__name__, details["tries"]]  # ty:ignore[unresolved-attribute]
+    log_args = [details["target"].__name__, details["tries"]]  # ty:ignore[missing-attribute]
 
-    exc = details.get("exception")
-    if exc is not None:
+    if (exc := details.get("exception")) is not None:
         exc_fmt = traceback.format_exception_only(type(exc), exc)[-1]
         log_args.append(exc_fmt.rstrip("\n"))
     else:

{python_backoff-3.0.0 → python_backoff-3.1.0}/backoff/_decorator.py

@@ -307,9 +307,14 @@ def retry_context(
     Unlike `on_exception`, this doesn't wrap a whole function; it lets a
     caller retry an arbitrary block of code:
 
-        for attempt in backoff.retry_context(ValueError, backoff.expo):
-            with attempt:
-                do_something()
+    ```python
+    for attempt in backoff.retry_context(
+        ValueError,
+        backoff.expo,
+    ):
+        with attempt:
+            do_something()
+    ```
 
     Each `attempt` is a context manager: exceptions matching `exception`
     are caught, and the loop either sleeps and retries or lets the
@@ -403,9 +408,14 @@ def aretry_context(
 ) -> AsyncGenerator[Attempt, None]:
     """Async counterpart to `retry_context`, for use with `async for`.
 
-        async for attempt in backoff.aretry_context(ValueError, backoff.expo):
-            with attempt:
-                await do_something()
+    ```python
+    async for attempt in backoff.aretry_context(
+        ValueError,
+        backoff.expo,
+    ):
+        with attempt:
+            await do_something()
+    ```
 
     `giveup` and the handlers may be sync or async callables. See
     `retry_context` for the full argument reference.

{python_backoff-3.0.0 → python_backoff-3.1.0}/backoff/_wait_gen.py

@@ -2,11 +2,13 @@ from __future__ import annotations
 
 import itertools
 import math
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, ParamSpec
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Generator, Iterable
 
+    P = ParamSpec("P")
+
 
 def expo(
     base: float = 2,
@@ -38,7 +40,7 @@ def decay(
     decay_factor: float = 1,
     min_value: float | None = None,
 ) -> Generator[float, Any, None]:
-    """Generator for exponential decay[1]:
+    """Generator for [exponential decay](https://en.wikipedia.org/wiki/Exponential_decay).
 
     Args:
         initial_value: initial quantity
@@ -46,8 +48,6 @@ def decay(
         min_value: The minimum value to yield. Once the value in the
              true exponential sequence is lower than this, the value
              of min_value will forever after be yielded.
-
-    [1] https://en.wikipedia.org/wiki/Exponential_decay
     """
     # Advance past initial .send() call
     yield 0
@@ -61,12 +61,12 @@ def decay(
 
 
 def fibo(max_value: int | None = None) -> Generator[int, Any, None]:
-    """Generator for fibonaccial decay.
+    """Generator for Fibonacci decay.
 
     Args:
         max_value: The maximum value to yield. Once the value in the
-             true fibonacci sequence exceeds this, the value
-             of max_value will forever after be yielded.
+             true Fibonacci sequence exceeds this, the value
+             of `max_value` will forever after be yielded.
     """
     # Advance past initial .send() call
     yield 0
@@ -99,6 +99,57 @@ def constant(interval: float | Iterable[float] = 1) -> Generator[float, Any, Non
         yield val
 
 
+def capped(
+    wait_gen: Callable[P, Generator[float, Any, None]],
+    *,
+    min_value: float | None = None,
+    max_value: float | None = None,
+) -> Callable[P, Generator[float, Any, None]]:
+    """Wraps a wait generator, clamping each value it yields.
+
+    Useful for wait generators without their own bound, such as
+    [`constant`][backoff.constant] or [`runtime`][backoff.runtime] (e.g.
+    capping a server-provided `Retry-After` value so a misbehaving server
+    can't stall retries indefinitely):
+
+    ```python
+    backoff.on_predicate(
+        backoff.capped(backoff.runtime, max_value=60),
+        predicate=lambda r: r.status_code == 429,
+        value=lambda r: int(r.headers.get("Retry-After", 1)),
+    )
+    ```
+
+    Args:
+        wait_gen: The wait generator to wrap.
+        min_value: The minimum value to yield. Values below this are
+            raised to min_value.
+        max_value: The maximum value to yield. Values above this are
+            lowered to max_value.
+    """
+    if min_value is not None and max_value is not None and min_value > max_value:
+        msg = f"`min_value` {min_value} cannot be greater than `max_value` {max_value}"
+        raise ValueError(msg)
+
+    def generator(*args: P.args, **kwargs: P.kwargs) -> Generator[float, Any, None]:
+        gen = wait_gen(*args, **kwargs)
+        gen.send(None)
+
+        send_value = yield 0
+        while True:
+            try:
+                value = gen.send(send_value)
+            except StopIteration:
+                return
+            if max_value is not None:
+                value = min(value, max_value)
+            if min_value is not None:
+                value = max(value, min_value)
+            send_value = yield value
+
+    return generator
+
+
 def runtime(*, value: Callable[[Any], float]) -> Generator[float, Any, None]:
     """Generator that is based on parsing the return value or thrown
         exception of the decorated method
@@ -106,23 +157,25 @@ def runtime(*, value: Callable[[Any], float]) -> Generator[float, Any, None]:
     Useful for honoring a server-specified retry delay, e.g. an HTTP
     `Retry-After` header, rather than a fixed wait sequence:
 
-        # with on_predicate, `value` receives the return value
-        @backoff.on_predicate(
-            backoff.runtime,
-            predicate=lambda r: r.status_code == 429,
-            value=lambda r: int(r.headers.get("Retry-After", 1)),
-        )
-        def get_page():
-            return requests.get(url)
-
-        # with on_exception, `value` receives the raised exception
-        @backoff.on_exception(
-            backoff.runtime,
-            RetryableError,
-            value=lambda e: e.wait_seconds,
-        )
-        def get_page():
-            ...
+    ```python
+    # with on_predicate, `value` receives the return value
+    @backoff.on_predicate(
+        backoff.runtime,
+        predicate=lambda r: r.status_code == 429,
+        value=lambda r: int(r.headers.get("Retry-After", 1)),
+    )
+    def get_page():
+        return requests.get(url)
+
+
+    # with on_exception, `value` receives the raised exception
+    @backoff.on_exception(
+        backoff.runtime,
+        RetryableError,
+        value=lambda e: e.wait_seconds,
+    )
+    def get_page(): ...
+    ```
 
     Args:
         value: a callable which takes as input the decorated

python_backoff-3.1.0/docs/advanced/combining-decorators.md

@@ -0,0 +1,123 @@
+# Combining Decorators
+
+Stack multiple backoff decorators for complex retry logic.
+
+## Basics
+
+Decorators are applied from bottom to top (inside out):
+
+```python
+@backoff.on_predicate(backoff.fibo, lambda x: x is None)  # Applied last
+@backoff.on_exception(backoff.expo, HTTPError)  # Applied second
+@backoff.on_exception(backoff.expo, Timeout)  # Applied first
+def complex_operation():
+    pass
+```
+
+## Common Patterns
+
+### Different Exceptions, Different Strategies
+
+```python
+@backoff.on_exception(
+    backoff.expo,
+    requests.exceptions.Timeout,
+    max_time=300,  # Generous timeout for network issues
+)
+@backoff.on_exception(
+    backoff.expo,
+    requests.exceptions.HTTPError,
+    max_time=60,  # Shorter timeout for HTTP errors
+    giveup=lambda e: 400 <= e.response.status_code < 500,
+)
+def api_call(url):
+    response = requests.get(url)
+    response.raise_for_status()
+    return response.json()
+```
+
+### Exception + Predicate
+
+```python
+@backoff.on_predicate(
+    backoff.constant,
+    lambda result: result.get("status") == "pending",
+    interval=5,
+    max_time=600,
+)
+@backoff.on_exception(
+    backoff.expo,
+    requests.exceptions.RequestException,
+    max_time=60,
+)
+def poll_until_ready(job_id):
+    response = requests.get(f"/api/jobs/{job_id}")
+    response.raise_for_status()
+    return response.json()
+```
+
+## Execution Order
+
+Inner decorators execute first:
+
+```python
+calls = []
+
+
+def track_call(func_name):
+    def handler(details):
+        calls.append(func_name)
+
+    return handler
+
+
+@backoff.on_exception(
+    backoff.constant,
+    ValueError,
+    on_backoff=track_call("outer"),
+    max_tries=2,
+    interval=0.01,
+)
+@backoff.on_exception(
+    backoff.constant,
+    TypeError,
+    on_backoff=track_call("inner"),
+    max_tries=2,
+    interval=0.01,
+)
+def failing_function(error_type):
+    raise error_type("Test")
+```
+
+- If `TypeError` raised: inner decorator retries
+- If `ValueError` raised: outer decorator retries
+- Both errors: inner handles TypeError, then outer handles ValueError
+
+## Best Practices
+
+### Specific Before General
+
+```python
+@backoff.on_exception(backoff.expo, Exception)  # Catch-all
+@backoff.on_exception(backoff.fibo, ConnectionError)  # Specific
+def network_operation():
+    pass
+```
+
+### Short Timeouts Inside, Long Outside
+
+```python
+@backoff.on_exception(
+    backoff.expo,
+    Exception,
+    max_time=600,  # Overall 10-minute limit
+)
+@backoff.on_exception(
+    backoff.constant,
+    Timeout,
+    interval=1,
+    max_tries=3,  # Quick retries for timeouts
+)
+def layered_retry():
+    pass
+```

python_backoff-3.1.0/docs/advanced/custom-strategies.md

@@ -0,0 +1,144 @@
+# Custom Wait Strategies
+
+Create custom wait generators for specialized retry patterns.
+
+## Wait Generator Interface
+
+A wait generator is a function that yields wait times in seconds:
+
+```python
+def my_wait_gen():
+    """Yields: 1, 2, 3, 4, 5, 5, 5, ..."""
+    # Note: Using `yield from` can be unsafe in backoff wait generators.
+    for i in range(1, 6):
+        yield i
+    while True:
+        yield 5
+
+
+@backoff.on_exception(my_wait_gen, Exception)
+def my_function():
+    pass
+```
+
+## Parameters
+
+Accept parameters to customize behavior:
+
+```python
+def linear_backoff(start=1, increment=1, max_value=None):
+    """Linear backoff: start, start+increment, start+2*increment, ..."""
+    value = start
+    while True:
+        if max_value and value > max_value:
+            yield max_value
+        else:
+            yield value
+            value += increment
+
+
+@backoff.on_exception(
+    linear_backoff,
+    Exception,
+    start=2,
+    increment=3,
+    max_value=30,
+)
+def my_function():
+    pass
+```
+
+## Examples
+
+### Polynomial Backoff
+
+```python
+def polynomial_backoff(base=2, exponent=2, max_value=None):
+    """Polynomial: base^(tries^exponent)"""
+    n = 1
+    while True:
+        value = base ** (n**exponent)
+        if max_value and value > max_value:
+            yield max_value
+        else:
+            yield value
+        n += 1
+
+
+@backoff.on_exception(
+    polynomial_backoff,
+    Exception,
+    base=2,
+    exponent=1.5,
+)
+def my_function():
+    pass
+```
+
+### Stepped Backoff
+
+```python
+def stepped_backoff(steps):
+    """Different wait times for different ranges
+    steps = [(3, 1), (5, 5), (None, 10)]  # 3 tries at 1s, next 5 at 5s, rest at 10s
+    """
+    for max_tries, wait_time in steps:
+        if max_tries is None:
+            while True:
+                yield wait_time
+        else:
+            for _ in range(max_tries):
+                yield wait_time
+
+
+@backoff.on_exception(
+    stepped_backoff,
+    Exception,
+    steps=[(3, 1), (3, 5), (None, 30)],
+)
+def my_function():
+    pass
+```
+
+### Random Backoff
+
+```python
+import random
+
+
+def random_backoff(min_wait=1, max_wait=60):
+    """Random wait between min and max"""
+    while True:
+        yield random.uniform(min_wait, max_wait)
+
+
+@backoff.on_exception(
+    random_backoff,
+    Exception,
+    min_wait=1,
+    max_wait=10,
+)
+def my_function():
+    pass
+```
+
+### Time-of-Day Aware
+
+```python
+from datetime import datetime, timezone
+
+
+def business_hours_backoff():
+    """Shorter waits during business hours"""
+    while True:
+        hour = datetime.now(tz=timezone.utc).hour
+        if 9 <= hour < 17:
+            yield 5  # 5 seconds during business hours
+        else:
+            yield 60  # 1 minute otherwise
+
+
+@backoff.on_exception(business_hours_backoff, Exception)
+def my_function():
+    pass
+```