Reference

Utilities for polling, retrying, and exception handling.

exception poll.CircuitBrokenError(message='', time_remaining=0)

Exception to indicate that the operation was not carried out because the circuit is broken.

poll.circuitbreaker(ex, threshold, reset_timeout, on_error=<function <lambda>>)

Decorator for functions which should ‘back off’ using the Circuit Breaker pattern: http://martinfowler.com/bliki/CircuitBreaker.html

This implementation of Circuit Breaker uses a ‘leaky bucket’ form of failure counting. For example, if threshold is 3 and reset_timeout is 60, then the circuit will be broken if the call fails three times within a sixty-second period. The circuit breaker is lenient towards intermittent failures.

Parameters:
  • ex (class or iterable) – The class of the exception to catch, or an iterable of classes.
  • threshold (int) – The number of times a failure can occur before the circuit is broken.
  • reset_timeout (float) – The length of time, in seconds, that a broken circuit should remain broken.
  • on_error (function) –

    A function to be called when the decorated function throws an exception.

    If on_error() takes no parameters, it will be called without arguments.

    If on_error(exception) takes one parameter, it will be called with the exception that was raised.

    A typical use of on_error would be to log the exception.
Returns:

The final return value of the function f.
Raises:

CircuitBrokenError – The operation was not carried out because the circuit is broken.
poll.exec_(f, ex, until, times=3, timeout=15, interval=1, on_error=<function <lambda>>, *args, **kwargs)

General function for polling, retrying, and handling errors.

Parameters:
  • f (function) – The function to retry
  • ex (class or iterable) – The class of the exception to catch, or an iterable of classes
  • until (function) – The success condition. until should be a function; it will be called with the return value of the function. until(x) should return True if the operation was successful (and retrying should stop) and False if retrying should continue.
  • times (int) – The maximum number of times to retry
  • interval (float) – How long to sleep in between attempts in seconds
  • on_error (function) –

    A function to be called when f throws an exception.

    If on_error() takes no parameters, it will be called without arguments.

    If on_error(exception) takes one parameter, it will be called with the exception that was raised.

    If on_error(exception, retry_count) takes two parameters, it will be called with the exception that was raised and the number of previous attempts (starting at 0).

    A typical use of on_error would be to log the exception.

Any other arguments are forwarded to f.

Returns:The final return value of the function f.
Raises:TimeoutError – The call did not succeed within the specified timeout.
poll.poll(until, timeout=15, interval=1)

Decorator for functions that should be repeated until a condition or a timeout.

Parameters:
  • until (function) – The success condition. until should be a function; it will be called with the return value of the function. until should return True if the operation was successful (and retrying should stop) and False if retrying should continue.
  • timeout (float) – How long to keep retrying the operation in seconds
  • interval (float) – How long to sleep between attempts in seconds
Returns:

The final return value of the decorated function
Raises:

TimeoutError – The condition did not become true within the specified timeout.
poll.poll_(f, until, timeout=15, interval=1, *args, **kwargs)

Repeatedly call a function until a condition becomes true or a timeout expires.

Parameters:
  • f (function) – The function to poll
  • until (function) – The success condition. until should be a function; it will be called with the return value of the function. until should return True if the operation was successful (and retrying should stop) and False if retrying should continue.
  • timeout (float) – How long to keep retrying the operation in seconds
  • interval (float) – How long to sleep in between attempts in seconds

Any other arguments are forwarded to f.

Returns:The final return value of the function f.
Raises:TimeoutError – The condition did not become true within the specified timeout.
poll.retry(ex, times=3, interval=1, on_error=<function <lambda>>)

Decorator for functions that should be retried upon error.

Parameters:
  • ex (class or iterable) – The class of the exception to catch, or an iterable of classes
  • times (int) – The maximum number of times to retry
  • interval (float) – How long to sleep in between attempts in seconds
  • on_error (function) –

    A function to be called when the decorated function throws an exception.

    If on_error() takes no parameters, it will be called without arguments.

    If on_error(exception) takes one parameter, it will be called with the exception that was raised.

    If on_error(exception, retry_count) takes two parameters, it will be called with the exception that was raised and the number of previous attempts (starting at 0).

    A typical use of on_error would be to log the exception.
Returns:

The return value of the decorated function
Raises:

TimeoutError – The function did not succeed within the specified timeout.
poll.retry_(f, ex, times=3, interval=1, on_error=<function <lambda>>, *args, **kwargs)

Call a function and try again if it throws a specified exception.

Parameters:
  • f (funciton) – The function to retry
  • ex (class or iterable) – The class of the exception to catch, or an iterable of classes
  • times (int) – The maximum number of times to retry
  • interval (float) – How long to sleep in between attempts in seconds
  • on_error (function) –

    A function to be called when f throws an exception.

    If on_error() takes no parameters, it will be called without arguments.

    If on_error(exception) takes one parameter, it will be called with the exception that was raised.

    If on_error(exception, retry_count) takes two parameters, it will be called with the exception that was raised and the number of previous attempts (starting at 0).

    A typical use of on_error would be to log the exception.

Any other arguments are forwarded to f.

Returns:The final return value of the function f.
Raises:TimeoutError – The function did not succeed within the specified timeout.