{"id":7038,"library":"backoff-utils","title":"Backoff-Utils","description":"Backoff-Utils is a Python library that provides functions and decorators for various backoff/retry strategies to Python function and method calls. It offers a consistent syntax and has been tested across a broad range of Python versions, including 2.7, 3.4, 3.5, 3.6, 3.7, and 3.8. The current version is 1.0.1, with recent updates focusing on documentation clarity and dependency management.","status":"active","version":"1.0.1","language":"en","source_language":"en","source_url":"https://github.com/insightindustry/backoff-utils/","tags":["retry","backoff","resilience","utilities","decorator","fault-tolerance"],"install":[{"cmd":"pip install backoff-utils","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Provides robust validation functionality, which backoff-utils relies on. Indirectly brings in 'jsonschema' and 'regex' (for Python 2.7).","package":"validator-collection","optional":false}],"imports":[{"note":"For applying backoff strategies as a function call.","symbol":"backoff","correct":"from backoff_utils import backoff"},{"note":"For applying backoff strategies as a decorator.","symbol":"apply_backoff","correct":"from backoff_utils import apply_backoff"},{"note":"Contains predefined backoff strategies like Exponential, Linear, etc.","symbol":"strategies","correct":"from backoff_utils import strategies"}],"quickstart":{"code":"import random\nimport time\nfrom backoff_utils import backoff, apply_backoff, strategies\n\n# Example 1: Using backoff() as a function call\nprint(\"\\n--- Function Call Example ---\")\ndef unreliable_function(attempt_num):\n    print(f\"Attempting function (call #{attempt_num})...\")\n    if random.random() < 0.7: # 70% chance of failure\n        raise ConnectionError(\"Simulated network error\")\n    return f\"Success on attempt {attempt_num}!\"\n\ntry:\n    result_func = backoff(\n        unreliable_function, \n        args=[0], # Placeholder, actual attempt num passed internally\n        max_tries=5, \n        max_delay=60, \n        strategy=strategies.Exponential,\n        catch_exceptions=(ConnectionError,)\n    )\n    print(result_func)\nexcept ConnectionError as e:\n    print(f\"Function failed after multiple retries: {e}\")\n\n# Example 2: Using @apply_backoff() as a decorator\nprint(\"\\n--- Decorator Example ---\")\n@apply_backoff(\n    strategy=strategies.Linear(interval=1), \n    max_tries=4, \n    catch_exceptions=(IOError,)\n)\ndef another_unreliable_function(data):\n    print(f\"Processing '{data}' (decorated function)...\")\n    if random.random() < 0.5: # 50% chance of failure\n        raise IOError(\"Simulated disk write error\")\n    return f\"Successfully processed '{data}'\"\n\ntry:\n    result_decorator = another_unreliable_function(\"important data\")\n    print(result_decorator)\nexcept IOError as e:\n    print(f\"Decorated function failed after multiple retries: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Use a concrete strategy class like `strategy=strategies.Exponential` or `strategy=strategies.Linear()` instead of `strategy=strategies.BackoffStrategy`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `on_failure(error, message, traceback)` and `on_success(result)` for custom handler functions to avoid `TypeError`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install backoff-utils` to install the library.","cause":"The `backoff-utils` package has not been installed in the current Python environment.","error":"ImportError: No module named 'backoff_utils'"},{"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)`.","cause":"Attempting to instantiate the abstract base class `BackoffStrategy` directly, which lacks a concrete implementation for `time_to_sleep`.","error":"TypeError: Can't instantiate abstract class BackoffStrategy with abstract methods time_to_sleep"},{"fix":"Modify the `on_failure` function signature to `def my_failure_handler(error, message, traceback): ...`.","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.","error":"TypeError: my_failure_handler() takes 1 positional argument but 3 were given"}]}