One retry decorator for def and async def alike. Exponential backoff, jitter,
exception filtering, per-attempt hooks. Zero dependencies, fully typed, ~140 lines.
from jitretry import retry
@retry(attempts=4, on=(ConnectionError, TimeoutError), base_delay=0.2)
def charge(amount: int) -> str:
return payment_api.charge(amount)
@retry(attempts=4, on=ConnectionError) # same decorator, async wrapper
async def charge_async(amount: int) -> str:
return await async_payment_api.charge(amount)Four attempts: one call plus three retries, waiting ~0.2s, 0.4s, 0.8s with jitter. A
ValueError is not in on=, so it propagates immediately instead of burning three more
attempts on a bug.
Hand-rolled retry loops are almost always subtly wrong: they sleep after the last attempt,
retry on KeyboardInterrupt, have no jitter so every client hammers the recovering service
in lockstep, and can't be tested without actually waiting. This is that loop written once,
short enough to read before you trust it in a payment path.
pip install jitretry # requires Python 3.12+, pulls in nothing elseto_thread=True runs a blocking function on a worker thread and releases that thread
during backoff, so the pool isn't held hostage by waiting.
@retry(attempts=3, to_thread=True)
def legacy_client(query: str) -> list[dict]:
return old_driver.execute(query) # blocking
async def handler() -> list[dict]:
return await legacy_client("select 1")Against the usual alternative — await asyncio.to_thread(tenacity_wrapped_call), which
occupies a slot for the calls and every pause — measured 5.4x faster at 40 concurrent
tasks over a 4-thread pool, and 1.02x (i.e. no difference) when the pool isn't
saturated. Full table and method: benchmarks/.
on_retry fires after every failure that will be retried, and not after the final one.
import logging
from jitretry import Attempt, retry
log = logging.getLogger(__name__)
def record(attempt: Attempt) -> None:
log.warning(
"attempt %d failed with %r, retrying in %.2fs",
attempt.number,
attempt.exception,
attempt.delay,
)
@retry(attempts=5, on_retry=record)
def sync_inventory() -> None: ...@retry works bare or configured. Invalid values raise ValueError at decoration
time, so a bad config fails at import, not on the first production outage.
| Argument | Default | Meaning |
|---|---|---|
attempts |
3 |
Total calls including the first — 3 is one call plus two retries |
on |
Exception |
What triggers a retry. Anything else propagates immediately |
base_delay / multiplier / max_delay |
0.1 / 2.0 / 10.0 |
Backoff curve. The cap applies before jitter |
jitter |
Jitter.FULL |
FULL, EQUAL or NONE — the AWS taxonomy |
on_retry |
None |
(Attempt) -> None, called per retried failure |
to_thread |
False |
Run a sync function off the event loop, releasing the thread during backoff |
sleep / async_sleep / rng |
stdlib | Injectable, so tests assert exact delay sequences without waiting |
Also exported: Attempt (frozen dataclass — number, exception, delay, elapsed),
Jitter, and compute_delay (the backoff formula as a pure function).
Generator functions are rejected at decoration time — decorating one would be a silent no-op, since calling it returns a generator without running the body.
Measured against tenacity 9.1.4 and backoff 2.2.1, not from memory:
| jitretry | tenacity | backoff | |
|---|---|---|---|
Zero deps · py.typed · jitter · hooks · sync+async |
yes | yes | yes |
| On exhaustion | original exception | RetryError wrapper |
original exception |
| Releases the thread during backoff | yes | no | no |
Stop conditions, retry_if_*, statistics |
no | yes | partial |
| Lines of code | 138 | 1711 | 722 |
The first row is table stakes — all three have it. Two things actually differ: the thread
behaviour measured above, and that adding retries here doesn't change the exception your
callers catch (tenacity wraps it in RetryError unless you remember reraise=True,
silently breaking except ConnectionError upstream).
Everything else tips their way: tenacity and backoff are far more featureful and more battle-tested. Want a retry DSL, or the library your on-call team already knows? Use them. Want retries with jitter in a file you can read end to end? Use this.
Reasoning behind each choice: DESIGN.md.
uv sync && uv run pytest # 56 tests, 98% coverage, runs in 0.1s
uv run ruff check . && pyright
uv run --group bench python benchmarks/to_thread_bench.pyMIT