retryhttp

retryhttp is a lightweight Python library that adds smart retry behavior for transient HTTP failures across httpx, httpx2, requests, and aiohttp. Built as a thin, opinionated layer on top of tenacity, it ships pre-configured retry and wait strategies for the errors that most commonly resolve on a second attempt: 429 rate limiting, 5xx server errors, network failures, and timeouts.

Instead of hand-rolling retry logic per HTTP client library, developers apply the @retry decorator to any function that makes an HTTP call and get context-aware backoff out of the box — honoring Retry-After headers when present, falling back to exponential backoff otherwise, and letting every behavior be overridden through keyword arguments without ever touching tenacity internals.

What You Get

• A single @retry decorator with sensible defaults for HTTP status errors, network errors, timeouts, and rate limiting
• Native support for httpx, httpx2, requests, and aiohttp — install only the client extras you need
• wait_context_aware and wait_retry_after strategies that honor a Retry-After header (seconds or HTTP-date) with configurable exponential-backoff fallback
• Fully typed, granular building blocks (retry_if_rate_limited, retry_if_server_error, retry_if_network_error, retry_if_timeout) for composing custom tenacity.retry configurations

Common Use Cases

• Wrapping API client calls that occasionally hit rate limits so a script backs off automatically instead of crashing
• Making batch jobs and data pipelines resilient to transient 5xx errors from upstream services
• Adding retry behavior to a new HTTP client integration without duplicating tenacity boilerplate
• Building internal SDKs that need to honor Retry-After headers correctly across multiple HTTP client backends

Under The Hood

Architecture The library is a flat, single-purpose module: _utils.py detects which of httpx, httpx2, requests, and aiohttp are installed and normalizes their differing exception shapes (response vs status attributes) into a common is_rate_limited/is_server_error check; _retry.py composes retry_if_server_error, retry_if_network_error, retry_if_timeout, and retry_if_rate_limited predicates via tenacity’s retry_any, and _wait.py supplies wait_context_aware (picks a wait strategy per exception type) and wait_retry_after (parses the Retry-After header). Everything converges in a single tenacity_retry(retry=..., wait=..., stop=...) call inside the retry decorator in _retry.py, so nearly all downstream behavior is tightly coupled to tenacity’s retry_base/wait_base contract — changing that core composition would ripple through every retry_if_* and wait_* class.

Tech Stack Python 3.10+ with only pydantic and tenacity as hard dependencies; httpx, httpx2, requests (plus types-requests), and aiohttp are all optional extras detected at import time via try/except. Packaged with setuptools and setuptools_scm, linted with ruff, documented with mkdocs-material and mkdocstrings, and tested across Python 3.10–3.13 via nox, with GitHub Actions running the full nox test matrix on pull requests.

Code Quality Tests in tests/ cover the retry decorator, wait strategies, and rate-limit handling using pytest with respx (and pytest-httpx2) to mock HTTP responses and assert call counts, RetryError propagation, and reraise behavior explicitly, including edge cases like non-HTTP exceptions passing through untouched. Type hints and Google-style docstrings (Args/Returns/Raises) are used consistently, a py.typed marker signals first-class typing support, and ruff enforces linting in CI across the supported Python versions.

What Makes It Unique The @retry decorator requires zero configuration to get sensible, HTTP-aware retry behavior, while wait_context_aware solves a real gap in vanilla tenacity: applying a different wait strategy per exception type (server error vs. network error vs. timeout vs. rate limit) within one retry configuration instead of forcing a single strategy for everything. Multi-client support via soft dependencies means adding retryhttp never forces a particular HTTP stack on a project. It’s an ergonomics-focused convenience layer over tenacity rather than a new retry mechanism, but a genuinely useful one for anyone tired of re-deriving Retry-After parsing and per-exception backoff logic by hand.