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.

Long-Running Operations

Futures for long-running operations returned from Google Cloud APIs.

These futures can be used to synchronously wait for the result of a long-running operation using Operation.result():

operation = my_api_client.long_running_method()
result = operation.result()

Or asynchronously using callbacks and Operation.add_done_callback():

operation = my_api_client.long_running_method()

def my_callback(future):
    result = future.result()

operation.add_done_callback(my_callback)
class google.api_core.operation.Operation(operation, refresh, cancel, result_type, metadata_type=None, polling=<google.api_core.retry.retry_unary.Retry object>, **kwargs)[source]

Bases: google.api_core.future.polling.PollingFuture

A Future for interacting with a Google API Long-Running Operation.

Parameters

  • operation (google.longrunning.operations_pb2.Operation) – The initial operation.

  • refresh (Callable[[], Operation]) – A callable that returns the latest state of the operation.

  • cancel (Callable[[], None]) – A callable that tries to cancel the operation.

  • (func (metadata_type) – type): The protobuf type for the operation’s result.

  • (func – type): The protobuf type for the operation’s metadata.

  • 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 the result() method, it will override the polling.timeout property.

  • retry (google.api_core.retry.Retry) – DEPRECATED: use polling instead. If specified it will override polling parameter to maintain backward compatibility.

cancel()[source]

Attempt to cancel the operation.

Returns

True if the cancel RPC was made, False if the operation is

already complete.

Return type

bool

cancelled()[source]

True if the operation was cancelled.

classmethod deserialize(payload)[source]

Deserialize a google.longrunning.Operation protocol buffer.

Parameters

payload (bytes) – A serialized operation protocol buffer.

Returns

An Operation protobuf object.

Return type

Operation

done(retry=None)[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

property metadata

the current operation metadata.

Type

google.protobuf.Message

property operation

The current long-running operation.

Type

google.longrunning.Operation

google.api_core.operation.from_gapic(operation, operations_client, result_type, grpc_metadata=None, **kwargs)[source]

Create an operation future from a gapic client.

This interacts with the long-running operations service (specific to a given API) via a gapic client.

Parameters

  • operation (google.longrunning.operations_pb2.Operation) – The operation.

  • operations_client (google.api_core.operations_v1.OperationsClient) – The operations client.

  • result_type (type()) – The protobuf result type.

  • grpc_metadata (Optional[List[Tuple[str, str]]]) – Additional metadata to pass to the rpc.

  • kwargs – Keyword args passed into the Operation constructor.

Returns

The operation future to track the given

operation.

Return type

Operation

google.api_core.operation.from_grpc(operation, operations_stub, result_type, grpc_metadata=None, **kwargs)[source]

Create an operation future using a gRPC client.

This interacts with the long-running operations service (specific to a given API) via gRPC.

Parameters

  • operation (google.longrunning.operations_pb2.Operation) – The operation.

  • operations_stub (google.longrunning.operations_pb2.OperationsStub) – The operations stub.

  • result_type (type()) – The protobuf result type.

  • grpc_metadata (Optional[List[Tuple[str, str]]]) – Additional metadata to pass to the rpc.

  • kwargs – Keyword args passed into the Operation constructor.

Returns

The operation future to track the given

operation.

Return type

Operation

google.api_core.operation.from_http_json(operation, api_request, result_type, **kwargs)[source]

Create an operation future using a HTTP/JSON client.

This interacts with the long-running operations service (specific to a given API) via HTTP/JSON.

Parameters

  • operation (dict) – Operation as a dictionary.

  • api_request (Callable) – A callable used to make an API request. This should generally be google.cloud._http.Connection.api_request().

  • result_type (type()) – The protobuf result type.

  • kwargs – Keyword args passed into the Operation constructor.

Returns

The operation future to track the given

operation.

Return type

Operation

Long-Running Operations in AsyncIO

AsyncIO futures for long-running operations returned from Google Cloud APIs.

These futures can be used to await for the result of a long-running operation using AsyncOperation.result():

operation = my_api_client.long_running_method()
result = await operation.result()

Or asynchronously using callbacks and Operation.add_done_callback():

operation = my_api_client.long_running_method()

def my_callback(future):
    result = await future.result()

operation.add_done_callback(my_callback)
class google.api_core.operation_async.AsyncOperation(operation, refresh, cancel, result_type, metadata_type=None, retry=<google.api_core.retry.retry_unary_async.AsyncRetry object>)[source]

Bases: google.api_core.future.async_future.AsyncFuture

A Future for interacting with a Google API Long-Running Operation.

Parameters

  • operation (google.longrunning.operations_pb2.Operation) – The initial operation.

  • refresh (Callable[[], Operation]) – A callable that returns the latest state of the operation.

  • cancel (Callable[[], None]) – A callable that tries to cancel the operation.

  • (func (metadata_type) – type): The protobuf type for the operation’s result.

  • (func – type): The protobuf type for the operation’s metadata.

  • 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().

async cancel()[source]

Attempt to cancel the operation.

Returns

True if the cancel RPC was made, False if the operation is

already complete.

Return type

bool

async cancelled()[source]

True if the operation was cancelled.

classmethod deserialize(payload)[source]

Deserialize a google.longrunning.Operation protocol buffer.

Parameters

payload (bytes) – A serialized operation protocol buffer.

Returns

An Operation protobuf object.

Return type

Operation

async done(retry=<google.api_core.retry.retry_unary_async.AsyncRetry object>)[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

property metadata

the current operation metadata.

Type

google.protobuf.Message

property operation

The current long-running operation.

Type

google.longrunning.Operation

google.api_core.operation_async.from_gapic(operation, operations_client, result_type, grpc_metadata=None, **kwargs)[source]

Create an operation future from a gapic client.

This interacts with the long-running operations service (specific to a given API) via a gapic client.

Parameters

  • operation (google.longrunning.operations_pb2.Operation) – The operation.

  • operations_client (google.api_core.operations_v1.OperationsClient) – The operations client.

  • result_type (type()) – The protobuf result type.

  • grpc_metadata (Optional[List[Tuple[str, str]]]) – Additional metadata to pass to the rpc.

  • kwargs – Keyword args passed into the Operation constructor.

Returns

The operation future to track the given

operation.

Return type

Operation