python-backoff 3.0.0__py3-none-any.whl → 3.1.0__py3-none-any.whl

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"

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:

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.

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.0.0.dist-info → python_backoff-3.1.0.dist-info}/METADATA

@@ -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.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+backoff/__init__.py,sha256=pTD7ZdghoWQHaMhPwKe7S04yfLjCK7SZYkbUBa1ibGY,1080
+backoff/_async.py,sha256=UMAls92zTDOc_W8nmaTIWAEznQgE-bnSCjfoYerVG9Q,9235
+backoff/_common.py,sha256=d7D0crETK5Gstdb2qh1afPEEAJSwu1nqFt7qnw67HgY,8307
+backoff/_decorator.py,sha256=RO_z4IEDifNS7R-2MiLKtVAeI6b2KYGxlJ0SKjx21AU,18176
+backoff/_jitter.py,sha256=wzQHBDNuYg7owbc3fcZLOr5uhhRgqiuncU5rIYOB9lY,766
+backoff/_sync.py,sha256=bUoAkIBUB1TEyvSvHQSulesSjuyvRxD6Lq2SbLcw96o,6710
+backoff/_typing.py,sha256=ZMEhNamBlnXcOqzSCvGqZZ0uc0KVu9-mOKcxccCCPAs,1996
+backoff/_wait_gen.py,sha256=lEAyqcFdSH8cgjNotBMhb0bWaK4fNxzlCZbylvGN5Qc,5475
+backoff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+backoff/types.py,sha256=obBefroeCaGlPbOQSw1KIKvYl4SKFr8_YvwogvorVnw,97
+python_backoff-3.1.0.dist-info/METADATA,sha256=Yi6wAsS2d9G4UTtOMCxKUK5ifN4nt7dD46H-9i6UxhE,15016
+python_backoff-3.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+python_backoff-3.1.0.dist-info/licenses/LICENSE,sha256=KmtNX4hNTXob8E6n3xlEzxKzLjWnmobQoHWi0_QPuaw,1077
+python_backoff-3.1.0.dist-info/RECORD,,

{python_backoff-3.0.0.dist-info → python_backoff-3.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.32.0
+Generator: hatchling 1.33.0
 Root-Is-Purelib: true
 Tag: py3-none-any

python_backoff-3.0.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-backoff/__init__.py,sha256=_AGhwnTFSCdB_oeBA1-X5HPaivH4At8qucG8WQ8kZjI,1039
-backoff/_async.py,sha256=UMAls92zTDOc_W8nmaTIWAEznQgE-bnSCjfoYerVG9Q,9235
-backoff/_common.py,sha256=0ONXWZBiAMSAXw4KN_Cp7mLvhlUPOGV826NHYn6E760,8342
-backoff/_decorator.py,sha256=loMJ2ep7O0KOeXL8vvyMFU9VGK2fKlSsUaZoVCT5Tfs,18110
-backoff/_jitter.py,sha256=wzQHBDNuYg7owbc3fcZLOr5uhhRgqiuncU5rIYOB9lY,766
-backoff/_sync.py,sha256=bUoAkIBUB1TEyvSvHQSulesSjuyvRxD6Lq2SbLcw96o,6710
-backoff/_typing.py,sha256=ZMEhNamBlnXcOqzSCvGqZZ0uc0KVu9-mOKcxccCCPAs,1996
-backoff/_wait_gen.py,sha256=J7-UEqBjxdxvj7LKb5D1ILfPzMrUmCIVX0YsvS107UQ,3752
-backoff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-backoff/types.py,sha256=obBefroeCaGlPbOQSw1KIKvYl4SKFr8_YvwogvorVnw,97
-python_backoff-3.0.0.dist-info/METADATA,sha256=n9RmkgXbEsR9yRYThMaw0tk7KFaPG6eNIKO_TX5WRBI,14760
-python_backoff-3.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
-python_backoff-3.0.0.dist-info/licenses/LICENSE,sha256=KmtNX4hNTXob8E6n3xlEzxKzLjWnmobQoHWi0_QPuaw,1077
-python_backoff-3.0.0.dist-info/RECORD,,