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

backoff/_sync.py

@@ -1,144 +1,238 @@
+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 = {
+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,
+    target: Callable[P, T],
+    wait_gen: _WaitGenerator,
+    predicate: _Predicate[T],
     *,
-    max_tries,
-    max_time,
-    jitter,
-    on_success,
-    on_backoff,
-    on_giveup,
-    wait_gen_kwargs,
-):
+    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)
 
                 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 _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,
-    wait_gen,
-    exception,
+    target: Callable[P, T],
+    wait_gen: _WaitGenerator,
+    exception: _MaybeTuple[type[Exception]],
     *,
-    max_tries,
-    max_time,
-    jitter,
-    giveup,
-    on_success,
-    on_backoff,
-    on_giveup,
-    raise_on_giveup,
-    wait_gen_kwargs,
-):
+    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
-
-                _call_handlers(on_backoff, **details, wait=seconds, exception=e)
+        return ret
 
-                time.sleep(seconds)
-            else:
-                _call_handlers(on_success, **details)
+    return retry
 
-                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,43 +1,68 @@
+from __future__ import annotations
+
 import logging
-from types import FunctionType
+from collections.abc import Coroutine, Generator
 from typing import (
     Any,
     Callable,
-    Coroutine,
-    Dict,
-    Generator,
-    Sequence,
-    Tuple,
     TypedDict,
     TypeVar,
     Union,
 )
 
 
-class _Details(TypedDict):
-    target: FunctionType
-    args: Tuple[Any, ...]
-    kwargs: Dict[str, Any]
+class _BaseDetails(TypedDict):
+    target: Callable[..., 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,12 +1,17 @@
+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.
 
@@ -18,21 +23,20 @@ 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]:
 
@@ -46,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:
@@ -66,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
 
@@ -110,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)

{python_backoff-2.3.1.dist-info → python_backoff-2.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-backoff
-Version: 2.3.1
+Version: 2.4.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,12 +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
@@ -27,7 +25,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.9
 Description-Content-Type: text/x-rst
 
 backoff
@@ -406,7 +404,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.4.0.dist-info/RECORD

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

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

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.28.0
+Generator: hatchling 1.31.0
 Root-Is-Purelib: true
 Tag: py3-none-any

python_backoff-2.3.1.dist-info/RECORD

@@ -1,14 +0,0 @@
-backoff/__init__.py,sha256=MS4ieVYpjBh-feDqzJHYJy8mjnuEEaprTWWuXgJI-1A,914
-backoff/_async.py,sha256=Ehv3H3jMF9JylzZzHTLSLwK_s0PoJa_1jeGo3qtpcOY,6370
-backoff/_common.py,sha256=Q8ZB8mCMI76WLii8JcrfoSZc11WRqu7ci_mpG1y-j9Y,3460
-backoff/_decorator.py,sha256=61iXFb5jN2mQ9-1mtRPi_gysJwuyhkKrbDVNWH8GDxo,9483
-backoff/_jitter.py,sha256=wzQHBDNuYg7owbc3fcZLOr5uhhRgqiuncU5rIYOB9lY,766
-backoff/_sync.py,sha256=7W0aTlntrL237rfhy2yaFklZheQoYxBTD5F_4TUarQI,3867
-backoff/_typing.py,sha256=hO065un_HjJEsEa_OgW66JZRyxVf-BsJ9HrswIwW3fA,1056
-backoff/_wait_gen.py,sha256=ZTZfs4WiI295EvOJeJYPIUAABQ0WBAKcvUtg0_ZId8k,3244
-backoff/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-backoff/types.py,sha256=rOQAfuetqVwfEIuzVvK5D_w97A3wrZ9lQ8HwuJ_uq5s,59
-python_backoff-2.3.1.dist-info/METADATA,sha256=o7ltpQ3fk4s05tUCVIeUgZVzGFfigmw06jNoz6HM6RI,14885
-python_backoff-2.3.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-python_backoff-2.3.1.dist-info/licenses/LICENSE,sha256=KmtNX4hNTXob8E6n3xlEzxKzLjWnmobQoHWi0_QPuaw,1077
-python_backoff-2.3.1.dist-info/RECORD,,