Futures¶

Futures for dealing with asynchronous operations.

classgoogle.api_core.future.Future[source]¶

Bases:object

Future interface.

This interface is based onconcurrent.futures.Future.

Abstract and helper bases for Future implementations.

classgoogle.api_core.future.polling.PollingFuture(polling=<google.api_core.retry.retry_unary.Retryobject>,**kwargs)[source]¶

Bases:google.api_core.future.base.Future

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

Thedone() method should be implemented by subclasses. The pollingbehavior will repeatedly calldone until it returns True.

The actual polling logic is encapsulated inresult() method. Seedocumentation for that method for details on how polling works.

Note

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

Parameters

• polling (google.api_core.retry.Retry) – The configuration used for polling.This parameter controls how oftendone() is polled. If thetimeout argument is specified inresult() method it willoverride thepolling.timeout property.

• retry (google.api_core.retry.Retry) – DEPRECATED usepolling instead.If set, it will overridepolling parameter for backwardcompatibility.

add_done_callback(fn)[source]¶

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

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

Parameters

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

abstractdone(retry=None)[source]¶

Checks to see if the operation is complete.

Parameters

retry (google.api_core.retry.Retry) – (Optional) How to retry thepolling RPC (to not be confused with polling configuration. Seethe documentation forresult() for details).

Returns

True if the operation is complete, False otherwise.

Return type

bool

exception(timeout=<objectobject>)[source]¶

Get the exception from the operation, blocking if necessary.

See the documentation for theresult() method for details on howthis method operates, as bothresult and this method rely on theexact same polling logic. The only difference is that this method doesnot acceptretry andpolling arguments but relies on the default onesinstead.

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=<objectobject>,retry=None,polling=None)[source]¶

Get the result of the operation.

This method will poll for operation status periodically, blocking ifnecessary. If you just want to make sure that this method does not blockfor more than X seconds and you do not care about the nitty-gritty ofhow this method operates, just call it withresult(timeout=X). Theother parameters are for advanced use only.

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

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

First, please checkgoogle.api_core.retry.Retryclass documentation for the proper definition of timeout and deadlineterms and for the definition the three different types of timeouts.This class operates in terms of Retry Timeout and Polling Timeout. Itdoes not let customizing RPC timeout and the user is expected to rely ondefault behavior for it.

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

timeout (int): (Optional) The Polling Timeout as defined ingoogle.api_core.retry.Retry. If the operation does not completewithin this timeout an exception will be thrown. This parameter affectsneither Retry Timeout nor RPC Timeout.

retry (google.api_core.retry.Retry): (Optional) How to retry thepolling RPC. Theretry.timeout property of this parameter is theRetry Timeout as defined ingoogle.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). Itdoes NOT define how the polling is done (i.e. how frequently and forhow long to call the polling RPC); use thepolling parameter for that.If a polling RPC throws and error and retrying it fails, the wholefuture fails with the corresponding exception. If you want to tune whichserver response error codes are not fatal for operation polling, use thisparameter to control that (retry.predicate in particular).

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

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

Iftimeout is provided (i.e.``timeout is not _DEFAULT VALUE``; notetheNone value means “infinite timeout”), it will be used to controlthe actual Polling Timeout. Otherwise, thepolling.timeout valuewill be used instead (see below for how thepolling config itselfgets resolved). In other words, this parameter effectively overridesthepolling.timeout value if specified. This is so to preservebackward compatibility.

Ifretry is provided (i.e.retryisnotNone) it will be used tocontrol retry behavior for the polling RPC and theretry.timeoutwill determine the Retry Timeout. If not provided, thepolling RPC will be called with whichever default retry config wasspecified for the polling RPC at the moment of the construction of thepolling RPC’s client. For example, if the polling RPC isoperations_client.get_operation(), theretry parameter will becontrolling its retry behavior (not polling behavior) and, if notspecified, that specific method (operations_client.get_operation())will be retried according to the default retry config provided duringcreation ofoperations_client client instead. This argument existsmainly for backward compatibility; users are very unlikely to ever needto set this parameter explicitly.

Ifpolling is provided (i.e.pollingisnotNone), it will be usedto control the overall polling behavior andpolling.timeout willcontrol Polling Timeout unless it is overridden bytimeout parameteras described above. If not provided, the``polling`` parameter specifiedduring construction of this future (thepolling argument in theconstructor) will be used instead. Note: since thetimeout argument mayoverridepolling.timeout value, this parameter should be viewed ascoupled with thetimeout parameter as described above.

Parameters

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

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

• polling (google.api_core.retry.Retry) – (Optional) How often andfor how long to call polling RPC periodically. This parameterdoes NOT define how to retry each individual polling RPC call(use theretry 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()[source]¶

True if the operation is currently running.

set_exception(exception)[source]¶

Set the Future’s exception.

set_result(result)[source]¶

Set the Future’s result.

AsyncIO implementation of the abstract base Future class.

classgoogle.api_core.future.async_future.AsyncFuture(retry=<google.api_core.retry.retry_unary_async.AsyncRetryobject>)[source]¶

Bases:google.api_core.future.base.Future

A Future that polls peer service to self-update.

Thedone() method should be implemented by subclasses. The pollingbehavior will repeatedly calldone until it returns True.

Note

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

Parameters

retry (google.api_core.retry.Retry) – The retry configuration usedwhen polling. This can be used to control how oftendone()is polled. Regardless of the retry’sdeadline, it will beoverridden by thetimeout argument toresult().

add_done_callback(fn)[source]¶

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

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

Parameters

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

asyncdone(retry=<google.api_core.retry.retry_unary_async.AsyncRetryobject>)[source]¶

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

asyncexception(timeout=None)[source]¶

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]

asyncresult(timeout=None)[source]¶

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.

asyncrunning()[source]¶

True if the operation is currently running.

set_exception(exception)[source]¶

Set the Future’s exception.

set_result(result)[source]¶

Set the Future’s result.