Install & Compatibility
Where this runs
tested against v26.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.104s · 22.2MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.0s · import 0.092s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
retry
✓ from stamina import retry
Main decorator for retrying functions.
retry_context
✓ from stamina import retry_context
For retrying arbitrary code blocks using a context manager.
set_testing
✓ from stamina import set_testing
For activating/deactivating test mode and controlling retry behavior during tests.
RetryingCaller
✓ from stamina import RetryingCaller
For retrying single function/method calls without decorating.
This quickstart demonstrates using the `@stamina.retry` decorator with `httpx` to handle transient HTTP errors. It configures retries for `httpx.HTTPStatusError` but includes a custom check to only retry on 5xx status codes, explicitly not retrying on 4xx client errors, and limits attempts and total timeout.
import httpx
import stamina
import os
@stamina.retry(on=httpx.HTTPStatusError, attempts=3, timeout=5)
def fetch_url_with_retry(url: str) -> str:
try:
response = httpx.get(url, timeout=1)
response.raise_for_status() # Raises HTTPStatusError for 4xx/5xx responses
return f"Successfully fetched: {response.status_code}"
except httpx.HTTPStatusError as e:
# Example: only retry on 5xx errors
if e.response.status_code >= 500:
print(f"Retrying on {e.response.status_code} for {url}...")
raise
else:
print(f"Not retrying on {e.response.status_code} for {url}.")
raise
except httpx.RequestError as e:
print(f"Request error for {url}: {e}, retrying...")
raise
# Example usage:
try:
# This URL will fail with 500 and retry
print(fetch_url_with_retry("https://httpbin.org/status/500"))
except (httpx.HTTPStatusError, httpx.RequestError) as e:
print(f"Final failure after retries for 500: {e}")
try:
# This URL will fail with 404 and not retry (due to the if e.response.status_code >= 500 check)
print(fetch_url_with_retry("https://httpbin.org/status/404"))
except (httpx.HTTPStatusError, httpx.RequestError) as e:
print(f"Final failure for 404 (not retried): {e}")
try:
# This URL will succeed
print(fetch_url_with_retry("https://httpbin.org/status/200"))
except (httpx.HTTPStatusError, httpx.RequestError) as e:
print(f"Unexpected failure for 200: {e}")
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'stamina'
The 'stamina' library is not installed in the current Python environment.
TypeError: retry() got an unexpected keyword argument 'wait'
The `stamina.retry` decorator does not accept a `wait` argument. It simplifies Tenacity's wait strategies by providing direct parameters like `wait_min` and `wait_max`.
fixReplace `wait` with appropriate `stamina.retry` parameters such as `wait_min`, `wait_max`, `wait_initial`, `wait_multiplier`, or `wait_jitter`. Example: `@stamina.retry(wait_min=0.1, wait_max=10)`.
AttributeError: module 'stamina' has no attribute 'wait_fixed'
The `stamina` library simplifies Tenacity's complex wait strategies and does not expose specific wait functions like `wait_fixed` or `wait_exponential` as separate importable objects.
fixConfigure retry delay behavior using the `stamina.retry` decorator's built-in parameters: `wait_min`, `wait_max`, `wait_initial`, `wait_multiplier`, and `wait_jitter`.
TypeError: retry() missing 1 required positional argument: 'func'
When specifying multiple exception types for the `on` argument in `stamina.retry`, they must be provided as a single tuple, not as separate keyword arguments. The second exception is misinterpreted as the decorated function.
fixWrap multiple exception types in a tuple for the `on` argument. Example: `@stamina.retry(on=(ValueError, KeyError))`.
Upgrade
Version history
26.1.0latest on PyPI · released Apr 13, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.
httpxoptionalCommonly used in examples for HTTP requests; not a core dependency but useful for quickstart.
prometheus-clientoptionalOptional for Prometheus instrumentation of retries.
structlogoptionalOptional for structlog instrumentation of retries.