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

backoff/_decorator.py

@@ -1,39 +1,51 @@
+from __future__ import annotations
+
 import inspect
 import logging
 import operator
-from typing import Any, Callable, Iterable, Optional, Type, Union
+from typing import TYPE_CHECKING, Any, cast
 
+from backoff import _async, _sync
 from backoff._common import (
-    _prepare_logger,
     _config_handlers,
     _log_backoff,
+    _log_backoff_context,
     _log_giveup,
+    _log_giveup_context,
+    _prepare_logger,
 )
 from backoff._jitter import full_jitter
-from backoff import _async, _sync
-from backoff._typing import (
-    _CallableT,
-    _Handler,
-    _Jitterer,
-    _MaybeCallable,
-    _MaybeLogger,
-    _MaybeSequence,
-    _Predicate,
-    _WaitGenerator,
-)
+from backoff._wait_gen import expo
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Callable, Generator, Iterable
+
+    from backoff._common import Attempt
+    from backoff._typing import (
+        _AnyLoggerOrName,
+        _CallableT,
+        _ContextHandler,
+        _Handler,
+        _Jitterer,
+        _MaybeCallable,
+        _MaybeTuple,
+        _Predicate,
+        _WaitGenerator,
+    )
 
 
 def on_predicate(
     wait_gen: _WaitGenerator,
     predicate: _Predicate[Any] = operator.not_,
     *,
-    max_tries: Optional[_MaybeCallable[int]] = None,
-    max_time: Optional[_MaybeCallable[float]] = None,
-    jitter: Union[_Jitterer, None] = full_jitter,
-    on_success: Union[_Handler, Iterable[_Handler], None] = None,
-    on_backoff: Union[_Handler, Iterable[_Handler], None] = None,
-    on_giveup: Union[_Handler, Iterable[_Handler], None] = None,
-    logger: _MaybeLogger = "backoff",
+    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: _AnyLoggerOrName | None = "backoff",
     backoff_log_level: int = logging.INFO,
     giveup_log_level: int = logging.ERROR,
     **wait_gen_kwargs: Any,
@@ -62,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.
@@ -82,10 +97,11 @@ def on_predicate(
             This is useful for runtime configuration.
     """
 
-    def decorate(target):
-        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,
@@ -101,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.
@@ -124,17 +157,18 @@ def on_predicate(
 
 def on_exception(
     wait_gen: _WaitGenerator,
-    exception: _MaybeSequence[Type[Exception]],
+    exception: _MaybeTuple[type[Exception]],
     *,
-    max_tries: Optional[_MaybeCallable[int]] = None,
-    max_time: Optional[_MaybeCallable[float]] = None,
-    jitter: Union[_Jitterer, None] = full_jitter,
+    max_tries: _MaybeCallable[int] | None = None,
+    max_time: _MaybeCallable[float] | None = None,
+    jitter: _Jitterer | None = full_jitter,
     giveup: _Predicate[Exception] = lambda e: False,
-    on_success: Union[_Handler, Iterable[_Handler], None] = None,
-    on_backoff: Union[_Handler, Iterable[_Handler], None] = None,
-    on_giveup: Union[_Handler, Iterable[_Handler], None] = None,
+    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,
@@ -164,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.
@@ -185,10 +222,11 @@ def on_exception(
             This is useful for runtime configuration.
     """
 
-    def decorate(target):
-        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,
@@ -204,24 +242,201 @@ 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.
     return decorate
+
+
+def retry_context(
+    exception: _MaybeTuple[type[Exception]] = Exception,
+    wait_gen: _WaitGenerator = expo,
+    *,
+    max_tries: _MaybeCallable[int] | None = None,
+    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: _AnyLoggerOrName | None = "backoff",
+    backoff_log_level: int = logging.INFO,
+    giveup_log_level: int = logging.ERROR,
+    **wait_gen_kwargs: Any,
+) -> 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()
+
+    Each `attempt` is a context manager: exceptions matching `exception`
+    are caught, and the loop either sleeps and retries or lets the
+    exception (or a different one) propagate once retries are exhausted.
+    Succeeding (no exception raised in the `with` block) ends the loop.
+
+    Args:
+        exception: An exception type (or tuple of types) which triggers
+            backoff.
+        wait_gen: A generator yielding successive wait times in seconds.
+        max_tries: The maximum number of attempts to make before giving
+            up. Once exhausted, the exception will be allowed to escape.
+            The default value of None means there is no limit to the
+            number of tries. If a callable is passed, it will be
+            evaluated at runtime and its return value used.
+        max_time: The maximum total amount of time to try for before
+            giving up. Once expired, the exception will be allowed to
+            escape. If a callable is passed, it will be evaluated at
+            runtime and its return value used.
+        jitter: A function of the value yielded by wait_gen returning
+            the actual time to wait. Jittered by default using
+            full_jitter; disable with jitter=None.
+        giveup: Function accepting an exception instance and returning
+            whether or not to give up. Optional. The default is to
+            always continue.
+        on_success: Callable (or iterable of callables) with a unary
+            signature called on success. The parameter is a dict with
+            `tries` and `elapsed`.
+        on_backoff: Callable (or iterable of callables) called on
+            backoff. The parameter dict additionally has `wait` and
+            `exception`.
+        on_giveup: Callable (or iterable of callables) called when
+            giving up. The parameter dict additionally has `exception`.
+        raise_on_giveup: Boolean indicating whether the registered
+            exception should be raised on giveup. Defaults to `True`.
+        logger: Name or Logger object to log to. Defaults to 'backoff'.
+        backoff_log_level: log level for the backoff event. Defaults to "INFO"
+        giveup_log_level: log level for the give up event. Defaults to "ERROR"
+        **wait_gen_kwargs: Any additional keyword args specified will be
+            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,
+        default_handler=_log_backoff_context,
+        logger=logger,
+        log_level=backoff_log_level,
+    )
+    on_giveup = _config_handlers(
+        on_giveup,
+        default_handler=_log_giveup_context,
+        logger=logger,
+        log_level=giveup_log_level,
+    )
+
+    return _sync.retry_context(
+        exception,
+        wait_gen,
+        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,
+    )
+
+
+def aretry_context(
+    exception: _MaybeTuple[type[Exception]] = Exception,
+    wait_gen: _WaitGenerator = expo,
+    *,
+    max_tries: _MaybeCallable[int] | None = None,
+    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: _AnyLoggerOrName | None = "backoff",
+    backoff_log_level: int = logging.INFO,
+    giveup_log_level: int = logging.ERROR,
+    **wait_gen_kwargs: Any,
+) -> 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()
+
+    `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,
+        default_handler=_log_backoff_context,
+        logger=logger,
+        log_level=backoff_log_level,
+    )
+    on_giveup = _config_handlers(
+        on_giveup,
+        default_handler=_log_giveup_context,
+        logger=logger,
+        log_level=giveup_log_level,
+    )
+
+    return _async.aretry_context(
+        exception,
+        wait_gen,
+        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,
+    )