Wordsmith

README.md

@@ -17,7 +17,7 @@ But bad retries can make things *much worse*.
 Our goal is to be as **ergonomic** as possible, while doing the **right thing by default**, and minimizing the potential for **misuse**.
 It is the result of years of copy-pasting the same configuration over and over again:
 
-- Retry only on certain exceptions – or even a subset of them by introspecting them first.
+- Retry only on certain exceptions – or even a subset of them by introspecting them first using a predicate.
 - Exponential **backoff** with **jitter** between retries.
 - Limit the number of retries **and** total time.
 - Automatic **async** support – including [Trio](https://trio.readthedocs.io/).

docs/tutorial.md

@@ -35,7 +35,8 @@ Sometimes, an exception is too broad, though.
 For example, *httpx* raises [`httpx.HTTPStatusError`](https://www.python-httpx.org/exceptions/) on all HTTP errors.
 But some errors, like 404 (Not Found) or 403 (Forbidden), usually shouldn't be retried!
 
-To solve problems like this, you can pass a callable to `on` that will be called with the exception that was raised and whose return value will be used to decide whether to retry or not.
+To solve problems like this, you can pass a *predicate* to `on`.
+A predicate is a callable that's called with the exception that was raised and whose return value will be used to decide whether to retry or not.
 
 So, calling the following `do_it` function will only retry if <https://httpbin.org> returns a 5xx status code:
 

src/stamina/_core.py

@@ -571,11 +571,14 @@ def retry(
             An Exception or a tuple of Exceptions on which the decorated
             callable will be retried.
 
-            You can also pass a callable that takes an exception and returns a
-            bool which decides whether the exception should be retried. This
-            allows more fine-grained control over when to retry. For example,
-            to only retry on HTTP errors in the 500s range that indicate server
-            errors, but not those in the 400s which indicate a client error.
+            You can also pass a *predicate* in the form of a callable that
+            takes an exception and returns a bool which decides whether the
+            exception should be retried -- True meaning yes.
+
+            This allows more fine-grained control over when to retry. For
+            example, to only retry on HTTP errors in the 500s range that
+            indicate server errors, but not those in the 400s which indicate a
+            client error.
 
             There is no default -- you *must* pass this explicitly.