Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1# Copyright 2020 Google LLC
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
15"""Helpers for retrying coroutine functions with exponential back-off.
17The :class:`AsyncRetry` decorator shares most functionality and behavior with
18:class:`Retry`, but supports coroutine functions. Please refer to description
19of :class:`Retry` for more details.
21By default, this decorator will retry transient
22API errors (see :func:`if_transient_error`). For example:
24.. code-block:: python
26 @retry_async.AsyncRetry()
27 async def call_flaky_rpc():
28 return await client.flaky_rpc()
30 # Will retry flaky_rpc() if it raises transient API errors.
31 result = await call_flaky_rpc()
33You can pass a custom predicate to retry on different exceptions, such as
34waiting for an eventually consistent item to be available:
36.. code-block:: python
38 @retry_async.AsyncRetry(predicate=retry_async.if_exception_type(exceptions.NotFound))
39 async def check_if_exists():
40 return await client.does_thing_exist()
42 is_available = await check_if_exists()
44Some client library methods apply retry automatically. These methods can accept
45a ``retry`` parameter that allows you to configure the behavior:
47.. code-block:: python
49 my_retry = retry_async.AsyncRetry(timeout=60)
50 result = await client.some_method(retry=my_retry)
52"""
54from __future__ import annotations
56import asyncio
57import functools
58import time
59from typing import (
60 TYPE_CHECKING,
61 Any,
62 Awaitable,
63 Callable,
64 Iterable,
65 TypeVar,
66)
68# for backwards compatibility, expose helpers in this module
69from google.api_core.retry.retry_base import ( # noqa: F401
70 RetryFailureReason,
71 _BaseRetry,
72 _retry_error_helper,
73 build_retry_error,
74 exponential_sleep_generator,
75 if_exception_type,
76 if_transient_error,
77)
79if TYPE_CHECKING:
80 import sys
82 if sys.version_info >= (3, 10):
83 from typing import ParamSpec
84 else:
85 from typing_extensions import ParamSpec
87 _P = ParamSpec("_P") # target function call parameters
88 _R = TypeVar("_R") # target function returned value
90_DEFAULT_INITIAL_DELAY = 1.0 # seconds
91_DEFAULT_MAXIMUM_DELAY = 60.0 # seconds
92_DEFAULT_DELAY_MULTIPLIER = 2.0
93_DEFAULT_DEADLINE = 60.0 * 2.0 # seconds
94_DEFAULT_TIMEOUT = 60.0 * 2.0 # seconds
97async def retry_target(
98 target: Callable[[], Awaitable[_R]],
99 predicate: Callable[[Exception], bool],
100 sleep_generator: Iterable[float],
101 timeout: float | None = None,
102 on_error: Callable[[Exception], None] | None = None,
103 exception_factory: Callable[
104 [list[Exception], RetryFailureReason, float | None],
105 tuple[Exception, Exception | None],
106 ] = build_retry_error,
107 **kwargs,
108):
109 """Await a coroutine and retry if it fails.
111 This is the lowest-level retry helper. Generally, you'll use the
112 higher-level retry helper :class:`Retry`.
114 Args:
115 target(Callable[[], Any]): The function to call and retry. This must be a
116 nullary function - apply arguments with `functools.partial`.
117 predicate (Callable[Exception]): A callable used to determine if an
118 exception raised by the target should be considered retryable.
119 It should return True to retry or False otherwise.
120 sleep_generator (Iterable[float]): An infinite iterator that determines
121 how long to sleep between retries.
122 timeout (Optional[float]): How long to keep retrying the target, in seconds.
123 Note: timeout is only checked before initiating a retry, so the target may
124 run past the timeout value as long as it is healthy.
125 on_error (Optional[Callable[Exception]]): If given, the on_error
126 callback will be called with each retryable exception raised by the
127 target. Any error raised by this function will *not* be caught.
128 exception_factory: A function that is called when the retryable reaches
129 a terminal failure state, used to construct an exception to be raised.
130 It takes a list of all exceptions encountered, a retry.RetryFailureReason
131 enum indicating the failure cause, and the original timeout value
132 as arguments. It should return a tuple of the exception to be raised,
133 along with the cause exception if any. The default implementation will raise
134 a RetryError on timeout, or the last exception encountered otherwise.
135 deadline (float): DEPRECATED use ``timeout`` instead. For backward
136 compatibility, if set it will override the ``timeout`` parameter.
138 Returns:
139 Any: the return value of the target function.
141 Raises:
142 ValueError: If the sleep generator stops yielding values.
143 Exception: a custom exception specified by the exception_factory if provided.
144 If no exception_factory is provided:
145 google.api_core.RetryError: If the timeout is exceeded while retrying.
146 Exception: If the target raises an error that isn't retryable.
147 """
149 timeout = kwargs.get("deadline", timeout)
151 deadline = time.monotonic() + timeout if timeout is not None else None
152 error_list: list[Exception] = []
153 sleep_iter = iter(sleep_generator)
155 # continue trying until an attempt completes, or a terminal exception is raised in _retry_error_helper
156 # TODO: support max_attempts argument: https://github.com/googleapis/python-api-core/issues/535
157 while True:
158 try:
159 return await target()
160 # pylint: disable=broad-except
161 # This function explicitly must deal with broad exceptions.
162 except Exception as exc:
163 # defer to shared logic for handling errors
164 next_sleep = _retry_error_helper(
165 exc,
166 deadline,
167 sleep_iter,
168 error_list,
169 predicate,
170 on_error,
171 exception_factory,
172 timeout,
173 )
174 # if exception not raised, sleep before next attempt
175 await asyncio.sleep(next_sleep)
178class AsyncRetry(_BaseRetry):
179 """Exponential retry decorator for async coroutines.
181 This class is a decorator used to add exponential back-off retry behavior
182 to an RPC call.
184 Although the default behavior is to retry transient API errors, a
185 different predicate can be provided to retry other exceptions.
187 Args:
188 predicate (Callable[Exception]): A callable that should return ``True``
189 if the given exception is retryable.
190 initial (float): The minimum amount of time to delay in seconds. This
191 must be greater than 0.
192 maximum (float): The maximum amount of time to delay in seconds.
193 multiplier (float): The multiplier applied to the delay.
194 timeout (Optional[float]): How long to keep retrying in seconds.
195 Note: timeout is only checked before initiating a retry, so the target may
196 run past the timeout value as long as it is healthy.
197 on_error (Optional[Callable[Exception]]): A function to call while processing
198 a retryable exception. Any error raised by this function will
199 *not* be caught.
200 deadline (float): DEPRECATED use ``timeout`` instead. If set it will
201 override ``timeout`` parameter.
202 """
204 def __call__(
205 self,
206 func: Callable[..., Awaitable[_R]],
207 on_error: Callable[[Exception], Any] | None = None,
208 ) -> Callable[_P, Awaitable[_R]]:
209 """Wrap a callable with retry behavior.
211 Args:
212 func (Callable): The callable or stream to add retry behavior to.
213 on_error (Optional[Callable[Exception]]): If given, the
214 on_error callback will be called with each retryable exception
215 raised by the wrapped function. Any error raised by this
216 function will *not* be caught. If on_error was specified in the
217 constructor, this value will be ignored.
219 Returns:
220 Callable: A callable that will invoke ``func`` with retry
221 behavior.
222 """
223 if self._on_error is not None:
224 on_error = self._on_error
226 @functools.wraps(func)
227 async def retry_wrapped_func(*args: _P.args, **kwargs: _P.kwargs) -> _R:
228 """A wrapper that calls target function with retry."""
229 sleep_generator = exponential_sleep_generator(
230 self._initial, self._maximum, multiplier=self._multiplier
231 )
232 return await retry_target(
233 functools.partial(func, *args, **kwargs),
234 predicate=self._predicate,
235 sleep_generator=sleep_generator,
236 timeout=self._timeout,
237 on_error=on_error,
238 )
240 return retry_wrapped_func