Getting Started

Installation

To install Backoff-Utils, just execute:

$ pip install backoff-utils

Importing

Once installed, to import Backoff-Utils into your project you can use:

#: Import the backoff() function.
from backoff_utils import backoff

#: Import the @apply_backoff() decorator.
from backoff_utils import apply_backoff

#: Import backoff strategies.
from backoff_utils import strategies

Dependencies

By design, Backoff-Utils are designed to rely on minimal dependencies. The only dependency they have outside of the Python standard library is:

• validator-collection which provides for robust validation functionality.

  This library in turn has two external dependencies: * jsonschema, and * (when installed under Python 2.7) regex

  which is a drop-in replacement for Python 2.7’s (buggy) standard re module.

Hello, World

As a quick reference, here are some examples. Each of the examples below performs up to three attempts, applying an exponential backoff strategy with default configuration:

from backoff_utils import strategies

# Using a Function Call
from backoff_utils import backoff

def some_function(arg1, arg2, kwarg1 = None):
    # your code goes here
    pass

result = backoff(some_function,
                 args = ['value1', 'value2'],
                 kwargs = { 'kwarg1': 'value3' },
                 max_tries = 3,
                 max_delay = 3600,
                 strategy = strategies.Exponential)

# Using a Decorator
from backoff_utils import backoff

@apply_backoff(strategy = strategies.Exponential, max_tries = 3, max_delay = 3600)
def some_decorated_function(arg1, arg2, kwarg1 = None):
    # your code goes here
    pass

result = some_decorated_function('value1', 'value2', kwarg1 = 'value3')

---

Library Capabilities

There are two ways in which you can apply a backoff/retry strategy using the Backoff-Utils. Which approach you want to use will probably depend on your code and your code conventions:

• using a function call
• using a decorator

Both of these approaches support the following backoff strategies:

• Exponential
• Fibonaccial
• Fixed
• Linear
• Polynomial
• custom strategies

While the library’s defaults are usable out-of-the-box, your backoff strategy can be further tailored to your needs. The library also supports:

• random jitter
• argument-adjustment on retry
• selective exception capture
• chained backoff strategies
• failure handlers
• success handlers
• cut-off after a max delay
• cut-off after max tries
• scaling
• minimum delay

See also

While the Backoff-Utils are very straightforward to use, we recommend you review Using the Library to learn more about what it can do, and for a deep dive please see the API Reference .