As of January 1, 2020 this library no longer supports Python 2 on the latest released version. Library versions released prior to that date will continue to be available. For more information please visit Python 2 support on Google Cloud.

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

A decorator that adds a constant timeout argument.

DEPRECATED: use TimeToDeadlineTimeout instead.

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.

DEPRECATED: the concept of incrementing timeout exponentially has been deprecated. Use TimeToDeadlineTimeout instead.

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

with_deadline(deadline)[source]

Return a copy of this timeout with the given deadline.

Parameters

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

Returns

A new instance with the given deadline.

Return type

ExponentialTimeout

class google.api_core.timeout.TimeToDeadlineTimeout(timeout=None, clock=<function utcnow>)[source]

Bases: object

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

__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