Timeout¶
Decorators for applying timeout arguments to functions.
These decorators are used to wrap API methods to apply either a constant or exponential timeout argument.
For example, imagine an API method that can take a while to return results, such as one that might block until a resource is ready:
def is_thing_ready(timeout=None):
response = requests.get('https://example.com/is_thing_ready')
response.raise_for_status()
return response.json()
This module allows a function like this to be wrapped so that timeouts are automatically determined, for example:
timeout_ = timeout.ExponentialTimeout()
is_thing_ready_with_timeout = timeout_(is_thing_ready)
for n in range(10):
try:
is_thing_ready_with_timeout({'example': 'data'})
except:
pass
In this example the first call to is_thing_ready will have a relatively
small timeout (like 1 second). If the resource is available and the request
completes quickly, the loop exits. But, if the resource isn’t yet available
and the request times out, it’ll be retried - this time with a larger timeout.
In the broader context these decorators are typically combined with
google.api_core.retry to implement API methods with a signature that
matches api_method(request, timeout=None, retry=None).
-
class
google.api_core.timeout.ConstantTimeout(timeout=None)[source]¶ Bases:
objectA decorator that adds a constant timeout argument.
This is effectively equivalent to
functools.partial(func, timeout=timeout).- Parameters
timeout (Optional[float]) – the timeout (in seconds) to applied to the wrapped function. If None, the target function is expected to never timeout.
-
class
google.api_core.timeout.ExponentialTimeout(initial=5.0, maximum=30.0, multiplier=2.0, deadline=None)[source]¶ Bases:
objectA decorator that adds an exponentially increasing timeout argument.
This is useful if a function is called multiple times. Each time the function is called this decorator will calculate a new timeout parameter based on the the number of times the function has been called.
For example
- Parameters
initial (float) – The initial timeout to pass.
maximum (float) – The maximum timeout for any one call.
multiplier (float) – The multiplier applied to the timeout for each invocation.
deadline (Optional[float]) – The overall deadline across all invocations. This is used to prevent a very large calculated timeout from pushing the overall execution time over the deadline. This is especially useful in conjuction with
google.api_core.retry. IfNone, the timeouts will not be adjusted to accomodate an overall deadline.
-
__call__(func)[source]¶ Apply the timeout decorator.
- Parameters
func (Callable) – The function to apply the timeout argument to. This function must accept a timeout keyword argument.
- Returns
The wrapped function.
- Return type
Callable
