Timeout¶
Decorators for applying timeout arguments to functions.
These decorators are used to wrap API methods to apply either a Deadline-dependent (recommended), constant (DEPRECATED) or exponential (DEPRECATED) 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.
DEPRECATED: use
TimeToDeadlineTimeoutinstead.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.
DEPRECATED: the concept of incrementing timeout exponentially has been deprecated. Use
TimeToDeadlineTimeoutinstead.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 conjunction with
google.api_core.retry. IfNone, the timeouts will not be adjusted to accommodate 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
- class google.api_core.timeout.TimeToDeadlineTimeout(timeout=None, clock=<function utcnow>)[source]¶
Bases:
objectA decorator that decreases timeout set for an RPC based on how much time has left till its deadline. The deadline is calculated as
now + initial_timeoutwhen this decorator is first called for an rpc.In other words this decorator implements deadline semantics in terms of a sequence of decreasing timeouts t0 > t1 > t2 … tn >= 0.
- Parameters
timeout (Optional[float]) – the timeout (in seconds) to applied to the wrapped function. If None, the target function is expected to never timeout.
