Backoff-Utils

Common errors

• ImportError: No module named 'backoff_utils'

  cause The `backoff-utils` package has not been installed in the current Python environment.
  fix Run `pip install backoff-utils` to install the library.

• TypeError: Can't instantiate abstract class BackoffStrategy with abstract methods time_to_sleep

  cause Attempting to instantiate the abstract base class `BackoffStrategy` directly, which lacks a concrete implementation for `time_to_sleep`.
  fix Instead of `strategy=strategies.BackoffStrategy`, use a concrete strategy like `strategy=strategies.Exponential` or an instance of a concrete strategy like `strategy=strategies.Linear(interval=2)`.

• TypeError: my_failure_handler() takes 1 positional argument but 3 were given

  cause A custom `on_failure` callback function was provided to `backoff()` or `@apply_backoff()` with an incorrect signature. It must accept `error`, `message`, and `traceback` arguments.
  fix Modify the `on_failure` function signature to `def my_failure_handler(error, message, traceback): ...`.

Warnings

• gotcha The `BackoffStrategy` class is an abstract base class and cannot be instantiated directly. You must use one of its concrete subclasses (e.g., `strategies.Exponential`, `strategies.Linear`) or create your own custom strategy by subclassing it.
  Fix: Use a concrete strategy class like `strategy=strategies.Exponential` or `strategy=strategies.Linear()` instead of `strategy=strategies.BackoffStrategy`.
• gotcha When providing custom `on_failure` or `on_success` handlers, their signatures must match specific requirements. An `on_failure` handler must accept three positional arguments: `error`, `message`, and `traceback`. An `on_success` handler must accept a single `result` argument.
  Fix: Ensure `on_failure(error, message, traceback)` and `on_success(result)` for custom handler functions to avoid `TypeError`.
• gotcha If `max_tries` or `max_delay` are not explicitly provided, the library will attempt to read default values from the `BACKOFF_DEFAULT_TRIES` and `BACKOFF_DEFAULT_DELAY` environment variables, respectively. If these are also not set, `max_tries` defaults to 3, and `max_delay` defaults to infinite (no maximum).
  Fix: Explicitly set `max_tries` and `max_delay` parameters when calling `backoff()` or decorating with `@apply_backoff()` for predictable behavior, rather than relying on environment variables or implicit defaults.

Install

• pip install backoff-utils Install latest version

Imports

• backoff

  from backoff_utils import backoff

  For applying backoff strategies as a function call.
• apply_backoff

  from backoff_utils import apply_backoff

  For applying backoff strategies as a decorator.
• strategies

  from backoff_utils import strategies

  Contains predefined backoff strategies like Exponential, Linear, etc.

Quickstart

This quickstart demonstrates both the `backoff()` function and the `@apply_backoff()` decorator. The first example uses `backoff()` to retry an `unreliable_function` with an exponential strategy, catching `ConnectionError`. The second example uses `@apply_backoff()` as a decorator for `another_unreliable_function` with a linear strategy, catching `IOError`. Both include `max_tries` to limit attempts.

import random
import time
from backoff_utils import backoff, apply_backoff, strategies

# Example 1: Using backoff() as a function call
print("\n--- Function Call Example ---")
def unreliable_function(attempt_num):
    print(f"Attempting function (call #{attempt_num})...")
    if random.random() < 0.7: # 70% chance of failure
        raise ConnectionError("Simulated network error")
    return f"Success on attempt {attempt_num}!"

try:
    result_func = backoff(
        unreliable_function, 
        args=[0], # Placeholder, actual attempt num passed internally
        max_tries=5, 
        max_delay=60, 
        strategy=strategies.Exponential,
        catch_exceptions=(ConnectionError,)
    )
    print(result_func)
except ConnectionError as e:
    print(f"Function failed after multiple retries: {e}")

# Example 2: Using @apply_backoff() as a decorator
print("\n--- Decorator Example ---")
@apply_backoff(
    strategy=strategies.Linear(interval=1), 
    max_tries=4, 
    catch_exceptions=(IOError,)
)
def another_unreliable_function(data):
    print(f"Processing '{data}' (decorated function)...")
    if random.random() < 0.5: # 50% chance of failure
        raise IOError("Simulated disk write error")
    return f"Successfully processed '{data}'"

try:
    result_decorator = another_unreliable_function("important data")
    print(result_decorator)
except IOError as e:
    print(f"Decorated function failed after multiple retries: {e}")