python-backoff 2.4.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,16 +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",
@@ -30,4 +33,4 @@ __all__ = [
     "runtime",
 ]
 
-__version__ = "2.4.0"
+__version__ = "3.1.0"

backoff/_async.py

@@ -3,13 +3,15 @@ from __future__ import annotations
 import asyncio
 import functools
 import inspect
-from typing import TYPE_CHECKING, Any, Callable, TypeVar
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeVar
 
-from backoff._common import _Attempt, _RetryState
+from backoff._common import Attempt, _RetryState
 
 if TYPE_CHECKING:
     import sys
     from collections.abc import AsyncGenerator, Coroutine, Iterable
+    from typing import ParamSpec
 
     from backoff._typing import (
         ContextDetails,
@@ -25,11 +27,6 @@ if TYPE_CHECKING:
         _WaitGenerator,
     )
 
-    if sys.version_info >= (3, 10):
-        from typing import ParamSpec
-    else:
-        from typing_extensions import ParamSpec
-
     if sys.version_info >= (3, 11):
         from typing import Unpack
     else:
@@ -76,26 +73,27 @@ async def _call_handlers(
         "kwargs": kwargs,
         "tries": tries,
         "elapsed": elapsed,
+        **extra,
     }
-    # pyrefly: ignore [no-matching-overload]
-    details.update(extra)
     for handler in handlers:
         await handler(details)
 
 
 def retry_predicate(
-    target: Callable[P, T],
+    target: Callable[P, Coroutine[object, object, T]],
     wait_gen: _WaitGenerator,
     predicate: _Predicate[T],
     *,
     max_tries: _MaybeCallable[int] | None,
     max_time: _MaybeCallable[float] | None,
     jitter: _Jitterer | None,
+    on_try: Iterable[_Handler],
     on_success: Iterable[_Handler],
     on_backoff: Iterable[_Handler],
     on_giveup: Iterable[_Handler],
     wait_gen_kwargs: dict[str, Any],
-) -> Callable[P, T]:
+) -> Callable[P, Coroutine[object, object, T]]:
+    on_try = _ensure_coroutines(on_try)
     on_success = _ensure_coroutines(on_success)
     on_backoff = _ensure_coroutines(on_backoff)
     on_giveup = _ensure_coroutines(on_giveup)
@@ -116,14 +114,16 @@ def retry_predicate(
         )
         while True:
             state.start_attempt()
-            ret = await target(*args, **kwargs)
             details: _BaseDetails = {
                 "target": target,
                 "args": args,
                 "kwargs": kwargs,
                 "tries": state.tries,
-                "elapsed": state.record_elapsed(),
+                "elapsed": state.elapsed,
             }
+            await _call_handlers(on_try, **details)
+            ret = await target(*args, **kwargs)
+            details["elapsed"] = state.record_elapsed()
 
             if predicate(ret):
                 if state.exhausted():
@@ -154,7 +154,7 @@ def retry_predicate(
 
         return ret
 
-    return retry  # type: ignore[return-value] # ty:ignore[invalid-return-type]
+    return retry
 
 
 def _adapt_context_handlers(
@@ -177,7 +177,7 @@ def _adapt_context_handlers(
 
 
 def retry_exception(
-    target: Callable[P, T],
+    target: Callable[P, Coroutine[object, object, T]],
     wait_gen: _WaitGenerator,
     exception: _MaybeTuple[type[Exception]],
     *,
@@ -185,12 +185,14 @@ def retry_exception(
     max_time: _MaybeCallable[float] | None,
     jitter: _Jitterer | None,
     giveup: _Predicate[Exception],
+    on_try: Iterable[_Handler],
     on_success: Iterable[_Handler],
     on_backoff: Iterable[_Handler],
     on_giveup: Iterable[_Handler],
     raise_on_giveup: bool,
     wait_gen_kwargs: dict[str, Any],
-) -> Callable[P, T]:
+) -> Callable[P, Coroutine[object, object, T]]:
+    on_try = _ensure_coroutines(on_try)
     on_success = _ensure_coroutines(on_success)
     on_backoff = _ensure_coroutines(on_backoff)
     on_giveup = _ensure_coroutines(on_giveup)
@@ -214,6 +216,7 @@ def retry_exception(
             max_time=max_time,
             jitter=jitter,
             giveup=giveup,
+            on_try=_adapt_context_handlers(on_try, target, args, kwargs),
             on_success=_adapt_context_handlers(on_success, target, args, kwargs),
             on_backoff=_adapt_context_handlers(on_backoff, target, args, kwargs),
             on_giveup=_adapt_context_handlers(on_giveup, target, args, kwargs),
@@ -221,11 +224,11 @@ def retry_exception(
             wait_gen_kwargs=wait_gen_kwargs,
         ):
             with attempt:
-                ret = await target(*args, **kwargs)  # type: ignore[misc] # ty:ignore[invalid-await]
+                ret = await target(*args, **kwargs)
 
         return ret
 
-    return retry  # type: ignore[return-value] # ty:ignore[invalid-return-type]
+    return retry
 
 
 async def _dispatch_handlers(
@@ -243,12 +246,13 @@ async def aretry_context(
     max_time: _MaybeCallable[float] | None,
     jitter: _Jitterer | None,
     giveup: _Predicate[BaseException],
+    on_try: Iterable[_ContextHandler],
     on_success: Iterable[_ContextHandler],
     on_backoff: Iterable[_ContextHandler],
     on_giveup: Iterable[_ContextHandler],
     raise_on_giveup: bool,
     wait_gen_kwargs: dict[str, Any],
-) -> AsyncGenerator[_Attempt, None]:
+) -> AsyncGenerator[Attempt, None]:
     giveup = _ensure_coroutine(giveup)
 
     state = _RetryState(
@@ -259,7 +263,12 @@ async def aretry_context(
     )
     while True:
         state.start_attempt()
-        attempt = _Attempt(exception)
+        attempt = Attempt(exception)
+        await _dispatch_handlers(
+            handlers=on_try,
+            tries=state.tries,
+            elapsed=state.elapsed,
+        )
         yield attempt
         elapsed = state.record_elapsed()
 

backoff/_common.py

@@ -4,16 +4,18 @@ import functools
 import logging
 import time
 import traceback
-import warnings
-from typing import TYPE_CHECKING, Any, Callable, TypeVar
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, TypeAlias, TypeVar
 
 if TYPE_CHECKING:
     import sys
-    from collections.abc import Generator, Iterable
+    from collections.abc import Callable, Generator, Iterable
 
     from backoff._typing import (
         ContextDetails,
         Details,
+        _AnyLogger,
+        _AnyLoggerOrName,
         _ContextHandler,
         _Jitterer,
         _MaybeCallable,
@@ -25,6 +27,8 @@ if TYPE_CHECKING:
     else:
         from typing_extensions import Self
 
+    ExceptionTypes: TypeAlias = type[Exception] | tuple[type[Exception], ...]
+
 
 # Use module-specific logger with a default null handler.
 _logger = logging.getLogger("backoff")
@@ -39,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:
@@ -64,18 +68,7 @@ def _next_wait(
     max_time: float | None,
 ) -> float:
     value = wait.send(send_value)
-    try:
-        seconds = jitter(value) if jitter is not None else value
-    except TypeError:
-        warnings.warn(
-            "Nullary jitter function signature is deprecated. Use "
-            "unary signature accepting a wait value in seconds and "
-            "returning a jittered version of it.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-        seconds = value + jitter()  # type: ignore[call-arg, misc] # ty:ignore[missing-argument, call-non-callable]
+    seconds = jitter(value) if jitter is not None else value
 
     # don't sleep longer than remaining allotted max_time
     if max_time is not None:
@@ -132,7 +125,8 @@ class _RetryState:
         return _next_wait(self.wait, send_value, jitter, self.elapsed, self.max_time)
 
 
-class _Attempt:
+@dataclass(slots=True)
+class Attempt:
     """A single attempt yielded by `retry_context`/`aretry_context`.
 
     Used as `with attempt: ...`. Exceptions matching `exception_types` are
@@ -141,16 +135,10 @@ class _Attempt:
     exception at all, is left for the `with` block's normal exit behavior.
     """
 
-    __slots__ = (
-        "exception",
-        "exception_types",
-    )
+    exception_types: ExceptionTypes
+    exception: BaseException | None = field(init=False)
 
-    def __init__(
-        self,
-        exception_types: type[Exception] | tuple[type[Exception], ...],
-    ) -> None:
-        self.exception_types = exception_types
+    def __post_init__(self) -> None:
         self.exception: BaseException | None = None
 
     def __enter__(self) -> Self:
@@ -163,7 +151,6 @@ class _Attempt:
         tb: object,
     ) -> bool:
         if exc_type is None:
-            # self.outcome = _Success()
             return False
 
         if not issubclass(exc_type, self.exception_types):
@@ -178,9 +165,7 @@ def _dispatch_handlers(handlers: Iterable[_ContextHandler], **details: Any) -> N
         hdlr(details)  # type: ignore[arg-type] # ty:ignore[invalid-argument-type]
 
 
-def _prepare_logger(
-    logger: str | logging.Logger | logging.LoggerAdapter | None,
-) -> logging.Logger | logging.LoggerAdapter | None:
+def _prepare_logger(logger: _AnyLoggerOrName | None) -> _AnyLogger | None:
     if isinstance(logger, str):
         logger = logging.getLogger(logger)
     return logger
@@ -192,7 +177,7 @@ def _config_handlers(
     user_handlers: _HandlerT | Iterable[_HandlerT] | None,
     *,
     default_handler: Callable[..., None] | None = None,
-    logger: logging.Logger | logging.LoggerAdapter | None = None,
+    logger: _AnyLogger | None = None,
     log_level: int | None = None,
 ) -> list[_HandlerT]:
     handlers: list[_HandlerT] = []
@@ -225,16 +210,11 @@ def _config_handlers(
 
 
 # Default backoff handler
-def _log_backoff(
-    details: Details,
-    logger: logging.Logger | logging.LoggerAdapter,
-    log_level: int,
-) -> None:
+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:
@@ -243,16 +223,11 @@ def _log_backoff(
 
 
 # Default giveup handler
-def _log_giveup(
-    details: Details,
-    logger: logging.Logger | logging.LoggerAdapter,
-    log_level: int,
-) -> None:
+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:
@@ -266,7 +241,7 @@ def _log_giveup(
 # directly since it's no longer the active exception by this point).
 def _log_backoff_context(
     details: ContextDetails,
-    logger: logging.Logger | logging.LoggerAdapter,
+    logger: _AnyLogger,
     log_level: int,
 ) -> None:
     logger.log(
@@ -280,7 +255,7 @@ def _log_backoff_context(
 # Default giveup handler for retry_context/aretry_context.
 def _log_giveup_context(
     details: ContextDetails,
-    logger: logging.Logger | logging.LoggerAdapter,
+    logger: logging.Logger | logging.LoggerAdapter[Any],
     log_level: int,
 ) -> None:
     logger.log(

backoff/_decorator.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import inspect
 import logging
 import operator
-from typing import TYPE_CHECKING, Any, Callable, TypeVar
+from typing import TYPE_CHECKING, Any, cast
 
 from backoff import _async, _sync
 from backoff._common import (
@@ -18,29 +18,21 @@ from backoff._jitter import full_jitter
 from backoff._wait_gen import expo
 
 if TYPE_CHECKING:
-    import sys
-    from collections.abc import AsyncGenerator, Generator, Iterable
+    from collections.abc import AsyncGenerator, Callable, Generator, Iterable
 
-    from backoff._common import _Attempt
+    from backoff._common import Attempt
     from backoff._typing import (
+        _AnyLoggerOrName,
+        _CallableT,
         _ContextHandler,
         _Handler,
         _Jitterer,
         _MaybeCallable,
-        _MaybeLogger,
         _MaybeTuple,
         _Predicate,
         _WaitGenerator,
     )
 
-    if sys.version_info >= (3, 10):
-        from typing import ParamSpec
-    else:
-        from typing_extensions import ParamSpec
-
-    T = TypeVar("T")
-    P = ParamSpec("P")
-
 
 def on_predicate(
     wait_gen: _WaitGenerator,
@@ -49,14 +41,15 @@ def on_predicate(
     max_tries: _MaybeCallable[int] | None = None,
     max_time: _MaybeCallable[float] | None = None,
     jitter: _Jitterer | None = full_jitter,
+    on_try: _Handler | Iterable[_Handler] | None = None,
     on_success: _Handler | Iterable[_Handler] | None = None,
     on_backoff: _Handler | Iterable[_Handler] | None = None,
     on_giveup: _Handler | Iterable[_Handler] | None = None,
-    logger: _MaybeLogger = "backoff",
+    logger: _AnyLoggerOrName | None = "backoff",
     backoff_log_level: int = logging.INFO,
     giveup_log_level: int = logging.ERROR,
     **wait_gen_kwargs: Any,
-) -> Callable[[Callable[P, T]], Callable[P, T]]:
+) -> Callable[[_CallableT], _CallableT]:
     """Returns decorator for backoff and retry triggered by predicate.
 
     Args:
@@ -81,6 +74,9 @@ def on_predicate(
             concurrent clients. Wait times are jittered by default
             using the full_jitter function. Jittering may be disabled
             altogether by passing jitter=None.
+        on_try: Callable (or iterable of callables) with a unary
+            signature to be called before each attempt. The parameter
+            is a dict containing details about the invocation.
         on_success: Callable (or iterable of callables) with a unary
             signature to be called in the event of success. The
             parameter is a dict containing details about the invocation.
@@ -101,10 +97,11 @@ def on_predicate(
             This is useful for runtime configuration.
     """
 
-    def decorate(target: Callable[P, T]) -> Callable[P, T]:
-        nonlocal logger, on_success, on_backoff, on_giveup
+    def decorate(target: _CallableT) -> _CallableT:
+        nonlocal logger, on_try, on_success, on_backoff, on_giveup
 
         logger = _prepare_logger(logger)
+        on_try = _config_handlers(on_try)
         on_success = _config_handlers(on_success)
         on_backoff = _config_handlers(
             on_backoff,
@@ -120,21 +117,38 @@ def on_predicate(
         )
 
         if inspect.iscoroutinefunction(target):
-            retry = _async.retry_predicate
-        else:
-            retry = _sync.retry_predicate
-
-        return retry(
-            target,
-            wait_gen,
-            predicate,
-            max_tries=max_tries,
-            max_time=max_time,
-            jitter=jitter,
-            on_success=on_success,
-            on_backoff=on_backoff,
-            on_giveup=on_giveup,
-            wait_gen_kwargs=wait_gen_kwargs,
+            return cast(
+                "_CallableT",
+                _async.retry_predicate(
+                    target,
+                    wait_gen,
+                    predicate,
+                    max_tries=max_tries,
+                    max_time=max_time,
+                    jitter=jitter,
+                    on_try=on_try,
+                    on_success=on_success,
+                    on_backoff=on_backoff,
+                    on_giveup=on_giveup,
+                    wait_gen_kwargs=wait_gen_kwargs,
+                ),
+            )
+
+        return cast(
+            "_CallableT",
+            _sync.retry_predicate(
+                target,
+                wait_gen,
+                predicate,
+                max_tries=max_tries,
+                max_time=max_time,
+                jitter=jitter,
+                on_try=on_try,
+                on_success=on_success,
+                on_backoff=on_backoff,
+                on_giveup=on_giveup,
+                wait_gen_kwargs=wait_gen_kwargs,
+            ),
         )
 
     # Return a function which decorates a target with a retry loop.
@@ -149,15 +163,16 @@ def on_exception(
     max_time: _MaybeCallable[float] | None = None,
     jitter: _Jitterer | None = full_jitter,
     giveup: _Predicate[Exception] = lambda e: False,
+    on_try: _Handler | Iterable[_Handler] | None = None,
     on_success: _Handler | Iterable[_Handler] | None = None,
     on_backoff: _Handler | Iterable[_Handler] | None = None,
     on_giveup: _Handler | Iterable[_Handler] | None = None,
     raise_on_giveup: bool = True,
-    logger: _MaybeLogger = "backoff",
+    logger: _AnyLoggerOrName | None = "backoff",
     backoff_log_level: int = logging.INFO,
     giveup_log_level: int = logging.ERROR,
     **wait_gen_kwargs: Any,
-) -> Callable[[Callable[P, T]], Callable[P, T]]:
+) -> Callable[[_CallableT], _CallableT]:
     """Returns decorator for backoff and retry triggered by exception.
 
     Args:
@@ -183,6 +198,9 @@ def on_exception(
         giveup: Function accepting an exception instance and
             returning whether or not to give up. Optional. The default
             is to always continue.
+        on_try: Callable (or iterable of callables) with a unary
+            signature to be called before each attempt. The parameter
+            is a dict containing details about the invocation.
         on_success: Callable (or iterable of callables) with a unary
             signature to be called in the event of success. The
             parameter is a dict containing details about the invocation.
@@ -204,10 +222,11 @@ def on_exception(
             This is useful for runtime configuration.
     """
 
-    def decorate(target: Callable[P, T]) -> Callable[P, T]:
-        nonlocal logger, on_success, on_backoff, on_giveup
+    def decorate(target: _CallableT) -> _CallableT:
+        nonlocal logger, on_try, on_success, on_backoff, on_giveup
 
         logger = _prepare_logger(logger)
+        on_try = _config_handlers(on_try)
         on_success = _config_handlers(on_success)
         on_backoff = _config_handlers(
             on_backoff,
@@ -223,23 +242,42 @@ def on_exception(
         )
 
         if inspect.iscoroutinefunction(target):
-            retry = _async.retry_exception
-        else:
-            retry = _sync.retry_exception
-
-        return retry(
-            target,
-            wait_gen,
-            exception,
-            max_tries=max_tries,
-            max_time=max_time,
-            jitter=jitter,
-            giveup=giveup,
-            on_success=on_success,
-            on_backoff=on_backoff,
-            on_giveup=on_giveup,
-            raise_on_giveup=raise_on_giveup,
-            wait_gen_kwargs=wait_gen_kwargs,
+            return cast(
+                "_CallableT",
+                _async.retry_exception(
+                    target,
+                    wait_gen,
+                    exception,
+                    max_tries=max_tries,
+                    max_time=max_time,
+                    jitter=jitter,
+                    giveup=giveup,
+                    on_try=on_try,
+                    on_success=on_success,
+                    on_backoff=on_backoff,
+                    on_giveup=on_giveup,
+                    raise_on_giveup=raise_on_giveup,
+                    wait_gen_kwargs=wait_gen_kwargs,
+                ),
+            )
+
+        return cast(
+            "_CallableT",
+            _sync.retry_exception(
+                target,
+                wait_gen,
+                exception,
+                max_tries=max_tries,
+                max_time=max_time,
+                jitter=jitter,
+                giveup=giveup,
+                on_try=on_try,
+                on_success=on_success,
+                on_backoff=on_backoff,
+                on_giveup=on_giveup,
+                raise_on_giveup=raise_on_giveup,
+                wait_gen_kwargs=wait_gen_kwargs,
+            ),
         )
 
     # Return a function which decorates a target with a retry loop.
@@ -254,23 +292,29 @@ def retry_context(
     max_time: _MaybeCallable[float] | None = None,
     jitter: _Jitterer | None = full_jitter,
     giveup: _Predicate[BaseException] = lambda e: False,
+    on_try: _ContextHandler | Iterable[_ContextHandler] | None = None,
     on_success: _ContextHandler | Iterable[_ContextHandler] | None = None,
     on_backoff: _ContextHandler | Iterable[_ContextHandler] | None = None,
     on_giveup: _ContextHandler | Iterable[_ContextHandler] | None = None,
     raise_on_giveup: bool = True,
-    logger: _MaybeLogger = "backoff",
+    logger: _AnyLoggerOrName | None = "backoff",
     backoff_log_level: int = logging.INFO,
     giveup_log_level: int = logging.ERROR,
     **wait_gen_kwargs: Any,
-) -> Generator[_Attempt, None, None]:
+) -> Generator[Attempt, None, None]:
     """Returns a generator of retry attempts, for direct use with a `for` loop.
 
     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
@@ -313,6 +357,7 @@ def retry_context(
             passed to wait_gen when it is initialized.
     """
     logger = _prepare_logger(logger)
+    on_try = _config_handlers(on_try)
     on_success = _config_handlers(on_success)
     on_backoff = _config_handlers(
         on_backoff,
@@ -334,6 +379,7 @@ def retry_context(
         max_time=max_time,
         jitter=jitter,
         giveup=giveup,
+        on_try=on_try,
         on_success=on_success,
         on_backoff=on_backoff,
         on_giveup=on_giveup,
@@ -350,25 +396,32 @@ def aretry_context(
     max_time: _MaybeCallable[float] | None = None,
     jitter: _Jitterer | None = full_jitter,
     giveup: _Predicate[BaseException] = lambda e: False,
+    on_try: _ContextHandler | Iterable[_ContextHandler] | None = None,
     on_success: _ContextHandler | Iterable[_ContextHandler] | None = None,
     on_backoff: _ContextHandler | Iterable[_ContextHandler] | None = None,
     on_giveup: _ContextHandler | Iterable[_ContextHandler] | None = None,
     raise_on_giveup: bool = True,
-    logger: _MaybeLogger = "backoff",
+    logger: _AnyLoggerOrName | None = "backoff",
     backoff_log_level: int = logging.INFO,
     giveup_log_level: int = logging.ERROR,
     **wait_gen_kwargs: Any,
-) -> AsyncGenerator[_Attempt, None]:
+) -> 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.
     """
     logger = _prepare_logger(logger)
+    on_try = _config_handlers(on_try)
     on_success = _config_handlers(on_success)
     on_backoff = _config_handlers(
         on_backoff,
@@ -390,6 +443,7 @@ def aretry_context(
         max_time=max_time,
         jitter=jitter,
         giveup=giveup,
+        on_try=on_try,
         on_success=on_success,
         on_backoff=on_backoff,
         on_giveup=on_giveup,

backoff/_sync.py

@@ -2,13 +2,14 @@ from __future__ import annotations
 
 import functools
 import time
-from typing import TYPE_CHECKING, Any, Callable, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar
 
-from backoff._common import _Attempt, _dispatch_handlers, _RetryState
+from backoff._common import Attempt, _dispatch_handlers, _RetryState
 
 if TYPE_CHECKING:
     import sys
-    from collections.abc import Generator, Iterable
+    from collections.abc import Callable, Generator, Iterable
+    from typing import ParamSpec
 
     from backoff._typing import (
         ContextDetails,
@@ -24,11 +25,6 @@ if TYPE_CHECKING:
         _WaitGenerator,
     )
 
-    if sys.version_info >= (3, 10):
-        from typing import ParamSpec
-    else:
-        from typing_extensions import ParamSpec
-
     if sys.version_info >= (3, 11):
         from typing import Unpack
     else:
@@ -53,9 +49,8 @@ def _call_handlers(
         "kwargs": kwargs,
         "tries": tries,
         "elapsed": elapsed,
+        **extra,
     }
-    # pyrefly: ignore [no-matching-overload]
-    details.update(extra)
     for hdlr in hdlrs:
         hdlr(details)
 
@@ -68,6 +63,7 @@ def retry_predicate(
     max_tries: _MaybeCallable[int] | None,
     max_time: _MaybeCallable[float] | None,
     jitter: _Jitterer | None,
+    on_try: Iterable[_Handler],
     on_success: Iterable[_Handler],
     on_backoff: Iterable[_Handler],
     on_giveup: Iterable[_Handler],
@@ -83,14 +79,16 @@ def retry_predicate(
         )
         while True:
             state.start_attempt()
-            ret = target(*args, **kwargs)
             details: _BaseDetails = {
                 "target": target,
                 "args": args,
                 "kwargs": kwargs,
                 "tries": state.tries,
-                "elapsed": state.record_elapsed(),
+                "elapsed": state.elapsed,
             }
+            _call_handlers(on_try, **details)
+            ret = target(*args, **kwargs)
+            details["elapsed"] = state.record_elapsed()
 
             if predicate(ret):
                 if state.exhausted():
@@ -143,6 +141,7 @@ def retry_exception(
     max_time: _MaybeCallable[float] | None,
     jitter: _Jitterer | None,
     giveup: _Predicate[Exception],
+    on_try: Iterable[_Handler],
     on_success: Iterable[_Handler],
     on_backoff: Iterable[_Handler],
     on_giveup: Iterable[_Handler],
@@ -160,6 +159,7 @@ def retry_exception(
             max_time=max_time,
             jitter=jitter,
             giveup=giveup,  # type: ignore[arg-type] # ty:ignore[invalid-argument-type]
+            on_try=_adapt_context_handlers(on_try, target, args, kwargs),
             on_success=_adapt_context_handlers(on_success, target, args, kwargs),
             on_backoff=_adapt_context_handlers(on_backoff, target, args, kwargs),
             on_giveup=_adapt_context_handlers(on_giveup, target, args, kwargs),
@@ -182,12 +182,13 @@ def retry_context(
     max_time: _MaybeCallable[float] | None,
     jitter: _Jitterer | None,
     giveup: _Predicate[BaseException],
+    on_try: Iterable[_ContextHandler],
     on_success: Iterable[_ContextHandler],
     on_backoff: Iterable[_ContextHandler],
     on_giveup: Iterable[_ContextHandler],
     raise_on_giveup: bool,
     wait_gen_kwargs: dict[str, Any],
-) -> Generator[_Attempt, None, None]:
+) -> Generator[Attempt, None, None]:
     state = _RetryState(
         wait_gen,
         wait_gen_kwargs,
@@ -196,7 +197,8 @@ def retry_context(
     )
     while True:
         state.start_attempt()
-        attempt = _Attempt(exception)
+        attempt = Attempt(exception)
+        _dispatch_handlers(handlers=on_try, tries=state.tries, elapsed=state.elapsed)
         yield attempt
         elapsed = state.record_elapsed()
 

backoff/_typing.py

@@ -1,14 +1,8 @@
 from __future__ import annotations
 
 import logging
-from collections.abc import Coroutine, Generator
-from typing import (
-    Any,
-    Callable,
-    TypedDict,
-    TypeVar,
-    Union,
-)
+from collections.abc import Callable, Coroutine, Generator
+from typing import Any, TypeAlias, TypedDict, TypeVar
 
 
 class _BaseDetails(TypedDict):
@@ -36,6 +30,7 @@ class _BaseContextDetails(TypedDict):
 
 class _ContextCallDetails(TypedDict, total=False):
     wait: float  # present in the on_backoff handler case
+    value: Any  # present in the on_predicate decorator case
     exception: Exception  # present in the on_giveup handler case
 
 
@@ -48,21 +43,16 @@ class ContextDetails(_BaseContextDetails, _ContextCallDetails, total=False):
 
 T = TypeVar("T")
 
+_AnyLogger = logging.Logger | logging.LoggerAdapter  # type: ignore[type-arg]
+_AnyLoggerOrName = str | _AnyLogger
 _CallableT = TypeVar("_CallableT", bound=Callable[..., Any])  # ruff:ignore[unused-private-type-var]
-_Handler = Union[
-    Callable[[Details], None],
-    Callable[[Details], Coroutine[Any, Any, None]],
-]
-_ContextHandler = Union[
-    Callable[[ContextDetails], None],
-    Callable[[ContextDetails], Coroutine[Any, Any, None]],
-]
+_ContextHandler = (
+    Callable[[ContextDetails], None]
+    | Callable[[ContextDetails], Coroutine[Any, Any, None]]
+)
+_Handler = Callable[[Details], None] | Callable[[Details], Coroutine[Any, Any, None]]
 _Jitterer = Callable[[float], float]
-_MaybeCallable = Union[T, Callable[[], T]]
-_MaybeLogger = Union[str, logging.Logger, logging.LoggerAdapter, None]
-_MaybeTuple = Union[T, tuple[T, ...]]
-_Predicate = Union[
-    Callable[[T], bool],
-    Callable[[T], Coroutine[Any, Any, bool]],
-]
+_MaybeCallable: TypeAlias = T | Callable[[], T]  # ruff: ignore[unused-private-type-alias]
+_MaybeTuple: TypeAlias = T | tuple[T, ...]  # ruff: ignore[unused-private-type-alias]
+_Predicate = Callable[[T], bool] | Callable[[T], Coroutine[Any, Any, bool]]
 _WaitGenerator = Callable[..., Generator[float, Any, None]]

backoff/_wait_gen.py

@@ -2,10 +2,12 @@ from __future__ import annotations
 
 import itertools
 import math
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any, ParamSpec
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterable
+    from collections.abc import Callable, Generator, Iterable
+
+    P = ParamSpec("P")
 
 
 def expo(
@@ -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,10 +99,84 @@ 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
 
+    Useful for honoring a server-specified retry delay, e.g. an HTTP
+    `Retry-After` header, rather than a fixed wait sequence:
+
+    ```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
             function's return value or thrown exception and

backoff/types.py

@@ -1,5 +1,6 @@
-from ._typing import Details
+from ._typing import ContextDetails, Details
 
 __all__ = [
+    "ContextDetails",
     "Details",
 ]

{python_backoff-2.4.0.dist-info → python_backoff-3.1.0.dist-info}/METADATA

@@ -1,7 +1,8 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-backoff
-Version: 2.4.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>
@@ -15,17 +16,17 @@ Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 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
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 
 backoff
@@ -40,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
@@ -53,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
 ========
 
@@ -183,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-2.4.0.dist-info → python_backoff-3.1.0.dist-info}/WHEEL

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

python_backoff-2.4.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-backoff/__init__.py,sha256=BeZF5I4RDsBoy2C1xNvabGaJ5ez6m8JFteZYElAL_RM,988
-backoff/_async.py,sha256=xx5z-gkSK484W09d2On9vTQvnMbK-KyzVuiZPR67zFA,8936
-backoff/_common.py,sha256=2p0oj1toXysJ7jVxYr6fZ3Q3Pa7CYpje44k116C7il4,8939
-backoff/_decorator.py,sha256=rMTzMgRz7tPI0sIy6tCI9Q0RBStRX7bcgYuiYg9TlKU,16114
-backoff/_jitter.py,sha256=wzQHBDNuYg7owbc3fcZLOr5uhhRgqiuncU5rIYOB9lY,766
-backoff/_sync.py,sha256=iL5JBScW-l93opMSs09lSHMBFnrDBWjpml_Ar12yJME,6510
-backoff/_typing.py,sha256=RkIqYIJwjUlhwg5Z6TIF3HkCIv1oKDAtDGRDZJO0K48,1856
-backoff/_wait_gen.py,sha256=uyDnfEcOzUpLeGqktkVZ2pBr-NKu4K03qYug-VR_KJo,3056
-backoff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-backoff/types.py,sha256=rOQAfuetqVwfEIuzVvK5D_w97A3wrZ9lQ8HwuJ_uq5s,59
-python_backoff-2.4.0.dist-info/METADATA,sha256=Xek_me-7Sxh1vUE8Tb5NSdeSylTrBIUruOUJwLsQ7XQ,14809
-python_backoff-2.4.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-python_backoff-2.4.0.dist-info/licenses/LICENSE,sha256=KmtNX4hNTXob8E6n3xlEzxKzLjWnmobQoHWi0_QPuaw,1077
-python_backoff-2.4.0.dist-info/RECORD,,