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 delay

title: "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 exclude parameter prevents retrying non-transient errors (validation, auth, 4xx responses)
  • on_retry enables metrics emission for monitoring retry frequency
  • on_give_up triggers alerting when a dependency is truly down
  • Automatically detects async vs sync and uses appropriate sleep mechanism