Skip to main content

Python functions and decorators for various backoff/retry strategies

Project description

Python Library for Backoff/Retry Strategies

Branch Unit Tests
latest Build Status (Travis CI) Code Coverage Status (Codecov) Documentation Status (ReadTheDocs)
v. 1.0.0 Build Status (Travis CI) Code Coverage Status (Codecov) Documentation Status (ReadTheDocs)
develop Build Status (Travis CI) Code Coverage Status (Codecov) Documentation Status (ReadTheDocs)

Backoff-Utils is a Python library that provides Python functions and decorators that apply various backoff / retry strategies to your Python function and method calls.

The library has a consistent syntax for easy use, and has been tested on Python 2.7, 3.4, 3.5, and 3.6.

COMPLETE DOCUMENTATION ON READTHEDOCS: http://backoff-utils.readthedocs.io/en/latest


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 one external dependency when installed under Python 2.7:

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

Hello, World Example

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')

Why Backoff-Utils?

Because now and again, stuff breaks.

Often, when making external API calls to third-party systems, something goes wrong. The internet might glitch. The API we’re calling might timeout. Gremlins might eat your packets. Any number of things can go wrong, and Murphy’s law tells us that they will.

Which is why we need backoff strategies. Basically, these are techniques that we can use to retry function calls after a given delay - and keep retrying them until either the function call works, or until we’ve tried so many times that we just give up and handle the error.

This library is meant to be an incredibly simple utility that provides a number of easy-to-use backoff strategies. Its core API is to expose:

  • the backoff() function, which lets you apply a given backoff strategy to any Python function call, and;
  • the @apply_backoff() decorator, which lets you decorate any function or method call so that a given backoff strategy is always applied when the decorated function/method is called.

Library Features

Supported Strategies

The library supports five of the most-common backoff strategies that we’ve come across:

  • Exponential
  • Fibonacci
  • Fixed
  • Linear
  • Polynomial

In addtion, you can also create your own custom strategies as well.

For more information about the backoff strategies supported, please see: Strategies Explained

Additional Features

In addition to the basic strategies, the library also supports:

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

For more information about the backoff strategies supported, please see: Using the Library


Feedback, Support, and Contributing

We’re happy to maintain this library going forward, and would always love to hear users’ feedback - especially if you’re running into issues.

Please report issues or questions on the project’s Github page

For more information on contributing to the Backoff-Utils library, please see: Contributor Guide

Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
backoff_utils-1.0.0-py2.py3-none-any.whl (12.1 kB) Copy SHA256 hash SHA256 Wheel py2.py3
backoff-utils-1.0.0.tar.gz (12.0 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page