tenacity

Tenacity is an Apache 2.0 licensed, general-purpose retrying library for Python that makes it trivial to add resilient retry behavior to functions, coroutines, and arbitrary blocks of code. Originating as a maintained fork of the abandoned retrying library, it exposes a simple @retry decorator alongside a rich, composable vocabulary of stop, wait, and retry conditions.

Instead of scattering ad-hoc try/except loops throughout a codebase, developers declare retry policies declaratively: how many attempts to make, how long to wait between them, which exceptions or return values should trigger a retry, and what to do when retries are finally exhausted. This makes it a staple dependency for code that talks to flaky networks, remote APIs, and distributed services.

What You Get

• A generic @retry decorator that works on plain functions, async coroutines, and Tornado coroutines
• Composable stop conditions such as stop_after_attempt and stop_after_delay that combine with the | operator
• A full family of wait strategies including fixed, random, and exponential backoff with jitter
• Fine-grained retry predicates that react to specific exception types or to the returned result
• Callbacks and logging hooks (before, after, before_sleep) plus per-call retry statistics

Common Use Cases

• Retrying HTTP calls to remote APIs and microservices that fail intermittently
• Adding exponential backoff with jitter when contending for shared or rate-limited resources
• Waiting for eventually-consistent systems (databases, queues, cloud resources) to become ready
• Hardening background jobs and data pipelines against transient network and I/O errors

Under The Hood

Architecture - Tenacity centers on a BaseRetrying engine (in tenacity/__init__.py) that drives an attempt loop, delegating three orthogonal decisions to pluggable strategy objects: stop conditions (tenacity/stop.py), wait strategies (tenacity/wait.py), and retry predicates (tenacity/retry.py). Each strategy is a small callable that receives a shared RetryCallState carrying attempt number, outcome future, and timing data; strategies compose via overloaded | and & operators into retry_any/retry_all trees. Synchronous execution flows through Retrying, while tenacity/asyncio/ provides an AsyncRetrying variant that awaits coroutine outcomes and sleeps, and tenacity/tornadoweb.py adapts the loop to Tornado coroutines.

Tech Stack - Pure Python (100% of the codebase) targeting Python 3.10+, with zero required runtime dependencies. It ships type hints and a py.typed marker for full typing support. The build uses Hatchling with hatch-vcs for git-tag-derived versioning. Development tooling includes pytest, mypy, ruff, poethepoet task running, Sphinx with reno for docs, and optional Tornado/trio/typeguard for testing async integrations.

Code Quality - The project is well tested, with an extensive tests/test_tenacity.py (130+ test functions) plus dedicated suites for asyncio, Tornado, utilities, and regression tests for specific issues. Code is fully type-annotated and mypy-checked, uses clear abstract base classes for each strategy family, and follows consistent naming (stop_*, wait_*, retry_if_*). Apache-2.0 license headers are present across source files.

API Design - The public API is a highlight: the bare @retry decorator works with zero configuration, while keyword arguments (stop, wait, retry, reraise, before_sleep) layer in behavior incrementally. Strategy objects read declaratively and combine with intuitive boolean operators, keeping call sites free of imperative loop boilerplate. Extensive ReadTheDocs documentation with doctest-verified examples makes the learning curve gentle for common cases while still exposing RetryCallState for advanced custom callbacks.