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.

Futures

Futures for dealing with asynchronous operations.

class google.api_core.future.Future

Bases: object

Future interface.

This interface is based on concurrent.futures.Future.

Abstract and helper bases for Future implementations.

class google.api_core.future.polling.PollingFuture(polling=<google.api_core.retry.retry_unary.Retry object>, **kwargs)

Bases: google.api_core.future.base.Future

A Future that needs to poll some service to check its status.

The done() method should be implemented by subclasses. The polling behavior will repeatedly call done until it returns True.

The actual polling logic is encapsulated in result() method. See documentation for that method for details on how polling works.

Note

Privacy here is intended to prevent the final class from overexposing, not to prevent subclasses from accessing methods.

Parameters

• polling (google.api_core.retry.Retry) – The configuration used for polling. This parameter controls how often done() is polled. If the timeout argument is specified in result() method it will override the polling.timeout property.

• retry (google.api_core.retry.Retry) – DEPRECATED use polling instead. If set, it will override polling parameter for backward compatibility.

add_done_callback(fn)

Add a callback to be executed when the operation is complete.

If the operation is not already complete, this will start a helper thread to poll for the status of the operation in the background.

Parameters

fn (Callable[Future]) – The callback to execute when the operation is complete.

abstract done(retry=None)

Checks to see if the operation is complete.

Parameters

retry (google.api_core.retry.Retry) – (Optional) How to retry the polling RPC (to not be confused with polling configuration. See the documentation for result() for details).

Returns

True if the operation is complete, False otherwise.

Return type

bool

exception(timeout=<object object>)

Get the exception from the operation, blocking if necessary.

See the documentation for the result() method for details on how this method operates, as both result and this method rely on the exact same polling logic. The only difference is that this method does not accept retry and polling arguments but relies on the default ones instead.

Parameters

• timeout (int) – How long to wait for the operation to complete.

• None (If) –

• indefinitely. (wait) –

Returns

The operation’s

error.

Return type

Optional[google.api_core.GoogleAPICallError]

result(timeout=<object object>, retry=None, polling=None)

Get the result of the operation.

This method will poll for operation status periodically, blocking if necessary. If you just want to make sure that this method does not block for more than X seconds and you do not care about the nitty-gritty of how this method operates, just call it with result(timeout=X). The other parameters are for advanced use only.

Every call to this method is controlled by the following three parameters, each of which has a specific, distinct role, even though all three may look very similar: timeout, retry and polling. In most cases users do not need to specify any custom values for any of these parameters and may simply rely on default ones instead.

If you choose to specify custom parameters, please make sure you’ve read the documentation below carefully.

First, please check google.api_core.retry.Retry class documentation for the proper definition of timeout and deadline terms and for the definition the three different types of timeouts. This class operates in terms of Retry Timeout and Polling Timeout. It does not let customizing RPC timeout and the user is expected to rely on default behavior for it.

The roles of each argument of this method are as follows:

timeout (int): (Optional) The Polling Timeout as defined in google.api_core.retry.Retry. If the operation does not complete within this timeout an exception will be thrown. This parameter affects neither Retry Timeout nor RPC Timeout.

retry (google.api_core.retry.Retry): (Optional) How to retry the polling RPC. The retry.timeout property of this parameter is the Retry Timeout as defined in google.api_core.retry.Retry. This parameter defines ONLY how the polling RPC call is retried (i.e. what to do if the RPC we used for polling returned an error). It does NOT define how the polling is done (i.e. how frequently and for how long to call the polling RPC); use the polling parameter for that. If a polling RPC throws and error and retrying it fails, the whole future fails with the corresponding exception. If you want to tune which server response error codes are not fatal for operation polling, use this parameter to control that (retry.predicate in particular).

polling (google.api_core.retry.Retry): (Optional) How often and for how long to call the polling RPC periodically (i.e. what to do if a polling rpc returned successfully but its returned result indicates that the long running operation is not completed yet, so we need to check it again at some point in future). This parameter does NOT define how to retry each individual polling RPC in case of an error; use the retry parameter for that. The polling.timeout of this parameter is Polling Timeout as defined in as defined in google.api_core.retry.Retry.

For each of the arguments, there are also default values in place, which will be used if a user does not specify their own. The default values for the three parameters are not to be confused with the default values for the corresponding arguments in this method (those serve as “not set” markers for the resolution logic).

If timeout is provided (i.e.``timeout is not _DEFAULT VALUE``; note the None value means “infinite timeout”), it will be used to control the actual Polling Timeout. Otherwise, the polling.timeout value will be used instead (see below for how the polling config itself gets resolved). In other words, this parameter effectively overrides the polling.timeout value if specified. This is so to preserve backward compatibility.

If retry is provided (i.e. retry is not None) it will be used to control retry behavior for the polling RPC and the retry.timeout will determine the Retry Timeout. If not provided, the polling RPC will be called with whichever default retry config was specified for the polling RPC at the moment of the construction of the polling RPC’s client. For example, if the polling RPC is operations_client.get_operation(), the retry parameter will be controlling its retry behavior (not polling behavior) and, if not specified, that specific method (operations_client.get_operation()) will be retried according to the default retry config provided during creation of operations_client client instead. This argument exists mainly for backward compatibility; users are very unlikely to ever need to set this parameter explicitly.

If polling is provided (i.e. polling is not None), it will be used to control the overall polling behavior and polling.timeout will control Polling Timeout unless it is overridden by timeout parameter as described above. If not provided, the``polling`` parameter specified during construction of this future (the polling argument in the constructor) will be used instead. Note: since the timeout argument may override polling.timeout value, this parameter should be viewed as coupled with the timeout parameter as described above.

Parameters

• timeout (int) – (Optional) How long (in seconds) to wait for the operation to complete. If None, wait indefinitely.

• retry (google.api_core.retry.Retry) – (Optional) How to retry the polling RPC. This defines ONLY how the polling RPC call is retried (i.e. what to do if the RPC we used for polling returned an error). It does NOT define how the polling is done (i.e. how frequently and for how long to call the polling RPC).

• polling (google.api_core.retry.Retry) – (Optional) How often and for how long to call polling RPC periodically. This parameter does NOT define how to retry each individual polling RPC call (use the retry parameter for that).

Returns

The Operation’s result.

Return type

google.protobuf.Message

Raises

google.api_core.GoogleAPICallError – If the operation errors or if the timeout is reached before the operation completes.

running()

True if the operation is currently running.

set_exception(exception)

Set the Future’s exception.

set_result(result)

Set the Future’s result.

AsyncIO implementation of the abstract base Future class.

class google.api_core.future.async_future.AsyncFuture(retry=<google.api_core.retry.retry_unary_async.AsyncRetry object>)

Bases: google.api_core.future.base.Future

A Future that polls peer service to self-update.

The done() method should be implemented by subclasses. The polling behavior will repeatedly call done until it returns True.

Note

Privacy here is intended to prevent the final class from overexposing, not to prevent subclasses from accessing methods.

Parameters

retry (google.api_core.retry.Retry) – The retry configuration used when polling. This can be used to control how often done() is polled. Regardless of the retry’s deadline, it will be overridden by the timeout argument to result().

add_done_callback(fn)

Add a callback to be executed when the operation is complete.

If the operation is completed, the callback will be scheduled onto the event loop. Otherwise, the callback will be stored and invoked when the future is done.

Parameters

fn (Callable[Future]) – The callback to execute when the operation is complete.

async done(retry=<google.api_core.retry.retry_unary_async.AsyncRetry object>)

Checks to see if the operation is complete.

Parameters

retry (google.api_core.retry.Retry) – (Optional) How to retry the RPC.

Returns

True if the operation is complete, False otherwise.

Return type

bool

async exception(timeout=None)

Get the exception from the operation.

Parameters

timeout (int) – How long to wait for the operation to complete. If None, wait indefinitely.

Returns

The operation’s

error.

Return type

Optional[google.api_core.GoogleAPICallError]

async result(timeout=None)

Get the result of the operation.

Parameters

timeout (int) – How long (in seconds) to wait for the operation to complete. If None, wait indefinitely.

Returns

The Operation’s result.

Return type

google.protobuf.Message

Raises

google.api_core.GoogleAPICallError – If the operation errors or if the timeout is reached before the operation completes.

async running()

True if the operation is currently running.

set_exception(exception)

Set the Future’s exception.

set_result(result)

Set the Future’s result.