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: object

A 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.

__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.ExponentialTimeout(initial=5.0, maximum=30.0, multiplier=2.0, deadline=None)[source]

Bases: object

A 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. If None, 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

with_deadline(deadline)[source]

Return a copy of this teimout with the given deadline.

Parameters

deadline (float) – The overall deadline across all invocations.

Returns

A new instance with the given deadline.

Return type

ExponentialTimeout