Generalize retrying callers for sharing retry config w/o exc config

Ref #56 #45

Author: hynek

docs/api.md

@@ -8,21 +8,39 @@
 .. autoclass:: Attempt
    :members: num
 .. autoclass:: RetryingCaller
+   :members: on, __call__
 
    For example::
 
       def do_something_with_url(url, some_kw):
-          resp = httpx.get(url)
-          resp.raise_for_status()
+          resp = httpx.get(url).raise_for_status()
           ...
 
-      rc = stamina.RetryingCaller(on=httpx.HTTPError)
+      rc = stamina.RetryingCaller()
 
-      rc(do_something_with_url, f"https://httpbin.org/status/404", some_kw=42)
+      rc(httpx.HTTPError, do_something_with_url, f"https://httpbin.org/status/404", some_kw=42)
 
-   Runs ``do_something_with_url(f"https://httpbin.org/status/404", some_kw=42)`` and retries on ``httpx.HTTPError``.
+      # Equivalent:
+      bound_rc = rc.on(httpx.HTTPError)
+
+      bound_rc(do_something_with_url, f"https://httpbin.org/status/404", some_kw=42)
+
+   Both calls to ``rc`` and ``bound_rc`` run
+
+   .. code-block:: python
+
+      do_something_with_url(f"https://httpbin.org/status/404", some_kw=42)
+
+   and retry on ``httpx.HTTPError``.
+
+.. autoclass:: BoundRetryingCaller
+   :members: __call__
 
 .. autoclass:: AsyncRetryingCaller
+   :members: on, __call__
+
+.. autoclass:: BoundAsyncRetryingCaller
+   :members: __call__
 ```
 
 

docs/tutorial.md

@@ -46,6 +46,9 @@ for attempt in stamina.retry_context(on=httpx.HTTPError):
         resp.raise_for_status()
 ```
 
+
+## Retry One Function or Method Call
+
 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
@@ -54,12 +57,23 @@ def do_something_with_url(url, some_kw):
     resp.raise_for_status()
     ...
 
-rc = stamina.RetryingCaller(on=httpx.HTTPError)
+rc = stamina.RetryingCaller()
+
+rc(httpx.HTTPError, do_something_with_url, f"https://httpbin.org/status/404", some_kw=42)
+
+# You can also create a caller with a pre-bound exception type:
+bound_rc = rc.on(httpx.HTTPError)
 
-rc(do_something_with_url, f"https://httpbin.org/status/404", some_kw=42)
+bound_rc(do_something_with_url, f"https://httpbin.org/status/404", some_kw=42)
+```
+
+Both `rc` and `bound_rc` run:
+
+```python
+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`.
+and retry on `httpx.HTTPError`.
 
 
 ## Async

src/stamina/__init__.py

@@ -7,21 +7,25 @@
 from ._core import (
     AsyncRetryingCaller,
     Attempt,
+    BoundAsyncRetryingCaller,
+    BoundRetryingCaller,
     RetryingCaller,
     retry,
     retry_context,
 )
 
 
 __all__ = [
+    "AsyncRetryingCaller",
     "Attempt",
-    "retry",
-    "retry_context",
-    "is_active",
-    "set_active",
+    "BoundAsyncRetryingCaller",
+    "BoundRetryingCaller",
     "instrumentation",
+    "is_active",
+    "retry_context",
+    "retry",
     "RetryingCaller",
-    "AsyncRetryingCaller",
+    "set_active",
 ]
 
 

src/stamina/_core.py

@@ -127,7 +127,6 @@ def __exit__(
 
 
 class RetryKWs(TypedDict):
-    on: type[Exception] | tuple[type[Exception], ...]
     attempts: int | None
     timeout: float | dt.timedelta | None
     wait_initial: float | dt.timedelta
@@ -148,7 +147,6 @@ class BaseRetryingCaller:
 
     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,
@@ -157,7 +155,6 @@ def __init__(
         wait_exp_base: float = 2.0,
     ):
         self._context_kws = {
-            "on": on,
             "attempts": attempts,
             "timeout": timeout,
             "wait_initial": wait_initial,
@@ -167,35 +164,101 @@ def __init__(
         }
 
     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})>"
+        return f"<{self.__class__.__name__}({kws})>"
 
 
 class RetryingCaller(BaseRetryingCaller):
     """
     Call your callables with retries.
 
     Tip:
-        Instances of ``RetryingCaller`` may be reused because they create a new
-        :func:`retry_context` iterator on each call.
+        Instances of ``RetryingCaller`` may be reused because they internally
+        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
+        self,
+        on: type[Exception] | tuple[type[Exception], ...],
+        callable_: Callable[P, T],
+        /,
+        *args: P.args,
+        **kw: P.kwargs,
     ) -> T:
-        for attempt in retry_context(**self._context_kws):
+        r"""
+        Call ``callable_(*args, **kw)`` with retries if *on* is raised.
+
+        Args:
+            on: Exception(s) to retry on.
+
+            callable\_: Callable to call.
+
+            args: Positional arguments to pass to *callable_*.
+
+            kw: Keyword arguments to pass to *callable_*.
+        """
+        for attempt in retry_context(on, **self._context_kws):
             with attempt:
-                return func(*args, **kw)
+                return callable_(*args, **kw)
 
         raise SystemError("unreachable")  # pragma: no cover  # noqa: EM101
 
+    def on(
+        self, on: type[Exception] | tuple[type[Exception], ...], /
+    ) -> BoundRetryingCaller:
+        """
+        Create a new instance of :class:`BoundRetryingCaller` with the same
+        parameters, but bound to a specific exception type.
+
+        .. versionadded:: 24.2.0
+        """
+        return BoundRetryingCaller(self, on)
+
+
+class BoundRetryingCaller:
+    """
+    Same as :class:`RetryingCaller`, but pre-bound to a specific exception
+    type.
+
+    Caution:
+        Returned by :meth:`RetryingCaller.on` -- do not instantiate directly.
+
+    .. versionadded:: 24.2.0
+    """
+
+    __slots__ = ("_caller", "_on")
+
+    _caller: RetryingCaller
+    _on: type[Exception] | tuple[type[Exception], ...]
+
+    def __init__(
+        self,
+        caller: RetryingCaller,
+        on: type[Exception] | tuple[type[Exception], ...],
+    ):
+        self._caller = caller
+        self._on = on
+
+    def __repr__(self) -> str:
+        return (
+            f"<BoundRetryingCaller({guess_name(self._on)}, {self._caller!r})>"
+        )
+
+    def __call__(
+        self, callable_: Callable[P, T], /, *args: P.args, **kw: P.kwargs
+    ) -> T:
+        """
+        Same as :func:`RetryingCaller.__call__`, except retry on the exception
+        that is bound to this instance.
+        """
+        return self._caller(self._on, callable_, *args, **kw)
+
 
 class AsyncRetryingCaller(BaseRetryingCaller):
     """
@@ -205,14 +268,74 @@ class AsyncRetryingCaller(BaseRetryingCaller):
     """
 
     async def __call__(
-        self, func: Callable[P, Awaitable[T]], /, *args: P.args, **kw: P.kwargs
+        self,
+        on: type[Exception] | tuple[type[Exception], ...],
+        callable_: Callable[P, Awaitable[T]],
+        /,
+        *args: P.args,
+        **kw: P.kwargs,
     ) -> T:
-        async for attempt in retry_context(**self._context_kws):
+        """
+        Same as :meth:`RetryingCaller.__call__`, but *callable_* is awaited.
+        """
+        async for attempt in retry_context(on, **self._context_kws):
             with attempt:
-                return await func(*args, **kw)
+                return await callable_(*args, **kw)
 
         raise SystemError("unreachable")  # pragma: no cover  # noqa: EM101
 
+    def on(
+        self, on: type[Exception] | tuple[type[Exception], ...], /
+    ) -> BoundAsyncRetryingCaller:
+        """
+        Create a new instance of :class:`BoundAsyncRetryingCaller` with the
+        same parameters, but bound to a specific exception type.
+
+        .. versionadded:: 24.2.0
+        """
+        return BoundAsyncRetryingCaller(self, on)
+
+
+class BoundAsyncRetryingCaller:
+    """
+    Same as :class:`BoundRetryingCaller`, but for async callables.
+
+    Caution:
+        Returned by :meth:`AsyncRetryingCaller.on` -- do not instantiate
+        directly.
+
+    .. versionadded:: 24.2.0
+    """
+
+    __slots__ = ("_caller", "_on")
+
+    _caller: AsyncRetryingCaller
+    _on: type[Exception] | tuple[type[Exception], ...]
+
+    def __init__(
+        self,
+        caller: AsyncRetryingCaller,
+        on: type[Exception] | tuple[type[Exception], ...],
+    ):
+        self._caller = caller
+        self._on = on
+
+    def __repr__(self) -> str:
+        return f"<BoundAsyncRetryingCaller({guess_name(self._on)}, {self._caller!r})>"
+
+    async def __call__(
+        self,
+        callable_: Callable[P, Awaitable[T]],
+        /,
+        *args: P.args,
+        **kw: P.kwargs,
+    ) -> T:
+        """
+        Same as :func:`AsyncRetryingCaller.__call__`, except retry on the
+        exception that is bound to this instance.
+        """
+        return await self._caller(self._on, callable_, *args, **kw)
+
 
 _STOP_NO_RETRY = _t.stop_after_attempt(1)
 

tests/test_async.py

@@ -226,10 +226,34 @@ async def f(*args, **kw):
 
             return args, kw
 
-        arc = stamina.AsyncRetryingCaller(on=ValueError)
+        arc = stamina.AsyncRetryingCaller().on(ValueError)
 
         args, kw = await arc(f, 42, foo="bar")
 
         assert 1 == i
         assert (42,) == args
         assert {"foo": "bar"} == kw
+
+    def test_repr(self):
+        """
+        repr() is useful
+        """
+        arc = stamina.AsyncRetryingCaller(
+            attempts=42,
+            timeout=13.0,
+            wait_initial=23,
+            wait_max=123,
+            wait_jitter=0.42,
+            wait_exp_base=666,
+        )
+
+        r = repr(arc)
+
+        assert (
+            "<AsyncRetryingCaller(attempts=42, timeout=13.0, "
+            "wait_exp_base=666, wait_initial=23, wait_jitter=0.42, "
+            "wait_max=123)>"
+        ) == r
+        assert f"<BoundAsyncRetryingCaller(ValueError, {r})>" == repr(
+            arc.on(ValueError)
+        )

tests/test_sync.py

@@ -189,9 +189,9 @@ def f(*args, **kw):
 
             return args, kw
 
-        rc = stamina.RetryingCaller(on=ValueError)
+        bound_rc = stamina.RetryingCaller().on(ValueError)
 
-        args, kw = rc(f, 42, foo="bar")
+        args, kw = bound_rc(f, 42, foo="bar")
 
         assert 1 == i
         assert (42,) == args
@@ -202,7 +202,6 @@ def test_repr(self):
         repr() is useful.
         """
         rc = stamina.RetryingCaller(
-            on=ValueError,
             attempts=42,
             timeout=13.0,
             wait_initial=23,
@@ -211,8 +210,13 @@ def test_repr(self):
             wait_exp_base=666,
         )
 
+        r = repr(rc)
+
         assert (
-            "<RetryingCaller(on=ValueError, attempts=42, timeout=13.0, "
+            "<RetryingCaller(attempts=42, timeout=13.0, "
             "wait_exp_base=666, wait_initial=23, wait_jitter=0.42, "
             "wait_max=123)>"
-        ) == repr(rc)
+        ) == r
+        assert f"<BoundRetryingCaller(ValueError, {r})>" == repr(
+            rc.on(ValueError)
+        )