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

{python_backoff-2.3.1 → python_backoff-3.0.0}/.gitignore

@@ -1,6 +1,8 @@
+uv.lock
+
 __pycache__/
 *.pyc
-.coverage
+.coverage*
 virtualenv
 MANIFEST
 build/

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: python-backoff
-Version: 2.3.1
+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
@@ -11,13 +11,10 @@ License-File: LICENSE
 Keywords: backoff,decorators,retry
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -27,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.8
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 
 backoff
@@ -406,7 +403,7 @@ asynchronous HTTP client/server library.
         max_time=60,
     )
     async def get_url(url):
-        async with aiohttp.ClientSession(raise_for_status=True) as session:  # noqa: SIM117
+        async with aiohttp.ClientSession(raise_for_status=True) as session:  # ruff:ignore[multiple-with-statements]
             async with session.get(url) as response:
                 return await response.text()
 

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

@@ -374,7 +374,7 @@ asynchronous HTTP client/server library.
         max_time=60,
     )
     async def get_url(url):
-        async with aiohttp.ClientSession(raise_for_status=True) as session:  # noqa: SIM117
+        async with aiohttp.ClientSession(raise_for_status=True) as session:  # ruff:ignore[multiple-with-statements]
             async with session.get(url) as response:
                 return await response.text()
 

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

@@ -12,20 +12,24 @@ For examples and full documentation see the README at
 https://github.com/python-backoff/backoff
 """
 
-from backoff._decorator import on_exception, on_predicate
+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, expo, fibo, runtime, decay
+from backoff._wait_gen import constant, decay, expo, fibo, runtime
 
 __all__ = [
-    "on_predicate",
-    "on_exception",
+    "Attempt",
+    "aretry_context",
     "constant",
-    "expo",
     "decay",
+    "expo",
     "fibo",
-    "runtime",
     "full_jitter",
+    "on_exception",
+    "on_predicate",
     "random_jitter",
+    "retry_context",
+    "runtime",
 ]
 
-__version__ = "2.3.1"
+__version__ = "3.0.0"

python_backoff-3.0.0/backoff/_async.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import asyncio
+import functools
+import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, TypeVar
+
+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,
+        Details,
+        _BaseDetails,
+        _CallDetails,
+        _ContextHandler,
+        _Handler,
+        _Jitterer,
+        _MaybeCallable,
+        _MaybeTuple,
+        _Predicate,
+        _WaitGenerator,
+    )
+
+    if sys.version_info >= (3, 11):
+        from typing import Unpack
+    else:
+        from typing_extensions import Unpack
+
+    T = TypeVar("T")
+    P = ParamSpec("P")
+
+_AsyncHandler = Callable[["Details"], "Coroutine[Any, Any, None]"]
+
+
+def _ensure_coroutine(
+    coro_or_func: Callable[..., Any],
+) -> Callable[..., Coroutine[Any, Any, Any]]:
+    if inspect.iscoroutinefunction(coro_or_func):
+        return coro_or_func
+
+    @functools.wraps(coro_or_func)
+    async def f(*args: Any, **kwargs: Any) -> Any:  # ruff:ignore[unused-async]
+        return coro_or_func(*args, **kwargs)
+
+    return f
+
+
+def _ensure_coroutines(
+    coros_or_funcs: Iterable[Callable[..., Any]],
+) -> list[Callable[..., Coroutine[Any, Any, Any]]]:
+    return [_ensure_coroutine(f) for f in coros_or_funcs]
+
+
+async def _call_handlers(
+    handlers: Iterable[_AsyncHandler],
+    *,
+    target: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+    tries: int,
+    elapsed: float,
+    **extra: Unpack[_CallDetails],
+) -> None:
+    details: Details = {
+        "target": target,
+        "args": args,
+        "kwargs": kwargs,
+        "tries": tries,
+        "elapsed": elapsed,
+        **extra,
+    }
+    for handler in handlers:
+        await handler(details)
+
+
+def retry_predicate(
+    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, 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)
+
+    # Easy to implement, please report if you need this.
+    assert not inspect.iscoroutinefunction(max_tries)
+    assert not inspect.iscoroutinefunction(jitter)
+
+    assert inspect.iscoroutinefunction(target)
+
+    @functools.wraps(target)
+    async def retry(*args: P.args, **kwargs: P.kwargs) -> T:
+        state = _RetryState(
+            wait_gen,
+            wait_gen_kwargs,
+            max_tries=max_tries,
+            max_time=max_time,
+        )
+        while True:
+            state.start_attempt()
+            details: _BaseDetails = {
+                "target": target,
+                "args": args,
+                "kwargs": kwargs,
+                "tries": state.tries,
+                "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():
+                    await _call_handlers(on_giveup, **details, value=ret)
+                    break
+
+                try:
+                    seconds = state.next_wait(ret, jitter)
+                except StopIteration:
+                    await _call_handlers(on_giveup, **details, value=ret)
+                    break
+
+                await _call_handlers(on_backoff, **details, value=ret, wait=seconds)
+
+                # Note: there is no convenient way to pass explicit event
+                # loop to decorator, so here we assume that either default
+                # thread event loop is set and correct (it mostly is
+                # by default), or Python >= 3.5.3 or Python >= 3.6 is used
+                # where loop.get_event_loop() in coroutine guaranteed to
+                # return correct value.
+                # See for details:
+                #   <https://groups.google.com/forum/#!topic/python-tulip/yF9C-rFpiKk>
+                #   <https://bugs.python.org/issue28613>
+                await asyncio.sleep(seconds)
+                continue
+            await _call_handlers(on_success, **details, value=ret)
+            break
+
+        return ret
+
+    return retry
+
+
+def _adapt_context_handlers(
+    handlers: Iterable[_AsyncHandler],
+    target: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> list[_ContextHandler]:
+    async def adapted(details: ContextDetails) -> None:
+        full_details: Details = {
+            "target": target,
+            "args": args,
+            "kwargs": kwargs,
+            **details,
+        }
+        for hdlr in handlers:
+            await hdlr(full_details)
+
+    return [adapted]
+
+
+def retry_exception(
+    target: Callable[P, Coroutine[object, object, T]],
+    wait_gen: _WaitGenerator,
+    exception: _MaybeTuple[type[Exception]],
+    *,
+    max_tries: _MaybeCallable[int] | None,
+    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, 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)
+    giveup = _ensure_coroutine(giveup)
+
+    # Easy to implement, please report if you need this.
+    assert not inspect.iscoroutinefunction(max_tries)
+    assert not inspect.iscoroutinefunction(jitter)
+
+    @functools.wraps(target)
+    async def retry(
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> T:
+        ret: T = None  # type: ignore[assignment] # ty:ignore[invalid-assignment]
+
+        async for attempt in aretry_context(
+            exception,
+            wait_gen,
+            max_tries=max_tries,
+            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),
+            raise_on_giveup=raise_on_giveup,
+            wait_gen_kwargs=wait_gen_kwargs,
+        ):
+            with attempt:
+                ret = await target(*args, **kwargs)
+
+        return ret
+
+    return retry
+
+
+async def _dispatch_handlers(
+    handlers: Iterable[_ContextHandler], **details: Any
+) -> None:
+    for hdlr in _ensure_coroutines(handlers):
+        await hdlr(details)
+
+
+async def aretry_context(
+    exception: _MaybeTuple[type[Exception]],
+    wait_gen: _WaitGenerator,
+    *,
+    max_tries: _MaybeCallable[int] | None,
+    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]:
+    giveup = _ensure_coroutine(giveup)
+
+    state = _RetryState(
+        wait_gen,
+        wait_gen_kwargs,
+        max_tries=max_tries,
+        max_time=max_time,
+    )
+    while True:
+        state.start_attempt()
+        attempt = Attempt(exception)
+        await _dispatch_handlers(
+            handlers=on_try,
+            tries=state.tries,
+            elapsed=state.elapsed,
+        )
+        yield attempt
+        elapsed = state.record_elapsed()
+
+        exc = attempt.exception
+        if exc is None:
+            await _dispatch_handlers(on_success, tries=state.tries, elapsed=elapsed)
+            return
+
+        if await giveup(exc) or state.exhausted():
+            await _dispatch_handlers(
+                on_giveup,
+                tries=state.tries,
+                elapsed=elapsed,
+                exception=exc,
+            )
+            if raise_on_giveup:
+                raise exc
+            return
+
+        try:
+            seconds = state.next_wait(exc, jitter)
+        except StopIteration:
+            await _dispatch_handlers(
+                on_giveup,
+                tries=state.tries,
+                elapsed=elapsed,
+                exception=exc,
+            )
+            raise exc from None
+
+        await _dispatch_handlers(
+            on_backoff,
+            tries=state.tries,
+            elapsed=elapsed,
+            wait=seconds,
+            exception=exc,
+        )
+
+        await asyncio.sleep(seconds)

python_backoff-3.0.0/backoff/_common.py

@@ -0,0 +1,268 @@
+from __future__ import annotations
+
+import functools
+import logging
+import time
+import traceback
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, TypeAlias, TypeVar
+
+if TYPE_CHECKING:
+    import sys
+    from collections.abc import Callable, Generator, Iterable
+
+    from backoff._typing import (
+        ContextDetails,
+        Details,
+        _AnyLogger,
+        _AnyLoggerOrName,
+        _ContextHandler,
+        _Jitterer,
+        _MaybeCallable,
+        _WaitGenerator,
+    )
+
+    if sys.version_info >= (3, 11):
+        from typing import Self
+    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")
+_logger.addHandler(logging.NullHandler())  # pragma: no cover
+_logger.setLevel(logging.INFO)
+
+T = TypeVar("T")
+_HandlerT = TypeVar("_HandlerT")
+
+
+# Evaluate arg that can be either a fixed value or a callable.
+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]
+        except TypeError:
+            return f  # type: ignore[return-value] # ty:ignore[invalid-return-type]
+    else:
+        return f
+
+
+def _init_wait_gen(
+    wait_gen: _WaitGenerator,
+    wait_gen_kwargs: dict[str, Any],
+) -> Generator[float, Any, None]:
+    kwargs = {k: _maybe_call(v) for k, v in wait_gen_kwargs.items()}
+    initialized = wait_gen(**kwargs)
+    initialized.send(None)  # Initialize with an empty send
+    return initialized
+
+
+def _next_wait(
+    wait: Generator[float, None, None],
+    send_value: Any,
+    jitter: _Jitterer | None,
+    elapsed: float,
+    max_time: float | None,
+) -> float:
+    value = wait.send(send_value)
+    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:
+        seconds = min(seconds, max_time - elapsed)
+
+    return seconds
+
+
+class _RetryState:
+    """Bookkeeping shared by the sync and async retry loops.
+
+    Tracks try count and elapsed time, and owns the initialized wait
+    generator, so `retry_predicate`/`retry_exception` only need to drive
+    the call/check/sleep sequence around it.
+    """
+
+    __slots__ = (
+        "elapsed",
+        "max_time",
+        "max_tries",
+        "start",
+        "tries",
+        "wait",
+    )
+
+    def __init__(
+        self,
+        wait_gen: _WaitGenerator,
+        wait_gen_kwargs: dict[str, Any],
+        *,
+        max_tries: _MaybeCallable[int] | None = None,
+        max_time: _MaybeCallable[float] | None = None,
+    ) -> None:
+        self.tries = 0
+        self.elapsed: float = 0
+        self.start = time.monotonic()
+        self.max_tries = _maybe_call(max_tries)
+        self.max_time = _maybe_call(max_time)
+        self.wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+
+    def start_attempt(self) -> None:
+        self.tries += 1
+
+    def record_elapsed(self) -> float:
+        self.elapsed = time.monotonic() - self.start
+        return self.elapsed
+
+    def exhausted(self) -> bool:
+        max_tries_exceeded = self.tries == self.max_tries
+        max_time_exceeded = self.max_time is not None and self.elapsed >= self.max_time
+        return max_tries_exceeded or max_time_exceeded
+
+    def next_wait(self, send_value: Any, jitter: _Jitterer | None) -> float:
+        return _next_wait(self.wait, send_value, jitter, self.elapsed, self.max_time)
+
+
+@dataclass(slots=True)
+class Attempt:
+    """A single attempt yielded by `retry_context`/`aretry_context`.
+
+    Used as `with attempt: ...`. Exceptions matching `exception_types` are
+    caught here so the driving generator (not this object) decides whether
+    to retry, sleep, or let the exception propagate; anything else, or no
+    exception at all, is left for the `with` block's normal exit behavior.
+    """
+
+    exception_types: ExceptionTypes
+    exception: BaseException | None = field(init=False)
+
+    def __post_init__(self) -> None:
+        self.exception: BaseException | None = None
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: object,
+    ) -> bool:
+        if exc_type is None:
+            return False
+
+        if not issubclass(exc_type, self.exception_types):
+            return False  # not ours; propagate immediately
+
+        self.exception = exc
+        return True  # suppress for now; the driving generator decides next
+
+
+def _dispatch_handlers(handlers: Iterable[_ContextHandler], **details: Any) -> None:
+    for hdlr in handlers:
+        hdlr(details)  # type: ignore[arg-type] # ty:ignore[invalid-argument-type]
+
+
+def _prepare_logger(logger: _AnyLoggerOrName | None) -> _AnyLogger | None:
+    if isinstance(logger, str):
+        logger = logging.getLogger(logger)
+    return logger
+
+
+# Configure handler list with user specified handler and optionally
+# with a default handler bound to the specified logger.
+def _config_handlers(
+    user_handlers: _HandlerT | Iterable[_HandlerT] | None,
+    *,
+    default_handler: Callable[..., None] | None = None,
+    logger: _AnyLogger | None = None,
+    log_level: int | None = None,
+) -> list[_HandlerT]:
+    handlers: list[_HandlerT] = []
+    if logger is not None:
+        assert log_level is not None, "Log level is not specified"
+        assert default_handler is not None, "Default handler is not specified"
+        # bind the specified logger to the default log handler
+        log_handler = functools.partial(
+            default_handler,
+            logger=logger,
+            log_level=log_level,
+        )
+        handlers.append(log_handler)  # type: ignore[arg-type] # ty:ignore[invalid-argument-type]
+
+    if user_handlers is None:
+        return handlers
+
+    # user specified handlers can either be an iterable of handlers
+    # or a single handler. either way append them to the list.
+    if hasattr(user_handlers, "__iter__"):
+        # add all handlers in the iterable
+        # pyrefly: ignore [bad-argument-type]
+        handlers += list(user_handlers)  # ty:ignore[invalid-argument-type]
+    else:
+        # append a single handler
+        # pyrefly: ignore [bad-argument-type]
+        handlers.append(user_handlers)
+
+    return handlers
+
+
+# Default backoff handler
+def _log_backoff(details: Details, logger: _AnyLogger, log_level: int) -> None:
+    msg = "Backing off %s(...) for %.1fs (%s)"
+    log_args = [details["target"].__name__, details["wait"]]  # ty:ignore[unresolved-attribute]
+
+    exc = details.get("exception")
+    if exc is not None:
+        exc_fmt = traceback.format_exception_only(type(exc), exc)[-1]
+        log_args.append(exc_fmt.rstrip("\n"))
+    else:
+        log_args.append(details["value"])
+    logger.log(log_level, msg, *log_args)
+
+
+# Default giveup handler
+def _log_giveup(details: Details, logger: _AnyLogger, log_level: int) -> None:
+    msg = "Giving up %s(...) after %d tries (%s)"
+    log_args = [details["target"].__name__, details["tries"]]  # ty:ignore[unresolved-attribute]
+
+    exc = details.get("exception")
+    if exc is not None:
+        exc_fmt = traceback.format_exception_only(type(exc), exc)[-1]
+        log_args.append(exc_fmt.rstrip("\n"))
+    else:
+        log_args.append(details["value"])
+
+    logger.log(log_level, msg, *log_args)
+
+
+# Default backoff handler for retry_context/aretry_context (no wrapped
+# callable, so no name to log; the exception is read from `details`
+# directly since it's no longer the active exception by this point).
+def _log_backoff_context(
+    details: ContextDetails,
+    logger: _AnyLogger,
+    log_level: int,
+) -> None:
+    logger.log(
+        log_level,
+        "Backing off retry_context(...) for %.1fs (%s)",
+        details["wait"],
+        details.get("exception"),
+    )
+
+
+# Default giveup handler for retry_context/aretry_context.
+def _log_giveup_context(
+    details: ContextDetails,
+    logger: logging.Logger | logging.LoggerAdapter[Any],
+    log_level: int,
+) -> None:
+    logger.log(
+        log_level,
+        "Giving up retry_context(...) after %d tries (%s)",
+        details["tries"],
+        details.get("exception"),
+    )