Retry

Helpers for retrying functions with exponential back-off.

The Retry decorator can be used to retry functions that raise exceptions using exponential backoff. Because a exponential sleep algorithm is used, the retry is limited by a deadline. The deadline is the maxmimum amount of time a method can block. This is used instead of total number of retries because it is difficult to ascertain the amount of time a function can block when using total number of retries and exponential backoff.

By default, this decorator will retry transient API errors (see if_transient_error()). For example:

@retry.Retry()
def call_flaky_rpc():
    return client.flaky_rpc()

# Will retry flaky_rpc() if it raises transient API errors.
result = call_flaky_rpc()

You can pass a custom predicate to retry on different exceptions, such as waiting for an eventually consistent item to be available:

@retry.Retry(predicate=if_exception_type(exceptions.NotFound))
def check_if_exists():
    return client.does_thing_exist()

is_available = check_if_exists()

Some client library methods apply retry automatically. These methods can accept a retry parameter that allows you to configure the behavior:

my_retry = retry.Retry(deadline=60)
result = client.some_method(retry=my_retry)
class google.api_core.retry.Retry(predicate=<function if_exception_type.<locals>.if_exception_type_predicate>, initial=1.0, maximum=60.0, multiplier=2.0, deadline=120.0)[source]

Bases: object

Exponential retry decorator.

This class is a decorator used to add exponential back-off retry behavior to an RPC call.

Although the default behavior is to retry transient API errors, a different predicate can be provided to retry other exceptions.

Parameters

  • predicate (Callable[Exception]) – A callable that should return True if the given exception is retryable.

  • initial (float) – The minimum about of time to delay in seconds. This must be greater than 0.

  • maximum (float) – The maximum about of time to delay in seconds.

  • multiplier (float) – The multiplier applied to the delay.

  • deadline (float) – How long to keep retrying in seconds.

__call__(func, on_error=None)[source]

Wrap a callable with retry behavior.

Parameters

  • func (Callable) – The callable to add retry behavior to.

  • on_error (Callable) – A function to call while processing a retryable exception. Any error raised by this function will not be caught.

Returns

A callable that will invoke func with retry

behavior.

Return type

Callable

with_deadline(deadline)[source]

Return a copy of this retry with the given deadline.

Parameters

deadline (float) – How long to keep retrying.

Returns

A new retry instance with the given deadline.

Return type

Retry

with_delay(initial=None, maximum=None, multiplier=None)[source]

Return a copy of this retry with the given delay options.

Parameters

  • initial (float) – The minimum about of time to delay. This must be greater than 0.

  • maximum (float) – The maximum about of time to delay.

  • multiplier (float) – The multiplier applied to the delay.

Returns

A new retry instance with the given predicate.

Return type

Retry

with_predicate(predicate)[source]

Return a copy of this retry with the given predicate.

Parameters

predicate (Callable[Exception]) – A callable that should return True if the given exception is retryable.

Returns

A new retry instance with the given predicate.

Return type

Retry

google.api_core.retry.exponential_sleep_generator(initial, maximum, multiplier=2.0)[source]

Generates sleep intervals based on the exponential back-off algorithm.

This implements the Truncated Exponential Back-off algorithm.

Parameters

  • initial (float) – The minimum about of time to delay. This must be greater than 0.

  • maximum (float) – The maximum about of time to delay.

  • multiplier (float) – The multiplier applied to the delay.

Yields

float – successive sleep intervals.

google.api_core.retry.if_exception_type(*exception_types)[source]

Creates a predicate to check if the exception is of a given type.

Parameters

exception_types (Sequence[type()]) – The exception types to check for.

Returns

A predicate that returns True if the provided

exception is of the given type(s).

Return type

Callable[Exception]

google.api_core.retry.if_transient_error(exception)

A predicate that checks if an exception is a transient API error.

The following server errors are considered transient:

google.api_core.retry.retry_target(target, predicate, sleep_generator, deadline, on_error=None)[source]

Call a function and retry if it fails.

This is the lowest-level retry helper. Generally, you’ll use the higher-level retry helper Retry.

Parameters

  • target (Callable) – The function to call and retry. This must be a nullary function - apply arguments with functools.partial.

  • predicate (Callable[Exception]) – A callable used to determine if an exception raised by the target should be considered retryable. It should return True to retry or False otherwise.

  • sleep_generator (Iterable[float]) – An infinite iterator that determines how long to sleep between retries.

  • deadline (float) – How long to keep retrying the target.

  • on_error (Callable) – A function to call while processing a retryable exception. Any error raised by this function will not be caught.

Returns

the return value of the target function.

Return type

Any

Raises

  • google.api_core.RetryError – If the deadline is exceeded while retrying.

  • ValueError – If the sleep generator stops yielding values.

  • Exception – If the target raises a method that isn’t retryable.