API Reference¶

backoff() Function
@apply_backoff() Decorator
Strategies
- Exponential
- Fibonacci
- Fixed
- Linear
- Polynomial
Meta-classes
- BackoffStrategy

`backoff()` Function¶

backoff(to_execute, args=None, kwargs=None, strategy=None, retry_execute=None, retry_args=None, retry_kwargs=None, max_tries=None, max_delay=None, catch_exceptions=None, on_failure=None, on_success=None)[source]¶

Retry a function call multiple times with a delay per the strategy given.

Parameters:

to_execute (callable) – The function call that is to be attempted.
args (iterable / None.) –
The positional arguments to pass to the function on the first attempt.

If retry_args is None, will re-use these arguments on retry attempts as well.
kwargs (dict / None) –
The keyword arguments to pass to the function on the first attempt.

If retry_kwargs is None, will re-use these keyword arguments on retry attempts as well.
strategy (BackoffStrategy) –
The BackoffStrategy to use when determining the delay between retry attempts.

If None, defaults to Exponential.
retry_execute (callable / None) –
The function to call on retry attempts.

If None, will retry to_execute.

Defaults to None.
retry_args (iterable / None) –
The positional arguments to pass to the function on retry attempts.

If None, will re-use args.

Defaults to None.
retry_kwargs –
The keyword arguments to pass to the function on retry attempts.

If None, will re-use kwargs.

Defaults to None.
max_tries (int / None) –
The maximum number of times to attempt the call.

If None, will apply an environment variable BACKOFF_DEFAULT_TRIES. If that environment variable is not set, will apply a default of 3.
max_delay (None / int) – The maximum number of seconds to wait befor giving up once and for all. If None, will apply an environment variable BACKOFF_DEFAULT_DELAY if that environment variable is set. If it is not set, will not apply a max delay at all.

catch_exceptions (iterable of form [type(exception()), ...]) –

The type(exception) to catch and retry. If None, will catch all exceptions.

Defaults to None.

Caution

The iterable must contain one or more types of exception instances, and not class objects. For example:

# GOOD:
catch_exceptions = (type(ValueError()), type(TypeError()))

# BAD:
catch_exceptions = (type(ValueError), type(ValueError))

# BAD:
catch_exceptions = (ValueError, TypeError)

# BAD:
catch_exceptions = (ValueError(), TypeError())

on_failure (Exception / function / None) –
The exception or function to call when all retry attempts have failed.

If None, will raise the last-caught exception.

If an exception, will raise the exception with the same message as the last-caught exception.

If a function, will call the function and pass the last-raised exception, its message, and stacktrace to the function.

Defaults to None.
on_success (callable / None) –
The function to call when the operation was successful. The function receives the result of the to_execute or retry_execute function that was successful, and is called before that result is returned to whatever code called the backoff function. If None, will just return the result of to_execute or retry_execute without calling a handler.

Defaults to None.

Returns:

The result of the attempted function.

Example:

from backoff_utils import backoff

def some_function(arg1, arg2, kwarg1 = None):
    # Function does something
    pass

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

`@apply_backoff()` Decorator¶

apply_backoff(strategy=None, max_tries=None, max_delay=None, catch_exceptions=None, on_failure=None, on_success=None)[source]¶

Decorator that applies a backoff strategy to a decorated function/method.

Parameters:

strategy (BackoffStrategy) – The BackoffStrategy to use when determining the delay between retry attempts. If None, defaults to Exponential.
max_tries (int / None) –
The maximum number of times to attempt the call.

If None, will apply an environment variable BACKOFF_DEFAULT_TRIES. If that environment variable is not set, will apply a default of 3.
max_delay (None / class:int <python:int>) –
The maximum number of seconds to wait befor giving up once and for all.

If None, will apply an environment variable BACKOFF_DEFAULT_DELAY if that environment variable is set. If it is not set, will not apply a max delay at all.

catch_exceptions (iterable of form [type(exception()), ...]) –

The type(exception) to catch and retry. If None, will catch all exceptions.

Defaults to None.

Caution

The iterable must contain one or more types of exception instances, and not class objects. For example:

# GOOD:
catch_exceptions = (type(ValueError()), type(TypeError()))

# BAD:
catch_exceptions = (type(ValueError), type(ValueError))

# BAD:
catch_exceptions = (ValueError, TypeError)

# BAD:
catch_exceptions = (ValueError(), TypeError())

on_failure (Exception / function / None) –
The exception or function to call when all retry attempts have failed.

If None, will raise the last-caught Exception.

If an Exception, will raise the exception with the same message as the last-caught exception.

If a function, will call the function and pass the last-raised exception, its message, and stacktrace to the function.

Defaults to None.
on_success (callable / None) –
The function to call when the operation was successful.

The function receives the result of the decorated function, and is called before that result is returned to whatever code called the decorated function.

If None, will just return the result of the decorated function without calling a handler.

Defaults to None.

Example:

@apply_backoff(strategy = strategies.ExponentialBackoff,
               max_tries = 5,
               max_delay = 30)
def some_function(arg1, arg2, kwarg1 = None):
    pass

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

Strategies ¶

Exponential ¶

class Exponential(attempt=None, minimum=0.0, jitter=True, scale_factor=1.0, **kwargs)[source]¶

Implements the exponential backoff strategy.

The base delay time is calculated as:

\[2^a\]

where \(a\) is the number of the current attempt being made.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) – The minimum delay to apply. Defaults to 0.
jitter (bool) – If True, will add a random float to the delay. Defaults to True.
scale_factor (float) – A factor by which the time_to_sleep is multiplied to adjust its scale. Defaults to 1.0.

Class Attributes¶

IS_INSTANTIATED = False¶

Indicates whether the object is an instance of the strategy, or merely its class object.

Return type:	`bool`

Properties¶

attempt = None¶

The number of the attempt that the strategy is currently evaluating.

Return type:	`int` / `None`

minimum = 0.0¶

The minimum delay to apply, expressed in seconds.

Return type:	`float`

jitter = True¶

If True, will add a random float between 0 and 1 to the delay.

Return type:	`bool`

scale_factor = 1.0¶

A factor by which the time_to_sleep is multiplied to adjust its scale.

Return type:	`float`

time_to_sleep = 0.0 (read-only)¶

The base number of seconds to delay before allowing a retry.

Return type:	`float`

Class Methods¶

classmethod Exponential.delay(attempt, minimum=None, jitter=None, scale_factor=1.0)¶

Delay for a set period of time based on the attempt.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) –
The minimum number of seconds to delay.

If None, will apply either the strategy’s default or the instance’s configured property.
jitter (bool) –
If True, will add a random float to the delay.

If False, will not.

If None, will apply either the strategy’s default or the instance’s configured property.
scale_factor (float) –
A factor by which the time_to_sleep is multiplied to adjust its scale.

If None, will apply either the strategy’s default or the instance’s configured property.

Fibonacci ¶

class Fibonacci(attempt=None, minimum=0.0, jitter=True, scale_factor=1.0, **kwargs)[source]¶

Implements the fibonacci backoff strategy.

The base delay time is returned as the Fibonacci number corresponding to the current attempt.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) – The minimum delay to apply. Defaults to 0.
jitter (bool) – If True, will add a random float to the delay. Defaults to True.
scale_factor (float) – A factor by which the time_to_sleep is multiplied to adjust its scale. Defaults to 1.0.

Class Attributes¶

IS_INSTANTIATED = False

Indicates whether the object is an instance of the strategy, or merely its class object.

Return type:	`bool`

Properties¶

attempt = None

The number of the attempt that the strategy is currently evaluating.

Return type:	`int` / `None`

minimum = 0.0

The minimum delay to apply, expressed in seconds.

Return type:	`float`

jitter = True

If True, will add a random float between 0 and 1 to the delay.

Return type:	`bool`

scale_factor = 1.0

A factor by which the time_to_sleep is multiplied to adjust its scale.

Return type:	`float`

time_to_sleep = 0.0 (read-only)

The base number of seconds to delay before allowing a retry.

Return type:	`float`

Class Methods¶

classmethod Fibonacci.delay(attempt, minimum=None, jitter=None, scale_factor=1.0)¶

Delay for a set period of time based on the attempt.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) –
The minimum number of seconds to delay.

If None, will apply either the strategy’s default or the instance’s configured property.
jitter (bool) –
If True, will add a random float to the delay.

If False, will not.

If None, will apply either the strategy’s default or the instance’s configured property.
scale_factor (float) –
A factor by which the time_to_sleep is multiplied to adjust its scale.

If None, will apply either the strategy’s default or the instance’s configured property.

Fixed ¶

class Fixed(attempt=None, sequence=None, minimum=0, jitter=True, scale_factor=1.0, **kwargs)[source]¶

Implements the fixed backoff strategy.

The base delay time is calculated as a fixed value determined by the attempt number.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
sequence (iterable of numbers) – The sequence of base delay times to return based on the attempt number.
minimum (number) – The minimum delay to apply. Defaults to 0.
jitter (bool) – If True, will add a random float to the delay. Defaults to True.
scale_factor (float) –
A factor by which the time_to_sleep is multiplied to adjust its scale.

Defaults to 1.0.

Class Attributes¶

IS_INSTANTIATED = False

Indicates whether the object is an instance of the strategy, or merely its class object.

Return type:	`bool`

Properties¶

attempt = None

The number of the attempt that the strategy is currently evaluating.

Return type:	`int` / `None`

minimum = 0.0

The minimum delay to apply, expressed in seconds.

Return type:	`float`

jitter = True

If True, will add a random float between 0 and 1 to the delay.

Return type:	`bool`

scale_factor = 1.0

A factor by which the time_to_sleep is multiplied to adjust its scale.

Return type:	`float`

sequence = None¶

The sequence of base delay times (in seconds) to return based on the attempt number.

Note

If the number of attempts exceeds the length of the sequence, the last delay in the sequence will be repeated.

Tip

If no sequence is given, by default each base delay will be 1 second long.

Return type:	iterable of numbers / `None`

time_to_sleep = 0.0 (read-only)

The base number of seconds to delay before allowing a retry.

Return type:	`float`

Class Methods¶

classmethod Fixed.delay(attempt, minimum=None, jitter=None, scale_factor=1.0)¶

Delay for a set period of time based on the attempt.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) –
The minimum number of seconds to delay.

If None, will apply either the strategy’s default or the instance’s configured property.
jitter (bool) –
If True, will add a random float to the delay.

If False, will not.

If None, will apply either the strategy’s default or the instance’s configured property.
scale_factor (float) –
A factor by which the time_to_sleep is multiplied to adjust its scale.

If None, will apply either the strategy’s default or the instance’s configured property.

Linear ¶

class Linear(attempt=None, minimum=0.0, jitter=True, scale_factor=1.0, **kwargs)[source]¶

Implements the fixed backoff strategy.

The base delay time is equal to the attempt count.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) – The minimum delay to apply. Defaults to 0.
jitter (bool) – If True, will add a random float to the delay. Defaults to True.
scale_factor (float) – A factor by which the time_to_sleep is multiplied to adjust its scale. Defaults to 1.0.

Class Attributes¶

IS_INSTANTIATED = False

Indicates whether the object is an instance of the strategy, or merely its class object.

Return type:	`bool`

Properties¶

attempt = None

The number of the attempt that the strategy is currently evaluating.

Return type:	`int` / `None`

minimum = 0.0

The minimum delay to apply, expressed in seconds.

Return type:	`float`

jitter = True

If True, will add a random float between 0 and 1 to the delay.

Return type:	`bool`

scale_factor = 1.0

A factor by which the time_to_sleep is multiplied to adjust its scale.

Return type:	`float`

time_to_sleep = 0.0 (read-only)

The base number of seconds to delay before allowing a retry.

Return type:	`float`

Class Methods¶

classmethod Linear.delay(attempt, minimum=None, jitter=None, scale_factor=1.0)¶

Delay for a set period of time based on the attempt.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) –
The minimum number of seconds to delay.

If None, will apply either the strategy’s default or the instance’s configured property.
jitter (bool) –
If True, will add a random float to the delay.

If False, will not.

If None, will apply either the strategy’s default or the instance’s configured property.
scale_factor (float) –
A factor by which the time_to_sleep is multiplied to adjust its scale.

If None, will apply either the strategy’s default or the instance’s configured property.

Polynomial ¶

class Polynomial(attempt=None, exponent=1, minimum=0, jitter=True, scale_factor=1.0, **kwargs)[source]¶

Implements the polynomial backoff strategy.

The base delay time is calculated as:

\[a^e\]

where:

\(a\) is the number of attempts made

\(e\) is the exponent property

Parameters:

attempt (float) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
exponent (int) – The exponent to apply when calculating the base delay. Defaults to 1.
minimum (number) – The minimum delay to apply. Defaults to 0.
jitter (bool) – If True, will add a random float to the delay. Defaults to True.
scale_factor (float) – A factor by which the time_to_sleep is multiplied to adjust its scale. Defaults to 1.0.

Class Attributes¶

IS_INSTANTIATED = False

Indicates whether the object is an instance of the strategy, or merely its class object.

Return type:	`bool`

Properties¶

attempt = None

The number of the attempt that the strategy is currently evaluating.

Return type:	`int` / `None`

exponent = 1.0¶

The exponent to apply when calculating the base delay. Defaults to 1.0.

Return type:	`float`

minimum = 0.0

The minimum delay to apply, expressed in seconds.

Return type:	`float`

jitter = True

If True, will add a random float between 0 and 1 to the delay.

Return type:	`bool`

scale_factor = 1.0

A factor by which the time_to_sleep is multiplied to adjust its scale.

Return type:	`float`

time_to_sleep = 0.0 (read-only)

The base number of seconds to delay before allowing a retry.

Return type:	`float`

Class Methods¶

classmethod Polynomial.delay(attempt, minimum=None, jitter=None, scale_factor=1.0)¶

Delay for a set period of time based on the attempt.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) –
The minimum number of seconds to delay.

If None, will apply either the strategy’s default or the instance’s configured property.
jitter (bool) –
If True, will add a random float to the delay.

If False, will not.

If None, will apply either the strategy’s default or the instance’s configured property.
scale_factor (float) –
A factor by which the time_to_sleep is multiplied to adjust its scale.

If None, will apply either the strategy’s default or the instance’s configured property.

Meta-classes ¶

BackoffStrategy ¶

class BackoffStrategy(attempt=None, minimum=0.0, jitter=True, scale_factor=1.0, **kwargs)[source]¶

Abstract Base Class that defines the standard interface exposed by all backoff strategies supported by the library.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) – The minimum delay to apply. Defaults to 0.
jitter (bool) – If True, will add a random float to the delay. Defaults to True.
scale_factor (float) – A factor by which the time_to_sleep is multiplied to adjust its scale. Defaults to 1.0.

Class Attributes¶

IS_INSTANTIATED = False

Indicates whether the object is an instance of the strategy, or merely its class object.

Return type:	`bool`

Properties¶

attempt = None

The number of the attempt that the strategy is currently evaluating.

Return type:	`int` / `None`

minimum = 0.0

The minimum delay to apply, expressed in seconds.

Return type:	`float`

jitter = True

If True, will add a random float between 0 and 1 to the delay.

Return type:	`bool`

scale_factor = 1.0

A factor by which the time_to_sleep is multiplied to adjust its scale.

Return type:	`float`

time_to_sleep = 0.0 (read-only)

The base number of seconds to delay before allowing a retry.

Return type:	`float`

Class Methods¶

classmethod BackoffStrategy.delay(attempt, minimum=None, jitter=None, scale_factor=1.0)[source]¶

Delay for a set period of time based on the attempt.

Parameters:

attempt (int) – The number of the attempt that was last-attempted. This value is used by the strategy to determine the amount of time to delay before continuing.
minimum (number) –
The minimum number of seconds to delay.

If None, will apply either the strategy’s default or the instance’s configured property.
jitter (bool) –
If True, will add a random float to the delay.

If False, will not.

If None, will apply either the strategy’s default or the instance’s configured property.
scale_factor (float) –
A factor by which the time_to_sleep is multiplied to adjust its scale.

If None, will apply either the strategy’s default or the instance’s configured property.

API Reference¶

backoff() Function¶

@apply_backoff() Decorator¶

Class Attributes¶

Properties¶

Class Methods¶

Class Attributes¶

Properties¶

Class Methods¶

Class Attributes¶

Properties¶

Class Methods¶

Class Attributes¶

Properties¶

Class Methods¶

Class Attributes¶

Properties¶

Class Methods¶

Class Attributes¶

Properties¶

Class Methods¶

`backoff()` Function¶

`@apply_backoff()` Decorator¶