Add RetryingCaller and AsyncRetryingCaller (#56)

* Add RetryingCaller and AsyncRetryingCaller

Implements #45

* Add PR link

* Update CHANGELOG.md

Author: hynek

CHANGELOG.md

@@ -15,6 +15,11 @@ You can find our backwards-compatibility policy [here](https://github.com/hynek/
 
 ## [Unreleased](https://github.com/hynek/stamina/compare/24.1.0...HEAD)
 
+### Added
+
+- `stamina.RetryingCaller` and `stamina.AsyncRetryingCaller` that allow even easier retries of single callables.
+  [#56](https://github.com/hynek/stamina/pull/56)
+
 
 ## [24.1.0](https://github.com/hynek/stamina/compare/23.3.0...24.1.0) - 2024-01-03
 

docs/api.md

@@ -7,6 +7,8 @@
 .. autofunction:: retry_context
 .. autoclass:: Attempt
    :members: num
+.. autoclass:: RetryingCaller
+.. autoclass:: AsyncRetryingCaller
 ```
 
 

docs/tutorial.md

@@ -46,6 +46,21 @@ for attempt in stamina.retry_context(on=httpx.HTTPError):
         resp.raise_for_status()
 ```
 
+If you want to retry just one function call, *stamina* comes with an even easier way in the shape of {class}`stamina.RetryingCaller` and {class}`stamina.AsyncRetryingCaller`:
+
+```python
+def do_something_with_url(url, some_kw):
+    resp = httpx.get(url)
+    resp.raise_for_status()
+    ...
+
+rc = stamina.RetryingCaller(on=httpx.HTTPError)
+
+rc(do_something_with_url, f"https://httpbin.org/status/404", some_kw=42)
+```
+
+The last line calls `do_something_with_url(f"https://httpbin.org/status/404", some_kw=42)` and retries on `httpx.HTTPError`.
+
 
 ## Async
 

src/stamina/__init__.py

@@ -4,7 +4,13 @@
 
 from . import instrumentation
 from ._config import is_active, set_active
-from ._core import Attempt, retry, retry_context
+from ._core import (
+    AsyncRetryingCaller,
+    Attempt,
+    RetryingCaller,
+    retry,
+    retry_context,
+)
 
 
 __all__ = [
@@ -14,6 +20,8 @@
     "is_active",
     "set_active",
     "instrumentation",
+    "RetryingCaller",
+    "AsyncRetryingCaller",
 ]
 
 

src/stamina/_core.py

@@ -12,7 +12,7 @@
 from functools import wraps
 from inspect import iscoroutinefunction
 from types import TracebackType
-from typing import AsyncIterator, Iterator, TypeVar
+from typing import AsyncIterator, Awaitable, Iterator, TypedDict, TypeVar
 
 import tenacity as _t
 
@@ -126,6 +126,95 @@ def __exit__(
         )
 
 
+class RetryKWs(TypedDict):
+    on: type[Exception] | tuple[type[Exception], ...]
+    attempts: int | None
+    timeout: float | dt.timedelta | None
+    wait_initial: float | dt.timedelta
+    wait_max: float | dt.timedelta
+    wait_jitter: float | dt.timedelta
+    wait_exp_base: float
+
+
+class BaseRetryingCaller:
+    """
+    .. versionadded:: 24.2.0
+    """
+
+    __slots__ = ("_context_kws",)
+
+    _context_kws: RetryKWs
+
+    def __init__(
+        self,
+        on: type[Exception] | tuple[type[Exception], ...],
+        attempts: int | None = 10,
+        timeout: float | dt.timedelta | None = 45.0,
+        wait_initial: float | dt.timedelta = 0.1,
+        wait_max: float | dt.timedelta = 5.0,
+        wait_jitter: float | dt.timedelta = 1.0,
+        wait_exp_base: float = 2.0,
+    ):
+        self._context_kws = {
+            "on": on,
+            "attempts": attempts,
+            "timeout": timeout,
+            "wait_initial": wait_initial,
+            "wait_max": wait_max,
+            "wait_jitter": wait_jitter,
+            "wait_exp_base": wait_exp_base,
+        }
+
+    def __repr__(self) -> str:
+        on = guess_name(self._context_kws["on"])
+        kws = ", ".join(
+            f"{k}={self._context_kws[k]!r}"  # type: ignore[literal-required]
+            for k in sorted(self._context_kws)
+            if k != "on"
+        )
+        return f"<{self.__class__.__name__}(on={on}, {kws})>"
+
+
+class RetryingCaller(BaseRetryingCaller):
+    """
+    An object that will call your callable with retries.
+
+    Instances of `RetryingCaller` may be reused because they create a new
+    :func:`retry_context` iterator on each call.
+
+    .. versionadded:: 24.2.0
+    """
+
+    def __call__(
+        self, func: Callable[P, T], /, *args: P.args, **kw: P.kwargs
+    ) -> T:
+        for attempt in retry_context(**self._context_kws):
+            with attempt:
+                return func(*args, **kw)
+
+        raise SystemError("unreachable")  # pragma: no cover  # noqa: EM101
+
+
+class AsyncRetryingCaller(BaseRetryingCaller):
+    """
+    An object that will call your async callable with retries.
+
+    Instances of `AsyncRetryingCaller` may be reused because they create a new
+    :func:`retry_context` iterator on each call.
+
+    .. versionadded:: 24.2.0
+    """
+
+    async def __call__(
+        self, func: Callable[P, Awaitable[T]], /, *args: P.args, **kw: P.kwargs
+    ) -> T:
+        async for attempt in retry_context(**self._context_kws):
+            with attempt:
+                return await func(*args, **kw)
+
+        raise SystemError("unreachable")  # pragma: no cover  # noqa: EM101
+
+
 _STOP_NO_RETRY = _t.stop_after_attempt(1)
 
 

tests/test_async.py

@@ -209,3 +209,27 @@ async def test_retry_blocks_can_be_disabled():
                 raise Exception("passed")
 
     assert 1 == num_called
+
+
+class TestAsyncRetryingCaller:
+    async def test_retries(self):
+        """
+        Retries if the specific error is raised. Arguments are passed through.
+        """
+        i = 0
+
+        async def f(*args, **kw):
+            nonlocal i
+            if i < 1:
+                i += 1
+                raise ValueError
+
+            return args, kw
+
+        arc = stamina.AsyncRetryingCaller(on=ValueError)
+
+        args, kw = await arc(f, 42, foo="bar")
+
+        assert 1 == i
+        assert (42,) == args
+        assert {"foo": "bar"} == kw

tests/test_sync.py

@@ -172,3 +172,47 @@ def test_never(self):
         If all conditions are None, return stop_never.
         """
         assert tenacity.stop_never is _make_stop(attempts=None, timeout=None)
+
+
+class TestRetryingCaller:
+    def test_retries(self):
+        """
+        Retries if the specific error is raised. Arguments are passed through.
+        """
+        i = 0
+
+        def f(*args, **kw):
+            nonlocal i
+            if i < 1:
+                i += 1
+                raise ValueError
+
+            return args, kw
+
+        rc = stamina.RetryingCaller(on=ValueError)
+
+        args, kw = rc(f, 42, foo="bar")
+
+        assert 1 == i
+        assert (42,) == args
+        assert {"foo": "bar"} == kw
+
+    def test_repr(self):
+        """
+        repr() is useful.
+        """
+        rc = stamina.RetryingCaller(
+            on=ValueError,
+            attempts=42,
+            timeout=13.0,
+            wait_initial=23,
+            wait_max=123,
+            wait_jitter=0.42,
+            wait_exp_base=666,
+        )
+
+        assert (
+            "<RetryingCaller(on=ValueError, attempts=42, timeout=13.0, "
+            "wait_exp_base=666, wait_initial=23, wait_jitter=0.42, "
+            "wait_max=123)>"
+        ) == repr(rc)

tests/typing/api.py

@@ -12,6 +12,8 @@
 import datetime as dt
 
 from stamina import (
+    AsyncRetryingCaller,
+    RetryingCaller,
     is_active,
     retry,
     retry_context,
@@ -125,3 +127,22 @@ async def f() -> None:
     ):
         with attempt:
             pass
+
+
+def sync_f(x: int, foo: str) -> bool:
+    return True
+
+
+rc = RetryingCaller(on=ValueError, timeout=13.0, attempts=10)
+b: bool = rc(sync_f, 1, foo="bar")
+
+
+async def async_f(x: int, foo: str) -> bool:
+    return True
+
+
+arc = AsyncRetryingCaller(on=ValueError, timeout=13.0, attempts=10)
+
+
+async def g() -> bool:
+    return await arc(async_f, 1, foo="bar")