Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/api_core/operations_v1/operations_async_client.py: 34%
38 statements
« prev ^ index » next coverage.py v7.2.7, created at 2023-06-06 06:03 +0000
1# Copyright 2020 Google LLC
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.
15"""An async client for the google.longrunning.operations meta-API.
17.. _Google API Style Guide:
18 https://cloud.google.com/apis/design/design_pattern
19 s#long_running_operations
20.. _google/longrunning/operations.proto:
21 https://github.com/googleapis/googleapis/blob/master/google/longrunning
22 /operations.proto
23"""
25import functools
27from google.api_core import exceptions as core_exceptions
28from google.api_core import gapic_v1, page_iterator_async
29from google.api_core import retry as retries
30from google.api_core import timeout as timeouts
31from google.longrunning import operations_pb2
34class OperationsAsyncClient:
35 """Async client for interacting with long-running operations.
37 Args:
38 channel (aio.Channel): The gRPC AsyncIO channel associated with the
39 service that implements the ``google.longrunning.operations``
40 interface.
41 client_config (dict):
42 A dictionary of call options for each method. If not specified
43 the default configuration is used.
44 """
46 def __init__(self, channel, client_config=None):
47 # Create the gRPC client stub with gRPC AsyncIO channel.
48 self.operations_stub = operations_pb2.OperationsStub(channel)
50 default_retry = retries.Retry(
51 initial=0.1, # seconds
52 maximum=60.0, # seconds
53 multiplier=1.3,
54 predicate=retries.if_exception_type(
55 core_exceptions.DeadlineExceeded,
56 core_exceptions.ServiceUnavailable,
57 ),
58 timeout=600.0, # seconds
59 )
60 default_timeout = timeouts.TimeToDeadlineTimeout(timeout=600.0)
62 self._get_operation = gapic_v1.method_async.wrap_method(
63 self.operations_stub.GetOperation,
64 default_retry=default_retry,
65 default_timeout=default_timeout,
66 )
68 self._list_operations = gapic_v1.method_async.wrap_method(
69 self.operations_stub.ListOperations,
70 default_retry=default_retry,
71 default_timeout=default_timeout,
72 )
74 self._cancel_operation = gapic_v1.method_async.wrap_method(
75 self.operations_stub.CancelOperation,
76 default_retry=default_retry,
77 default_timeout=default_timeout,
78 )
80 self._delete_operation = gapic_v1.method_async.wrap_method(
81 self.operations_stub.DeleteOperation,
82 default_retry=default_retry,
83 default_timeout=default_timeout,
84 )
86 async def get_operation(
87 self,
88 name,
89 retry=gapic_v1.method_async.DEFAULT,
90 timeout=gapic_v1.method_async.DEFAULT,
91 metadata=None,
92 ):
93 """Gets the latest state of a long-running operation.
95 Clients can use this method to poll the operation result at intervals
96 as recommended by the API service.
98 Example:
99 >>> from google.api_core import operations_v1
100 >>> api = operations_v1.OperationsClient()
101 >>> name = ''
102 >>> response = await api.get_operation(name)
104 Args:
105 name (str): The name of the operation resource.
106 retry (google.api_core.retry.Retry): The retry strategy to use
107 when invoking the RPC. If unspecified, the default retry from
108 the client configuration will be used. If ``None``, then this
109 method will not retry the RPC at all.
110 timeout (float): The amount of time in seconds to wait for the RPC
111 to complete. Note that if ``retry`` is used, this timeout
112 applies to each individual attempt and the overall time it
113 takes for this method to complete may be longer. If
114 unspecified, the the default timeout in the client
115 configuration is used. If ``None``, then the RPC method will
116 not time out.
117 metadata (Optional[List[Tuple[str, str]]]):
118 Additional gRPC metadata.
120 Returns:
121 google.longrunning.operations_pb2.Operation: The state of the
122 operation.
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)
131 # Add routing header
132 metadata = metadata or []
133 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
135 return await self._get_operation(
136 request, retry=retry, timeout=timeout, metadata=metadata
137 )
139 async def list_operations(
140 self,
141 name,
142 filter_,
143 retry=gapic_v1.method_async.DEFAULT,
144 timeout=gapic_v1.method_async.DEFAULT,
145 metadata=None,
146 ):
147 """
148 Lists operations that match the specified filter in the request.
150 Example:
151 >>> from google.api_core import operations_v1
152 >>> api = operations_v1.OperationsClient()
153 >>> name = ''
154 >>>
155 >>> # Iterate over all results
156 >>> for operation in await api.list_operations(name):
157 >>> # process operation
158 >>> pass
159 >>>
160 >>> # Or iterate over results one page at a time
161 >>> iter = await api.list_operations(name)
162 >>> for page in iter.pages:
163 >>> for operation in page:
164 >>> # process operation
165 >>> pass
167 Args:
168 name (str): The name of the operation collection.
169 filter_ (str): The standard list filter.
170 retry (google.api_core.retry.Retry): The retry strategy to use
171 when invoking the RPC. If unspecified, the default retry from
172 the client configuration will be used. If ``None``, then this
173 method will not retry the RPC at all.
174 timeout (float): The amount of time in seconds to wait for the RPC
175 to complete. Note that if ``retry`` is used, this timeout
176 applies to each individual attempt and the overall time it
177 takes for this method to complete may be longer. If
178 unspecified, the the default timeout in the client
179 configuration is used. If ``None``, then the RPC method will
180 not time out.
181 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
182 metadata.
184 Returns:
185 google.api_core.page_iterator.Iterator: An iterator that yields
186 :class:`google.longrunning.operations_pb2.Operation` instances.
188 Raises:
189 google.api_core.exceptions.MethodNotImplemented: If the server
190 does not support this method. Services are not required to
191 implement this method.
192 google.api_core.exceptions.GoogleAPICallError: If an error occurred
193 while invoking the RPC, the appropriate ``GoogleAPICallError``
194 subclass will be raised.
195 """
196 # Create the request object.
197 request = operations_pb2.ListOperationsRequest(name=name, filter=filter_)
199 # Add routing header
200 metadata = metadata or []
201 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
203 # Create the method used to fetch pages
204 method = functools.partial(
205 self._list_operations, retry=retry, timeout=timeout, metadata=metadata
206 )
208 iterator = page_iterator_async.AsyncGRPCIterator(
209 client=None,
210 method=method,
211 request=request,
212 items_field="operations",
213 request_token_field="page_token",
214 response_token_field="next_page_token",
215 )
217 return iterator
219 async def cancel_operation(
220 self,
221 name,
222 retry=gapic_v1.method_async.DEFAULT,
223 timeout=gapic_v1.method_async.DEFAULT,
224 metadata=None,
225 ):
226 """Starts asynchronous cancellation on a long-running operation.
228 The server makes a best effort to cancel the operation, but success is
229 not guaranteed. Clients can use :meth:`get_operation` or service-
230 specific methods to check whether the cancellation succeeded or whether
231 the operation completed despite cancellation. On successful
232 cancellation, the operation is not deleted; instead, it becomes an
233 operation with an ``Operation.error`` value with a
234 ``google.rpc.Status.code`` of ``1``, corresponding to
235 ``Code.CANCELLED``.
237 Example:
238 >>> from google.api_core import operations_v1
239 >>> api = operations_v1.OperationsClient()
240 >>> name = ''
241 >>> api.cancel_operation(name)
243 Args:
244 name (str): The name of the operation resource to be cancelled.
245 retry (google.api_core.retry.Retry): The retry strategy to use
246 when invoking the RPC. If unspecified, the default retry from
247 the client configuration will be used. If ``None``, then this
248 method will not retry the RPC at all.
249 timeout (float): The amount of time in seconds to wait for the RPC
250 to complete. Note that if ``retry`` is used, this timeout
251 applies to each individual attempt and the overall time it
252 takes for this method to complete may be longer. If
253 unspecified, the the default timeout in the client
254 configuration is used. If ``None``, then the RPC method will
255 not time out.
257 Raises:
258 google.api_core.exceptions.MethodNotImplemented: If the server
259 does not support this method. Services are not required to
260 implement this method.
261 google.api_core.exceptions.GoogleAPICallError: If an error occurred
262 while invoking the RPC, the appropriate ``GoogleAPICallError``
263 subclass will be raised.
264 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
265 metadata.
266 """
267 # Create the request object.
268 request = operations_pb2.CancelOperationRequest(name=name)
270 # Add routing header
271 metadata = metadata or []
272 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
274 await self._cancel_operation(
275 request, retry=retry, timeout=timeout, metadata=metadata
276 )
278 async def delete_operation(
279 self,
280 name,
281 retry=gapic_v1.method_async.DEFAULT,
282 timeout=gapic_v1.method_async.DEFAULT,
283 metadata=None,
284 ):
285 """Deletes a long-running operation.
287 This method indicates that the client is no longer interested in the
288 operation result. It does not cancel the operation.
290 Example:
291 >>> from google.api_core import operations_v1
292 >>> api = operations_v1.OperationsClient()
293 >>> name = ''
294 >>> api.delete_operation(name)
296 Args:
297 name (str): The name of the operation resource to be deleted.
298 retry (google.api_core.retry.Retry): The retry strategy to use
299 when invoking the RPC. If unspecified, the default retry from
300 the client configuration will be used. If ``None``, then this
301 method will not retry the RPC at all.
302 timeout (float): The amount of time in seconds to wait for the RPC
303 to complete. Note that if ``retry`` is used, this timeout
304 applies to each individual attempt and the overall time it
305 takes for this method to complete may be longer. If
306 unspecified, the the default timeout in the client
307 configuration is used. If ``None``, then the RPC method will
308 not time out.
309 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
310 metadata.
312 Raises:
313 google.api_core.exceptions.MethodNotImplemented: If the server
314 does not support this method. Services are not required to
315 implement this method.
316 google.api_core.exceptions.GoogleAPICallError: If an error occurred
317 while invoking the RPC, the appropriate ``GoogleAPICallError``
318 subclass will be raised.
319 """
320 # Create the request object.
321 request = operations_pb2.DeleteOperationRequest(name=name)
323 # Add routing header
324 metadata = metadata or []
325 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
327 await self._delete_operation(
328 request, retry=retry, timeout=timeout, metadata=metadata
329 )