Skip to main content

Production-grade retries made easy.

Project description

stamina: Production-grade Retries Made Easy

Transient failures are common in distributed systems. To make your systems resilient, you need to retry failed operations. But bad retries can make things much worse.

stamina is an opinionated wrapper around the great-but-unopinionated Tenacity package. Its 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.
  • Exponential backoff with jitter between retries.
  • Limit the number of retries and total time.
  • Automatic async support – including Trio.
  • Preserve type hints of the decorated callable.
  • Flexible instrumentation with Prometheus, structlog, and standard library's logging support out-of-the-box.
  • Easy global deactivation for testing.

For example:

import httpx

import stamina

@stamina.retry(on=httpx.HTTPError, attempts=3)
def do_it(code: int) -> httpx.Response:
    resp = httpx.get(f"{code}")

    return resp

Async callables work use the same API and it's possible to retry arbitrary blocks, too. Check out our tutorial for more examples!

Release Information


  • stamina.RetryingCaller and stamina.AsyncRetryingCaller that allow even easier retries of single callables: stamina.RetryingCaller(attempts=5).on(ValueError)(do_something, "foo", bar=42) and stamina.RetryingCaller(attempts=5)(ValueError, do_something, "foo", bar=42) will call do_something("foo", bar=42) and retry on ValueError up to 5 times.

    stamina.RetryingCaller and stamina.AsyncRetryingCaller take the same arguments as stamina.retry(), except for on that can be bound separately.

    #56 #57

Full Changelog →


stamina is written by Hynek Schlawack and distributed under the terms of the MIT license.

The development is kindly supported by my employer Variomedia AG and all my amazing GitHub Sponsors.

This project would not be possible without the years of incredible work that went into Tenacity.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

stamina-24.2.0.tar.gz (553.1 kB view hashes)

Uploaded Source

Built Distribution

stamina-24.2.0-py3-none-any.whl (14.9 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page