Skip to content
vsevalidPublic

About

One retry decorator for both sync and async Python functions: exponential backoff, AWS-taxonomy jitter, per-attempt hooks, and a to_thread mode that releases the worker thread during backoff. Zero dependencies, fully typed.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

jitretry

CI Python Checked with pyright Ruff License: MIT

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.

Why

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.

Install

pip install jitretry     # requires Python 3.12+, pulls in nothing else

Retrying blocking calls from async code

to_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/.

Watching retries happen

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: ...

API

@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.

Compared to tenacity and backoff

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.

Development

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.py

MIT

About

One retry decorator for both sync and async Python functions: exponential backoff, AWS-taxonomy jitter, per-attempt hooks, and a to_thread mode that releases the worker thread during backoff. Zero dependencies, fully typed.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages