Pythonpythondecoratorretryresilienceproduction-ready
Configurable Retry Decorator
A decorator for retrying failed operations with exponential backoff, jitter, exception filtering, and callback hooks.
import asyncio
import functools
import random
import time
import logging
from typing import TypeVar, Callable, Any, Type
logger = logging.getLogger(__name__)
T = TypeVar("T")
class MaxRetriesExceeded(Exception):
"""Raised when all retry attempts have been exhausted."""
def __init__(self, attempts: int, last_exception: Exception):
self.attempts = attempts
self.last_exception = last_exception
super().__init__(
f"Failed after {attempts} attempts. Last error: {last_exception}"
)
def retry(
max_attempts: int = 3,
base_delay: float = 1.0,
max_delay: float = 60.0,
exponential_base: float = 2.0,
jitter: bool = True,
retry_on: tuple[Type[Exception], ...] = (Exception,),
exclude: tuple[Type[Exception], ...] = (),
on_retry: Callable[[Exception, int, float], None] | None = None,
on_give_up: Callable[[Exception, int], None] | None = None,
):
"""Decorator that retries a function on failure with exponential backoff.
Args:
max_attempts: Maximum number of attempts (including first try)
base_delay: Initial delay between retries in seconds
max_delay: Maximum delay cap
exponential_base: Multiplier for exponential growth
jitter: Add random jitter to prevent thundering herd
retry_on: Tuple of exception types to retry on
exclude: Tuple of exception types to NOT retry on
on_retry: Callback(exception, attempt, delay) called before each retry
on_give_up: Callback(exception, attempts) called when giving up
"""
def decorator(func: Callable[..., T]) -> Callable[..., T]:
if asyncio.iscoroutinefunction(func):
@functools.wraps(func)
async def async_wrapper(*args: Any, **kwargs: Any) -> T:
last_exc: Exception | None = None
for attempt in range(1, max_attempts + 1):
try:
return await func(*args, **kwargs)
except exclude:
raise
except retry_on as exc:
last_exc = exc
if attempt == max_attempts:
break
delay = _calculate_delay(attempt, base_delay, max_delay, exponential_base, jitter)
logger.warning(
"Attempt %d/%d for %s failed: %s. Retrying in %.2fs",
attempt, max_attempts, func.__name__, exc, delay
)
if on_retry:
on_retry(exc, attempt, delay)
await asyncio.sleep(delay)
if on_give_up and last_exc:
on_give_up(last_exc, max_attempts)
raise MaxRetriesExceeded(max_attempts, last_exc) # type: ignore
return async_wrapper # type: ignore
else:
@functools.wraps(func)
def sync_wrapper(*args: Any, **kwargs: Any) -> T:
last_exc: Exception | None = None
for attempt in range(1, max_attempts + 1):
try:
return func(*args, **kwargs)
except exclude:
raise
except retry_on as exc:
last_exc = exc
if attempt == max_attempts:
break
delay = _calculate_delay(attempt, base_delay, max_delay, exponential_base, jitter)
logger.warning(
"Attempt %d/%d for %s failed: %s. Retrying in %.2fs",
attempt, max_attempts, func.__name__, exc, delay
)
if on_retry:
on_retry(exc, attempt, delay)
time.sleep(delay)
if on_give_up and last_exc:
on_give_up(last_exc, max_attempts)
raise MaxRetriesExceeded(max_attempts, last_exc) # type: ignore
return sync_wrapper
return decorator
def _calculate_delay(
attempt: int,
base_delay: float,
max_delay: float,
exponential_base: float,
jitter: bool,
) -> float:
"""Calculate delay with exponential backoff and optional jitter."""
delay = base_delay * (exponential_base ** (attempt - 1))
delay = min(delay, max_delay)
if jitter:
delay = random.uniform(0, delay)
return delaytitle: "Configurable Retry Decorator" description: "A decorator for retrying failed operations with exponential backoff, jitter, exception filtering, and callback hooks." category: "Python" language: "python" tags: ["python", "decorator", "retry", "resilience", "production-ready"] createdAt: "2025-01-30" updatedAt: "2025-02-18"
Overview
A production retry decorator that handles both sync and async functions with exponential backoff, full jitter, exception filtering (retry only specific errors), and lifecycle callbacks for monitoring. Prevents thundering herd problems when services recover.
Code
@retry(max_attempts=3, retry_on=(TimeoutError,), base_delay=1.0)
async def unreliable_call():
...Notes
- Full jitter (
random.uniform(0, delay)) is recommended over equal jitter by AWS architecture docs - The
excludeparameter prevents retrying non-transient errors (validation, auth, 4xx responses) on_retryenables metrics emission for monitoring retry frequencyon_give_uptriggers alerting when a dependency is truly down- Automatically detects async vs sync and uses appropriate sleep mechanism