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, on_error=None)[source]¶ Bases:
objectExponential 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
Trueif the given exception is retryable.initial (float) – The minimum a,out of time to delay in seconds. This must be greater than 0.
maximum (float) – The maximum amout of time to delay in seconds.
multiplier (float) – The multiplier applied to the delay.
deadline (float) – How long to keep retrying in seconds. The last sleep period is shortened as necessary, so that the last retry runs at
deadline(and not considerably beyond it).
-
__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[Exception]) – 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
funcwith retry behavior.
- A callable that will invoke
- Return type
Callable
-
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.
-
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.exceptions.InternalServerError- HTTP 500, gRPCINTERNAL(13)and its subclasses.
google.api_core.exceptions.TooManyRequests- HTTP 429google.api_core.exceptions.ResourceExhausted- gRPCRESOURCE_EXHAUSTED(8)
-
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. The last sleep period is shortened as necessary, so that the last retry runs at
deadline(and not considerably beyond it).on_error (Callable[Exception]) – 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.
Retry in AsyncIO¶
Helpers for retrying coroutine functions with exponential back-off.
The AsyncRetry decorator shares most functionality and behavior with
Retry, but supports coroutine functions. Please refer to description
of Retry for more details.
By default, this decorator will retry transient
API errors (see if_transient_error()). For example:
@retry_async.AsyncRetry()
async def call_flaky_rpc():
return await client.flaky_rpc()
# Will retry flaky_rpc() if it raises transient API errors.
result = await 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_async.AsyncRetry(predicate=retry_async.if_exception_type(exceptions.NotFound))
async def check_if_exists():
return await client.does_thing_exist()
is_available = await 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_async.AsyncRetry(deadline=60)
result = await client.some_method(retry=my_retry)
-
class
google.api_core.retry_async.AsyncRetry(predicate=<function if_exception_type.<locals>.if_exception_type_predicate>, initial=1.0, maximum=60.0, multiplier=2.0, deadline=120.0, on_error=None)[source]¶ Bases:
objectExponential retry decorator for async functions.
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
Trueif the given exception is retryable.initial (float) – The minimum a,out of time to delay in seconds. This must be greater than 0.
maximum (float) – The maximum amout of time to delay in seconds.
multiplier (float) – The multiplier applied to the delay.
deadline (float) – How long to keep retrying in seconds. The last sleep period is shortened as necessary, so that the last retry runs at
deadline(and not considerably beyond it).on_error (Callable[Exception]) – A function to call while processing a retryable exception. Any error raised by this function will not be caught.
-
__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[Exception]) – 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
funcwith retry behavior.
- A callable that will invoke
- 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
-
with_delay(initial=None, maximum=None, multiplier=None)[source]¶ Return a copy of this retry with the given delay options.
- Parameters
- Returns
A new retry instance with the given predicate.
- Return type
-
async
google.api_core.retry_async.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. The last sleep period is shortened as necessary, so that the last retry runs at
deadline(and not considerably beyond it).on_error (Callable[Exception]) – 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.
