Generalize retrying callers for sharing retry config w/o exc config (#57)

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

Ref #56 #45

* docs

* Use official name in public APIs

* Docs

* Fix docs build

* Stress

* words

* Add explanation

* Use exclude_also

Author: hynek

CHANGELOG.md

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

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(attempts=5)
 
-      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/conf.py

@@ -54,7 +54,13 @@
 
 exclude_patterns = ["_build"]
 
-nitpick_ignore = [("py:class", "httpx.HTTPError")]
+nitpick_ignore = [
+    ("py:class", "httpx.HTTPError"),
+    # ParamSpec is not well-supported.
+    ("py:obj", "typing.~P"),
+    ("py:class", "~P"),
+    ("py:class", "stamina._core.T"),
+]
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True

docs/tutorial.md

@@ -46,20 +46,35 @@ 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`:
+
+## Retry One Function or Method Call
+
+If you want to retry just one function or method 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 = stamina.RetryingCaller(attempts=5)
+
+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` and as before, the type hints are preserved.
+It's up to you whether you want to share only the retry configuration or the exception type to retry on, too.
 
 
 ## Async

pyproject.toml

@@ -116,12 +116,11 @@ source = ["src", ".nox/tests*/**/site-packages"]
 [tool.coverage.report]
 show_missing = true
 skip_covered = true
-exclude_lines = [
-  "no cov",
-  "if __name__ == .__main__.:",
+exclude_also = [
+  'raise SystemError\("unreachable"\)',
   # Typing-related
   "if TYPE_CHECKING:",
-  ": \\.\\.\\.$",
+  ': \.\.\.$',
 ]
 
 

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,34 +164,105 @@ 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.
 
+    Arguments have the same meaning as for :func:`stamina.retry`.
+
     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,
+        **kwargs: 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, **kwargs)
+
+        raise SystemError("unreachable")  # 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.
 
-        raise SystemError("unreachable")  # pragma: no cover  # noqa: EM101
+        .. versionadded:: 24.2.0
+        """
+        # This should be a `functools.partial`, but unfortunately it's
+        # impossible to provide a nicely typed API with it, so we use a
+        # separate class.
+        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, **kwargs: 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, **kwargs)
 
 
 class AsyncRetryingCaller(BaseRetryingCaller):
@@ -205,13 +273,73 @@ 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,
+        **kwargs: 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, **kwargs)
 
-        raise SystemError("unreachable")  # pragma: no cover  # noqa: EM101
+        raise SystemError("unreachable")  # 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,
+        **kwargs: 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, **kwargs)
 
 
 _STOP_NO_RETRY = _t.stop_after_attempt(1)