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

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

@@ -1,3 +1,5 @@
+uv.lock
+
 __pycache__/
 *.pyc
 .coverage*

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

@@ -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-2.4.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-2.4.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,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"

{python_backoff-2.4.0 → python_backoff-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()
 

{python_backoff-2.4.0 → python_backoff-3.1.0}/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(