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

backoff/_sync.py

@@ -1,130 +1,238 @@
-# coding:utf-8
+from __future__ import annotations
+
 import functools
 import time
-
-from backoff._common import (_init_wait_gen, _maybe_call, _next_wait)
-
-
-def _call_handlers(hdlrs, target, args, kwargs, tries, elapsed, **extra):
-    details = {
-        'target': target,
-        'args': args,
-        'kwargs': kwargs,
-        'tries': tries,
-        'elapsed': elapsed,
+from typing import TYPE_CHECKING, Any, Callable, TypeVar
+
+from backoff._common import _Attempt, _dispatch_handlers, _RetryState
+
+if TYPE_CHECKING:
+    import sys
+    from collections.abc import Generator, Iterable
+
+    from backoff._typing import (
+        ContextDetails,
+        Details,
+        _BaseDetails,
+        _CallDetails,
+        _ContextHandler,
+        _Handler,
+        _Jitterer,
+        _MaybeCallable,
+        _MaybeTuple,
+        _Predicate,
+        _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:
+        from typing_extensions import Unpack
+
+    T = TypeVar("T")
+    P = ParamSpec("P")
+
+
+def _call_handlers(
+    hdlrs: Iterable[_Handler],
+    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,
     }
+    # pyrefly: ignore [no-matching-overload]
     details.update(extra)
     for hdlr in hdlrs:
         hdlr(details)
 
 
-def retry_predicate(target, wait_gen, predicate,
-                    *,
-                    max_tries, max_time, jitter,
-                    on_success, on_backoff, on_giveup,
-                    wait_gen_kwargs):
-
+def retry_predicate(
+    target: Callable[P, T],
+    wait_gen: _WaitGenerator,
+    predicate: _Predicate[T],
+    *,
+    max_tries: _MaybeCallable[int] | None,
+    max_time: _MaybeCallable[float] | None,
+    jitter: _Jitterer | None,
+    on_success: Iterable[_Handler],
+    on_backoff: Iterable[_Handler],
+    on_giveup: Iterable[_Handler],
+    wait_gen_kwargs: dict[str, Any],
+) -> Callable[P, T]:
     @functools.wraps(target)
-    def retry(*args, **kwargs):
-        max_tries_value = _maybe_call(max_tries)
-        max_time_value = _maybe_call(max_time)
-
-        tries = 0
-        start = time.monotonic()
-        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
+    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:
-            tries += 1
-            elapsed = time.monotonic() - start
-            details = {
+            state.start_attempt()
+            ret = target(*args, **kwargs)
+            details: _BaseDetails = {
                 "target": target,
                 "args": args,
                 "kwargs": kwargs,
-                "tries": tries,
-                "elapsed": elapsed,
+                "tries": state.tries,
+                "elapsed": state.record_elapsed(),
             }
 
-            ret = target(*args, **kwargs)
             if predicate(ret):
-                max_tries_exceeded = (tries == max_tries_value)
-                max_time_exceeded = (max_time_value is not None and
-                                     elapsed >= max_time_value)
-
-                if max_tries_exceeded or max_time_exceeded:
+                if state.exhausted():
                     _call_handlers(on_giveup, **details, value=ret)
                     break
 
                 try:
-                    seconds = _next_wait(wait, ret, jitter, elapsed,
-                                         max_time_value)
+                    seconds = state.next_wait(ret, jitter)
                 except StopIteration:
-                    _call_handlers(on_giveup, **details)
+                    _call_handlers(on_giveup, **details, value=ret)
                     break
 
-                _call_handlers(on_backoff, **details,
-                               value=ret, wait=seconds)
+                _call_handlers(on_backoff, **details, value=ret, wait=seconds)
 
                 time.sleep(seconds)
                 continue
-            else:
-                _call_handlers(on_success, **details, value=ret)
-                break
+            _call_handlers(on_success, **details, value=ret)
+            break
 
         return ret
 
     return retry
 
 
-def retry_exception(target, wait_gen, exception,
-                    *,
-                    max_tries, max_time, jitter, giveup,
-                    on_success, on_backoff, on_giveup, raise_on_giveup,
-                    wait_gen_kwargs):
-
+def _adapt_context_handlers(
+    handlers: Iterable[_Handler],
+    target: Callable[..., Any],
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> list[_ContextHandler]:
+    def adapted(details: ContextDetails) -> None:
+        full_details: Details = {
+            "target": target,
+            "args": args,
+            "kwargs": kwargs,
+            **details,
+        }
+        for hdlr in handlers:
+            hdlr(full_details)
+
+    return [adapted]
+
+
+def retry_exception(
+    target: Callable[P, 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_success: Iterable[_Handler],
+    on_backoff: Iterable[_Handler],
+    on_giveup: Iterable[_Handler],
+    raise_on_giveup: bool,
+    wait_gen_kwargs: dict[str, Any],
+) -> Callable[P, T]:
     @functools.wraps(target)
-    def retry(*args, **kwargs):
-        max_tries_value = _maybe_call(max_tries)
-        max_time_value = _maybe_call(max_time)
-
-        tries = 0
-        start = time.monotonic()
-        wait = _init_wait_gen(wait_gen, wait_gen_kwargs)
-        while True:
-            tries += 1
-            elapsed = time.monotonic() - start
-            details = {
-                "target": target,
-                "args": args,
-                "kwargs": kwargs,
-                "tries": tries,
-                "elapsed": elapsed,
-            }
-
-            try:
+    def retry(*args: P.args, **kwargs: P.kwargs) -> T:
+        ret: T = None  # type: ignore[assignment] # ty:ignore[invalid-assignment]
+
+        for attempt in retry_context(
+            exception,
+            wait_gen,
+            max_tries=max_tries,
+            max_time=max_time,
+            jitter=jitter,
+            giveup=giveup,  # type: ignore[arg-type] # ty:ignore[invalid-argument-type]
+            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 = target(*args, **kwargs)
-            except exception as e:
-                max_tries_exceeded = (tries == max_tries_value)
-                max_time_exceeded = (max_time_value is not None and
-                                     elapsed >= max_time_value)
-
-                if giveup(e) or max_tries_exceeded or max_time_exceeded:
-                    _call_handlers(on_giveup, **details, exception=e)
-                    if raise_on_giveup:
-                        raise
-                    return None
 
-                try:
-                    seconds = _next_wait(wait, e, jitter, elapsed,
-                                         max_time_value)
-                except StopIteration:
-                    _call_handlers(on_giveup, **details, exception=e)
-                    raise e
+        return ret
 
-                _call_handlers(on_backoff, **details, wait=seconds,
-                               exception=e)
+    return retry
 
-                time.sleep(seconds)
-            else:
-                _call_handlers(on_success, **details)
 
-                return ret
-    return retry
+def retry_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_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]:
+    state = _RetryState(
+        wait_gen,
+        wait_gen_kwargs,
+        max_tries=max_tries,
+        max_time=max_time,
+    )
+    while True:
+        state.start_attempt()
+        attempt = _Attempt(exception)
+        yield attempt
+        elapsed = state.record_elapsed()
+
+        exc = attempt.exception
+        if exc is None:
+            _dispatch_handlers(on_success, tries=state.tries, elapsed=elapsed)
+            return
+
+        if giveup(exc) or state.exhausted():
+            _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:
+            _dispatch_handlers(
+                on_giveup,
+                tries=state.tries,
+                elapsed=elapsed,
+                exception=exc,
+            )
+            raise exc from None
+
+        _dispatch_handlers(
+            on_backoff,
+            tries=state.tries,
+            elapsed=elapsed,
+            wait=seconds,
+            exception=exc,
+        )
+
+        time.sleep(seconds)

backoff/_typing.py

@@ -1,45 +1,68 @@
-# coding:utf-8
+from __future__ import annotations
+
 import logging
-import sys
-from typing import (Any, Callable, Coroutine, Dict, Generator, Sequence, Tuple,
-                    TypeVar, Union)
-
-if sys.version_info >= (3, 8):  # pragma: no cover
-    from typing import TypedDict
-else:  # pragma: no cover
-    # use typing_extensions if installed but don't require it
-    try:
-        from typing_extensions import TypedDict
-    except ImportError:
-        class TypedDict(dict):
-            def __init_subclass__(cls, **kwargs: Any) -> None:
-                return super().__init_subclass__()
-
-
-class _Details(TypedDict):
+from collections.abc import Coroutine, Generator
+from typing import (
+    Any,
+    Callable,
+    TypedDict,
+    TypeVar,
+    Union,
+)
+
+
+class _BaseDetails(TypedDict):
     target: Callable[..., Any]
-    args: Tuple[Any, ...]
-    kwargs: Dict[str, Any]
+    args: tuple[Any, ...]
+    kwargs: dict[str, Any]
     tries: int
     elapsed: float
 
 
-class Details(_Details, total=False):
+class _CallDetails(TypedDict, total=False):
     wait: float  # present in the on_backoff handler case for either decorator
     value: Any  # present in the on_predicate decorator case
     exception: Exception  # present in the on_exception decorator case
 
 
+class Details(_BaseDetails, _CallDetails, total=False):
+    pass
+
+
+class _BaseContextDetails(TypedDict):
+    tries: int
+    elapsed: float
+
+
+class _ContextCallDetails(TypedDict, total=False):
+    wait: float  # present in the on_backoff handler case
+    exception: Exception  # present in the on_giveup handler case
+
+
+class ContextDetails(_BaseContextDetails, _ContextCallDetails, total=False):
+    """Details passed to handlers registered with `retry_context`/`aretry_context`.
+
+    Unlike `Details`, there's no wrapped callable, so no `target`/`args`/`kwargs`.
+    """
+
+
 T = TypeVar("T")
 
-_CallableT = TypeVar('_CallableT', bound=Callable[..., Any])
+_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]],
+]
 _Jitterer = Callable[[float], float]
 _MaybeCallable = Union[T, Callable[[], T]]
 _MaybeLogger = Union[str, logging.Logger, logging.LoggerAdapter, None]
-_MaybeSequence = Union[T, Sequence[T]]
-_Predicate = Callable[[T], bool]
-_WaitGenerator = Callable[..., Generator[float, None, None]]
+_MaybeTuple = Union[T, tuple[T, ...]]
+_Predicate = Union[
+    Callable[[T], bool],
+    Callable[[T], Coroutine[Any, Any, bool]],
+]
+_WaitGenerator = Callable[..., Generator[float, Any, None]]

backoff/_wait_gen.py

@@ -1,16 +1,18 @@
-# coding:utf-8
+from __future__ import annotations
 
 import itertools
 import math
-from typing import Any, Callable, Generator, Iterable, Optional, Union
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:
+    from collections.abc import Generator, Iterable
 
 
 def expo(
     base: float = 2,
     factor: float = 1,
-    max_value: Optional[float] = None,
+    max_value: float | None = None,
 ) -> Generator[float, Any, None]:
-
     """Generator for exponential decay.
 
     Args:
@@ -21,23 +23,21 @@ def expo(
              of max_value will forever after be yielded.
     """
     # Advance past initial .send() call
-    yield  # type: ignore[misc]
-    base_n: float = 1
+    yield 0
+
+    a = factor
+    while max_value is None or a < max_value:
+        yield a
+        a *= base
     while True:
-        a = factor * base_n
-        if max_value is None or a < max_value:
-            yield a
-            base_n *= base
-        else:
-            yield max_value
+        yield max_value
 
 
 def decay(
     initial_value: float = 1,
     decay_factor: float = 1,
-    min_value: Optional[float] = None,
+    min_value: float | None = None,
 ) -> Generator[float, Any, None]:
-
     """Generator for exponential decay[1]:
 
     Args:
@@ -50,18 +50,17 @@ def decay(
     [1] https://en.wikipedia.org/wiki/Exponential_decay
     """
     # Advance past initial .send() call
-    yield  # type: ignore[misc]
-    t = 0
+    yield 0
+    a = initial_value
+    min_value = min_value or 0.0
+    while a > min_value:
+        yield a
+        a *= math.exp(-decay_factor)
     while True:
-        a = initial_value * math.e ** (-t * decay_factor)
-        if min_value is None or a > min_value:
-            yield a
-            t += 1
-        else:
-            yield min_value
+        yield min_value
 
 
-def fibo(max_value: Optional[int] = None) -> Generator[int, None, None]:
+def fibo(max_value: int | None = None) -> Generator[int, Any, None]:
     """Generator for fibonaccial decay.
 
     Args:
@@ -70,42 +69,37 @@ def fibo(max_value: Optional[int] = None) -> Generator[int, None, None]:
              of max_value will forever after be yielded.
     """
     # Advance past initial .send() call
-    yield  # type: ignore[misc]
+    yield 0
 
     a = 1
     b = 1
+    while max_value is None or a < max_value:
+        yield a
+        a, b = b, a + b
     while True:
-        if max_value is None or a < max_value:
-            yield a
-            a, b = b, a + b
-        else:
-            yield max_value
+        yield max_value
 
 
-def constant(
-    interval: Union[int, Iterable[float]] = 1,
-) -> Generator[float, None, None]:
+def constant(interval: float | Iterable[float] = 1) -> Generator[float, Any, None]:
     """Generator for constant intervals.
 
     Args:
         interval: A constant value to yield or an iterable of such values.
     """
     # Advance past initial .send() call
-    yield  # type: ignore[misc]
+    yield 0
 
-    try:
-        itr = iter(interval)  # type: ignore
-    except TypeError:
-        itr = itertools.repeat(interval)  # type: ignore
+    itr = (
+        itertools.repeat(interval)
+        if isinstance(interval, (int, float))
+        else iter(interval)
+    )
 
     for val in itr:
         yield val
 
 
-def runtime(
-    *,
-    value: Callable[[Any], float],
-) -> Generator[float, None, None]:
+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
 
@@ -114,6 +108,6 @@ def runtime(
             function's return value or thrown exception and
             determines how long to wait
     """
-    ret_or_exc = yield  # type: ignore[misc]
+    ret_or_exc = yield 0
     while True:
         ret_or_exc = yield value(ret_or_exc)

backoff/types.py

@@ -1,6 +1,5 @@
-# coding:utf-8
 from ._typing import Details
 
 __all__ = [
-    'Details',
+    "Details",
 ]