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

backoff/__init__.py

@@ -12,11 +12,13 @@ For examples and full documentation see the README at
 https://github.com/python-backoff/backoff
 """
 
+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
 
 __all__ = [
+    "Attempt",
     "aretry_context",
     "constant",
     "decay",
@@ -30,4 +32,4 @@ __all__ = [
     "runtime",
 ]
 
-__version__ = "2.4.0"
+__version__ = "3.0.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")
@@ -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,11 +210,7 @@ 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]
 
@@ -243,11 +224,7 @@ 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]
 
@@ -266,7 +243,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 +257,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,15 +292,16 @@ 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
@@ -313,6 +352,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 +374,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,15 +391,16 @@ 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):
@@ -369,6 +411,7 @@ def aretry_context(
     `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 +433,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,10 @@ from __future__ import annotations
 
 import itertools
 import math
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterable
+    from collections.abc import Callable, Generator, Iterable
 
 
 def expo(
@@ -103,6 +103,27 @@ 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:
+
+        # 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.0.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-backoff
-Version: 2.4.0
+Version: 3.0.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
@@ -15,7 +15,6 @@ 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
@@ -25,7 +24,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.9
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 
 backoff

python_backoff-3.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+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,,

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

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.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,,