Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/api_core/operations_v1/operations_client.py: 36%
39 statements
« prev ^ index » next coverage.py v7.2.2, created at 2023-03-26 07:30 +0000
1# Copyright 2017 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"""A client for the google.longrunning.operations meta-API.
17This is a client that deals with long-running operations that follow the
18pattern outlined by the `Google API Style Guide`_.
20When an API method normally takes long time to complete, it can be designed to
21return ``Operation`` to the client, and the client can use this interface to
22receive the real response asynchronously by polling the operation resource to
23receive the response.
25It is not a separate service, but rather an interface implemented by a larger
26service. The protocol-level definition is available at
27`google/longrunning/operations.proto`_. Typically, this will be constructed
28automatically by another client class to deal with operations.
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"""
38import functools
40from google.api_core import exceptions as core_exceptions
41from google.api_core import gapic_v1
42from google.api_core import page_iterator
43from google.api_core import retry as retries
44from google.api_core import timeout as timeouts
45from google.longrunning import operations_pb2
48class OperationsClient(object):
49 """Client for interacting with long-running operations within a service.
51 Args:
52 channel (grpc.Channel): The gRPC channel associated with the service
53 that implements the ``google.longrunning.operations`` interface.
54 client_config (dict):
55 A dictionary of call options for each method. If not specified
56 the default configuration is used.
57 """
59 def __init__(self, channel, client_config=None):
60 # Create the gRPC client stub.
61 self.operations_stub = operations_pb2.OperationsStub(channel)
63 default_retry = retries.Retry(
64 initial=0.1, # seconds
65 maximum=60.0, # seconds
66 multiplier=1.3,
67 predicate=retries.if_exception_type(
68 core_exceptions.DeadlineExceeded,
69 core_exceptions.ServiceUnavailable,
70 ),
71 timeout=600.0, # seconds
72 )
73 default_timeout = timeouts.TimeToDeadlineTimeout(timeout=600.0)
75 self._get_operation = gapic_v1.method.wrap_method(
76 self.operations_stub.GetOperation,
77 default_retry=default_retry,
78 default_timeout=default_timeout,
79 )
81 self._list_operations = gapic_v1.method.wrap_method(
82 self.operations_stub.ListOperations,
83 default_retry=default_retry,
84 default_timeout=default_timeout,
85 )
87 self._cancel_operation = gapic_v1.method.wrap_method(
88 self.operations_stub.CancelOperation,
89 default_retry=default_retry,
90 default_timeout=default_timeout,
91 )
93 self._delete_operation = gapic_v1.method.wrap_method(
94 self.operations_stub.DeleteOperation,
95 default_retry=default_retry,
96 default_timeout=default_timeout,
97 )
99 # Service calls
100 def get_operation(
101 self,
102 name,
103 retry=gapic_v1.method.DEFAULT,
104 timeout=gapic_v1.method.DEFAULT,
105 metadata=None,
106 ):
107 """Gets the latest state of a long-running operation.
109 Clients can use this method to poll the operation result at intervals
110 as recommended by the API service.
112 Example:
113 >>> from google.api_core import operations_v1
114 >>> api = operations_v1.OperationsClient()
115 >>> name = ''
116 >>> response = api.get_operation(name)
118 Args:
119 name (str): The name of the operation resource.
120 retry (google.api_core.retry.Retry): The retry strategy to use
121 when invoking the RPC. If unspecified, the default retry from
122 the client configuration will be used. If ``None``, then this
123 method will not retry the RPC at all.
124 timeout (float): The amount of time in seconds to wait for the RPC
125 to complete. Note that if ``retry`` is used, this timeout
126 applies to each individual attempt and the overall time it
127 takes for this method to complete may be longer. If
128 unspecified, the the default timeout in the client
129 configuration is used. If ``None``, then the RPC method will
130 not time out.
131 metadata (Optional[List[Tuple[str, str]]]):
132 Additional gRPC metadata.
134 Returns:
135 google.longrunning.operations_pb2.Operation: The state of the
136 operation.
138 Raises:
139 google.api_core.exceptions.GoogleAPICallError: If an error occurred
140 while invoking the RPC, the appropriate ``GoogleAPICallError``
141 subclass will be raised.
142 """
143 request = operations_pb2.GetOperationRequest(name=name)
145 # Add routing header
146 metadata = metadata or []
147 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
149 return self._get_operation(
150 request, retry=retry, timeout=timeout, metadata=metadata
151 )
153 def list_operations(
154 self,
155 name,
156 filter_,
157 retry=gapic_v1.method.DEFAULT,
158 timeout=gapic_v1.method.DEFAULT,
159 metadata=None,
160 ):
161 """
162 Lists operations that match the specified filter in the request.
164 Example:
165 >>> from google.api_core import operations_v1
166 >>> api = operations_v1.OperationsClient()
167 >>> name = ''
168 >>>
169 >>> # Iterate over all results
170 >>> for operation in api.list_operations(name):
171 >>> # process operation
172 >>> pass
173 >>>
174 >>> # Or iterate over results one page at a time
175 >>> iter = api.list_operations(name)
176 >>> for page in iter.pages:
177 >>> for operation in page:
178 >>> # process operation
179 >>> pass
181 Args:
182 name (str): The name of the operation collection.
183 filter_ (str): The standard list filter.
184 retry (google.api_core.retry.Retry): The retry strategy to use
185 when invoking the RPC. If unspecified, the default retry from
186 the client configuration will be used. If ``None``, then this
187 method will not retry the RPC at all.
188 timeout (float): The amount of time in seconds to wait for the RPC
189 to complete. Note that if ``retry`` is used, this timeout
190 applies to each individual attempt and the overall time it
191 takes for this method to complete may be longer. If
192 unspecified, the the default timeout in the client
193 configuration is used. If ``None``, then the RPC method will
194 not time out.
195 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
196 metadata.
198 Returns:
199 google.api_core.page_iterator.Iterator: An iterator that yields
200 :class:`google.longrunning.operations_pb2.Operation` instances.
202 Raises:
203 google.api_core.exceptions.MethodNotImplemented: If the server
204 does not support this method. Services are not required to
205 implement this method.
206 google.api_core.exceptions.GoogleAPICallError: If an error occurred
207 while invoking the RPC, the appropriate ``GoogleAPICallError``
208 subclass will be raised.
209 """
210 # Create the request object.
211 request = operations_pb2.ListOperationsRequest(name=name, filter=filter_)
213 # Add routing header
214 metadata = metadata or []
215 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
217 # Create the method used to fetch pages
218 method = functools.partial(
219 self._list_operations, retry=retry, timeout=timeout, metadata=metadata
220 )
222 iterator = page_iterator.GRPCIterator(
223 client=None,
224 method=method,
225 request=request,
226 items_field="operations",
227 request_token_field="page_token",
228 response_token_field="next_page_token",
229 )
231 return iterator
233 def cancel_operation(
234 self,
235 name,
236 retry=gapic_v1.method.DEFAULT,
237 timeout=gapic_v1.method.DEFAULT,
238 metadata=None,
239 ):
240 """Starts asynchronous cancellation on a long-running operation.
242 The server makes a best effort to cancel the operation, but success is
243 not guaranteed. Clients can use :meth:`get_operation` or service-
244 specific methods to check whether the cancellation succeeded or whether
245 the operation completed despite cancellation. On successful
246 cancellation, the operation is not deleted; instead, it becomes an
247 operation with an ``Operation.error`` value with a
248 ``google.rpc.Status.code`` of ``1``, corresponding to
249 ``Code.CANCELLED``.
251 Example:
252 >>> from google.api_core import operations_v1
253 >>> api = operations_v1.OperationsClient()
254 >>> name = ''
255 >>> api.cancel_operation(name)
257 Args:
258 name (str): The name of the operation resource to be cancelled.
259 retry (google.api_core.retry.Retry): The retry strategy to use
260 when invoking the RPC. If unspecified, the default retry from
261 the client configuration will be used. If ``None``, then this
262 method will not retry the RPC at all.
263 timeout (float): The amount of time in seconds to wait for the RPC
264 to complete. Note that if ``retry`` is used, this timeout
265 applies to each individual attempt and the overall time it
266 takes for this method to complete may be longer. If
267 unspecified, the the default timeout in the client
268 configuration is used. If ``None``, then the RPC method will
269 not time out.
270 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
271 metadata.
273 Raises:
274 google.api_core.exceptions.MethodNotImplemented: If the server
275 does not support this method. Services are not required to
276 implement this method.
277 google.api_core.exceptions.GoogleAPICallError: If an error occurred
278 while invoking the RPC, the appropriate ``GoogleAPICallError``
279 subclass will be raised.
280 """
281 # Create the request object.
282 request = operations_pb2.CancelOperationRequest(name=name)
284 # Add routing header
285 metadata = metadata or []
286 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
288 self._cancel_operation(request, retry=retry, timeout=timeout, metadata=metadata)
290 def delete_operation(
291 self,
292 name,
293 retry=gapic_v1.method.DEFAULT,
294 timeout=gapic_v1.method.DEFAULT,
295 metadata=None,
296 ):
297 """Deletes a long-running operation.
299 This method indicates that the client is no longer interested in the
300 operation result. It does not cancel the operation.
302 Example:
303 >>> from google.api_core import operations_v1
304 >>> api = operations_v1.OperationsClient()
305 >>> name = ''
306 >>> api.delete_operation(name)
308 Args:
309 name (str): The name of the operation resource to be deleted.
310 retry (google.api_core.retry.Retry): The retry strategy to use
311 when invoking the RPC. If unspecified, the default retry from
312 the client configuration will be used. If ``None``, then this
313 method will not retry the RPC at all.
314 timeout (float): The amount of time in seconds to wait for the RPC
315 to complete. Note that if ``retry`` is used, this timeout
316 applies to each individual attempt and the overall time it
317 takes for this method to complete may be longer. If
318 unspecified, the the default timeout in the client
319 configuration is used. If ``None``, then the RPC method will
320 not time out.
321 metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
322 metadata.
324 Raises:
325 google.api_core.exceptions.MethodNotImplemented: If the server
326 does not support this method. Services are not required to
327 implement this method.
328 google.api_core.exceptions.GoogleAPICallError: If an error occurred
329 while invoking the RPC, the appropriate ``GoogleAPICallError``
330 subclass will be raised.
331 """
332 # Create the request object.
333 request = operations_pb2.DeleteOperationRequest(name=name)
335 # Add routing header
336 metadata = metadata or []
337 metadata.append(gapic_v1.routing_header.to_grpc_metadata({"name": name}))
339 self._delete_operation(request, retry=retry, timeout=timeout, metadata=metadata)