Skip to content

Commit 3a95612

Browse files
author
Jon Wayne Parrott
authored
Add google.api.core.operations_v1 (googleapis#4081)
1 parent 400536d commit 3a95612

7 files changed

Lines changed: 500 additions & 2 deletions

File tree

‎core/google/api/core/operation.py‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@ def _cancel_http(api_request, operation_name):
187187

188188

189189
def from_http_json(operation, api_request, result_type, **kwargs):
190-
"""Create an operation future from using a HTTP/JSON client.
190+
"""Create an operation future using a HTTP/JSON client.
191191
192192
This interacts with the long-running operations `service`_ (specific
193193
to a given API) vis `HTTP/JSON`_.
@@ -243,7 +243,7 @@ def _cancel_grpc(operations_stub, operation_name):
243243

244244

245245
def from_grpc(operation, operations_stub, result_type, **kwargs):
246-
"""Create an operation future from using a gRPC client.
246+
"""Create an operation future using a gRPC client.
247247
248248
This interacts with the long-running operations `service`_ (specific
249249
to a given API) via gRPC.
@@ -267,3 +267,30 @@ def from_grpc(operation, operations_stub, result_type, **kwargs):
267267
cancel = functools.partial(
268268
_cancel_grpc, operations_stub, operation.name)
269269
return Operation(operation, refresh, cancel, result_type, **kwargs)
270+
271+
272+
def from_gapic(operation, operations_client, result_type, **kwargs):
273+
"""Create an operation future from a gapic client.
274+
275+
This interacts with the long-running operations `service`_ (specific
276+
to a given API) via a gapic client.
277+
278+
.. _service: https://github.com/googleapis/googleapis/blob/\
279+
050400df0fdb16f63b63e9dee53819044bffc857/\
280+
google/longrunning/operations.proto#L38
281+
282+
Args:
283+
operation (google.longrunning.operations_pb2.Operation): The operation.
284+
operations_client (google.api.core.operations_v1.OperationsClient):
285+
The operations client.
286+
result_type (type): The protobuf result type.
287+
kwargs: Keyword args passed into the :class:`Operation` constructor.
288+
289+
Returns:
290+
Operation: The operation future to track the given operation.
291+
"""
292+
refresh = functools.partial(
293+
operations_client.get_operation, operation.name)
294+
cancel = functools.partial(
295+
operations_client.cancel_operation, operation.name)
296+
return Operation(operation, refresh, cancel, result_type, **kwargs)

‎core/google/api/core/operations_v1/__init__.py‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Copyright 2017 Google Inc.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""Package for interacting with the google.longrunning.operations meta-API."""
16+
17+
from google.api.core.operations_v1.operations_client import OperationsClient
18+
19+
__all__ = [
20+
'OperationsClient'
21+
]

‎core/google/api/core/operations_v1/operations_client.py‎

Lines changed: 271 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,271 @@
1+
# Copyright 2017 Google Inc.
2+
#
3+
# Licensed under the Apache License, Version 2.0 (the "License");
4+
# you may not use this file except in compliance with the License.
5+
# You may obtain a copy of the License at
6+
#
7+
# http://www.apache.org/licenses/LICENSE-2.0
8+
#
9+
# Unless required by applicable law or agreed to in writing, software
10+
# distributed under the License is distributed on an "AS IS" BASIS,
11+
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
# See the License for the specific language governing permissions and
13+
# limitations under the License.
14+
15+
"""A client for the google.longrunning.operations meta-API.
16+
17+
This is a client that deals with long-running operations that follow the
18+
pattern outlined by the `Google API Style Guide`_.
19+
20+
When an API method normally takes long time to complete, it can be designed to
21+
return ``Operation`` to the client, and the client can use this interface to
22+
receive the real response asynchronously by polling the operation resource to
23+
receive the response.
24+
25+
It is not a separate service, but rather an interface implemented by a larger
26+
service. The protocol-level definition is available at
27+
`google/longrunning/operations.proto`_. Typically, this will be constructed
28+
automatically by another client class to deal with operations.
29+
30+
.. _Google API Style Guide:
31+
https://cloud.google.com/apis/design/design_pattern
32+
s#long_running_operations
33+
.. _google/longrunning/operations.proto:
34+
https://github.com/googleapis/googleapis/blob/master/google/longrunning
35+
/operations.proto
36+
"""
37+
38+
from google.api.core import gapic_v1
39+
from google.api.core.operations_v1 import operations_client_config
40+
from google.longrunning import operations_pb2
41+
42+
43+
class OperationsClient(object):
44+
"""Client for interacting with long-running operations within a service.
45+
46+
Args:
47+
channel (grpc.Channel): The gRPC channel associated with the service
48+
that implements the ``google.longrunning.operations`` interface.
49+
client_config (dict):
50+
A dictionary of call options for each method. If not specified
51+
the default configuration is used.
52+
"""
53+
54+
def __init__(self, channel, client_config=operations_client_config.config):
55+
# Create the gRPC client stub.
56+
self.operations_stub = operations_pb2.OperationsStub(channel)
57+
58+
# Create all wrapped methods using the interface configuration.
59+
# The interface config contains all of the default settings for retry
60+
# and timeout for each RPC method.
61+
interfaces = client_config['interfaces']
62+
interface_config = interfaces['google.longrunning.Operations']
63+
method_configs = gapic_v1.config.parse_method_configs(interface_config)
64+
65+
self._get_operation = gapic_v1.method.wrap_method(
66+
self.operations_stub.GetOperation,
67+
default_retry=method_configs['GetOperation'].retry,
68+
default_timeout=method_configs['GetOperation'].timeout)
69+
70+
self._list_operations = gapic_v1.method.wrap_method(
71+
self.operations_stub.ListOperations,
72+
default_retry=method_configs['ListOperations'].retry,
73+
default_timeout=method_configs['ListOperations'].timeout)
74+
75+
self._list_operations = gapic_v1.method.wrap_with_paging(
76+
self._list_operations,
77+
'operations',
78+
'page_token',
79+
'next_page_token')
80+
81+
self._cancel_operation = gapic_v1.method.wrap_method(
82+
self.operations_stub.CancelOperation,
83+
default_retry=method_configs['CancelOperation'].retry,
84+
default_timeout=method_configs['CancelOperation'].timeout)
85+
86+
self._delete_operation = gapic_v1.method.wrap_method(
87+
self.operations_stub.DeleteOperation,
88+
default_retry=method_configs['DeleteOperation'].retry,
89+
default_timeout=method_configs['DeleteOperation'].timeout)
90+
91+
# Service calls
92+
def get_operation(
93+
self, name,
94+
retry=gapic_v1.method.DEFAULT, timeout=gapic_v1.method.DEFAULT):
95+
"""Gets the latest state of a long-running operation.
96+
97+
Clients can use this method to poll the operation result at intervals
98+
as recommended by the API service.
99+
100+
Example:
101+
>>> from google.api.core import operations_v1
102+
>>> api = operations_v1.OperationsClient()
103+
>>> name = ''
104+
>>> response = api.get_operation(name)
105+
106+
Args:
107+
name (str): The name of the operation resource.
108+
retry (google.api.core.retry.Retry): The retry strategy to use
109+
when invoking the RPC. If unspecified, the default retry from
110+
the client configuration will be used. If ``None``, then this
111+
method will not retry the RPC at all.
112+
timeout (float): The amount of time in seconds to wait for the RPC
113+
to complete. Note that if ``retry`` is used, this timeout
114+
applies to each individual attempt and the overall time it
115+
takes for this method to complete may be longer. If
116+
unspecified, the the default timeout in the client
117+
configuration is used. If ``None``, then the RPC method will
118+
not time out.
119+
120+
Returns:
121+
google.longrunning.operations_pb2.Operation: The state of the
122+
operation.
123+
124+
Raises:
125+
google.api.core.exceptions.GoogleAPICallError: If an error occurred
126+
while invoking the RPC, the appropriate ``GoogleAPICallError``
127+
subclass will be raised.
128+
"""
129+
request = operations_pb2.GetOperationRequest(name=name)
130+
return self._get_operation(request, retry=retry, timeout=timeout)
131+
132+
def list_operations(
133+
self, name, filter_,
134+
retry=gapic_v1.method.DEFAULT, timeout=gapic_v1.method.DEFAULT):
135+
"""
136+
Lists operations that match the specified filter in the request.
137+
138+
Example:
139+
>>> from google.api.core import operations_v1
140+
>>> api = operations_v1.OperationsClient()
141+
>>> name = ''
142+
>>>
143+
>>> # Iterate over all results
144+
>>> for operation in api.list_operations(name):
145+
>>> # process operation
146+
>>> pass
147+
>>>
148+
>>> # Or iterate over results one page at a time
149+
>>> iter = api.list_operations(name)
150+
>>> for page in iter.pages:
151+
>>> for operation in page:
152+
>>> # process operation
153+
>>> pass
154+
155+
Args:
156+
name (str): The name of the operation collection.
157+
filter_ (str): The standard list filter.
158+
retry (google.api.core.retry.Retry): The retry strategy to use
159+
when invoking the RPC. If unspecified, the default retry from
160+
the client configuration will be used. If ``None``, then this
161+
method will not retry the RPC at all.
162+
timeout (float): The amount of time in seconds to wait for the RPC
163+
to complete. Note that if ``retry`` is used, this timeout
164+
applies to each individual attempt and the overall time it
165+
takes for this method to complete may be longer. If
166+
unspecified, the the default timeout in the client
167+
configuration is used. If ``None``, then the RPC method will
168+
not time out.
169+
170+
Returns:
171+
google.api.core.page_iterator.Iterator: An iterator that yields
172+
:class:`google.longrunning.operations_pb2.Operation` instances.
173+
174+
Raises:
175+
google.api.core.exceptions.MethodNotImplemented: If the server
176+
does not support this method. Services are not required to
177+
implement this method.
178+
google.api.core.exceptions.GoogleAPICallError: If an error occurred
179+
while invoking the RPC, the appropriate ``GoogleAPICallError``
180+
subclass will be raised.
181+
"""
182+
# Create the request object.
183+
request = operations_pb2.ListOperationsRequest(
184+
name=name, filter=filter_)
185+
return self._list_operations(request, retry=retry, timeout=timeout)
186+
187+
def cancel_operation(
188+
self, name,
189+
retry=gapic_v1.method.DEFAULT, timeout=gapic_v1.method.DEFAULT):
190+
"""Starts asynchronous cancellation on a long-running operation.
191+
192+
The server makes a best effort to cancel the operation, but success is
193+
not guaranteed. Clients can use :meth:`get_operation` or service-
194+
specific methods to check whether the cancellation succeeded or whether
195+
the operation completed despite cancellation. On successful
196+
cancellation, the operation is not deleted; instead, it becomes an
197+
operation with an ``Operation.error`` value with a
198+
``google.rpc.Status.code`` of ``1``, corresponding to
199+
``Code.CANCELLED``.
200+
201+
Example:
202+
>>> from google.api.core import operations_v1
203+
>>> api = operations_v1.OperationsClient()
204+
>>> name = ''
205+
>>> api.cancel_operation(name)
206+
207+
Args:
208+
name (str): The name of the operation resource to be cancelled.
209+
retry (google.api.core.retry.Retry): The retry strategy to use
210+
when invoking the RPC. If unspecified, the default retry from
211+
the client configuration will be used. If ``None``, then this
212+
method will not retry the RPC at all.
213+
timeout (float): The amount of time in seconds to wait for the RPC
214+
to complete. Note that if ``retry`` is used, this timeout
215+
applies to each individual attempt and the overall time it
216+
takes for this method to complete may be longer. If
217+
unspecified, the the default timeout in the client
218+
configuration is used. If ``None``, then the RPC method will
219+
not time out.
220+
221+
Raises:
222+
google.api.core.exceptions.MethodNotImplemented: If the server
223+
does not support this method. Services are not required to
224+
implement this method.
225+
google.api.core.exceptions.GoogleAPICallError: If an error occurred
226+
while invoking the RPC, the appropriate ``GoogleAPICallError``
227+
subclass will be raised.
228+
"""
229+
# Create the request object.
230+
request = operations_pb2.CancelOperationRequest(name=name)
231+
self._cancel_operation(request, retry=retry, timeout=timeout)
232+
233+
def delete_operation(
234+
self, name,
235+
retry=gapic_v1.method.DEFAULT, timeout=gapic_v1.method.DEFAULT):
236+
"""Deletes a long-running operation.
237+
238+
This method indicates that the client is no longer interested in the
239+
operation result. It does not cancel the operation.
240+
241+
Example:
242+
>>> from google.api.core import operations_v1
243+
>>> api = operations_v1.OperationsClient()
244+
>>> name = ''
245+
>>> api.delete_operation(name)
246+
247+
Args:
248+
name (str): The name of the operation resource to be deleted.
249+
retry (google.api.core.retry.Retry): The retry strategy to use
250+
when invoking the RPC. If unspecified, the default retry from
251+
the client configuration will be used. If ``None``, then this
252+
method will not retry the RPC at all.
253+
timeout (float): The amount of time in seconds to wait for the RPC
254+
to complete. Note that if ``retry`` is used, this timeout
255+
applies to each individual attempt and the overall time it
256+
takes for this method to complete may be longer. If
257+
unspecified, the the default timeout in the client
258+
configuration is used. If ``None``, then the RPC method will
259+
not time out.
260+
261+
Raises:
262+
google.api.core.exceptions.MethodNotImplemented: If the server
263+
does not support this method. Services are not required to
264+
implement this method.
265+
google.api.core.exceptions.GoogleAPICallError: If an error occurred
266+
while invoking the RPC, the appropriate ``GoogleAPICallError``
267+
subclass will be raised.
268+
"""
269+
# Create the request object.
270+
request = operations_pb2.DeleteOperationRequest(name=name)
271+
self._delete_operation(request, retry=retry, timeout=timeout)

0 commit comments

Comments
 (0)