Install & Compatibility
Where this runs
tested against v1.0.1 · 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.920 runs
installs and imports cleanly · install 0.0s · import 1.175s · 22MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.4s · import 1.117s · 22MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}")
Errors
Common errors & fixes
ImportError: No module named 'backoff_utils'
The `backoff-utils` package has not been installed in the current Python environment.
fixRun `pip install backoff-utils` to install the library.
TypeError: Can't instantiate abstract class BackoffStrategy with abstract methods time_to_sleep
Attempting to instantiate the abstract base class `BackoffStrategy` directly, which lacks a concrete implementation for `time_to_sleep`.
fixInstead 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
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.
fixModify the `on_failure` function signature to `def my_failure_handler(error, message, traceback): ...`.
Upgrade
Version history
1.0.1latest on PyPI · released Jul 11, 2020
Audit
Dependencies
validator-collectionrequiredProvides robust validation functionality, which backoff-utils relies on. Indirectly brings in 'jsonschema' and 'regex' (for Python 2.7).