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.
14
15"""An async client for the google.longrunning.operations meta-API.
16
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"""
24
25import functools
26
27from google.api_core import gapic_v1, page_iterator_async
28from google.api_core.operations_v1 import operations_client_config
29from google.longrunning import operations_pb2
30
31
32class OperationsAsyncClient:
33    """Async client for interacting with long-running operations.
34
35    Args:
36        channel (aio.Channel): The gRPC AsyncIO channel associated with the
37            service that implements the ``google.longrunning.operations``
38            interface.
39        client_config (dict):
40            A dictionary of call options for each method. If not specified
41            the default configuration is used.
42    """
43
44    def __init__(self, channel, client_config=operations_client_config.config):
45        # Create the gRPC client stub with gRPC AsyncIO channel.
46        self.operations_stub = operations_pb2.OperationsStub(channel)
47
48        # Create all wrapped methods using the interface configuration.
49        # The interface config contains all of the default settings for retry
50        # and timeout for each RPC method.
51        interfaces = client_config["interfaces"]
52        interface_config = interfaces["google.longrunning.Operations"]
53        method_configs = gapic_v1.config_async.parse_method_configs(interface_config)
54
55        self._get_operation = gapic_v1.method_async.wrap_method(
56            self.operations_stub.GetOperation,
57            default_retry=method_configs["GetOperation"].retry,
58            default_timeout=method_configs["GetOperation"].timeout,
59        )
60
61        self._list_operations = gapic_v1.method_async.wrap_method(
62            self.operations_stub.ListOperations,
63            default_retry=method_configs["ListOperations"].retry,
64            default_timeout=method_configs["ListOperations"].timeout,
65        )
66
67        self._cancel_operation = gapic_v1.method_async.wrap_method(
68            self.operations_stub.CancelOperation,
69            default_retry=method_configs["CancelOperation"].retry,
70            default_timeout=method_configs["CancelOperation"].timeout,
71        )
72
73        self._delete_operation = gapic_v1.method_async.wrap_method(
74            self.operations_stub.DeleteOperation,
75            default_retry=method_configs["DeleteOperation"].retry,
76            default_timeout=method_configs["DeleteOperation"].timeout,
77        )
78
79    async def get_operation(
80        self,
81        name,
82        retry=gapic_v1.method_async.DEFAULT,
83        timeout=gapic_v1.method_async.DEFAULT,
84        metadata=None,
85    ):
86        """Gets the latest state of a long-running operation.
87
88        Clients can use this method to poll the operation result at intervals
89        as recommended by the API service.
90
91        Example:
92            >>> from google.api_core import operations_v1
93            >>> api = operations_v1.OperationsClient()
94            >>> name = ''
95            >>> response = await api.get_operation(name)
96
97        Args:
98            name (str): The name of the operation resource.
99            retry (google.api_core.retry.Retry): The retry strategy to use
100                when invoking the RPC. If unspecified, the default retry from
101                the client configuration will be used. If ``None``, then this
102                method will not retry the RPC at all.
103            timeout (float): The amount of time in seconds to wait for the RPC
104                to complete. Note that if ``retry`` is used, this timeout
105                applies to each individual attempt and the overall time it
106                takes for this method to complete may be longer. If
107                unspecified, the the default timeout in the client
108                configuration is used. If ``None``, then the RPC method will
109                not time out.
110            metadata (Optional[List[Tuple[str, str]]]):
111                Additional gRPC metadata.
112
113        Returns:
114            google.longrunning.operations_pb2.Operation: The state of the
115                operation.
116
117        Raises:
118            google.api_core.exceptions.GoogleAPICallError: If an error occurred
119                while invoking the RPC, the appropriate ``GoogleAPICallError``
120                subclass will be raised.
121        """
122        request = operations_pb2.GetOperationRequest(name=name)
123        return await self._get_operation(request, retry=retry, timeout=timeout, metadata=metadata)
124
125    async def list_operations(
126        self,
127        name,
128        filter_,
129        retry=gapic_v1.method_async.DEFAULT,
130        timeout=gapic_v1.method_async.DEFAULT,
131        metadata=None,
132    ):
133        """
134        Lists operations that match the specified filter in the request.
135
136        Example:
137            >>> from google.api_core import operations_v1
138            >>> api = operations_v1.OperationsClient()
139            >>> name = ''
140            >>>
141            >>> # Iterate over all results
142            >>> for operation in await api.list_operations(name):
143            >>>   # process operation
144            >>>   pass
145            >>>
146            >>> # Or iterate over results one page at a time
147            >>> iter = await api.list_operations(name)
148            >>> for page in iter.pages:
149            >>>   for operation in page:
150            >>>     # process operation
151            >>>     pass
152
153        Args:
154            name (str): The name of the operation collection.
155            filter_ (str): The standard list filter.
156            retry (google.api_core.retry.Retry): The retry strategy to use
157                when invoking the RPC. If unspecified, the default retry from
158                the client configuration will be used. If ``None``, then this
159                method will not retry the RPC at all.
160            timeout (float): The amount of time in seconds to wait for the RPC
161                to complete. Note that if ``retry`` is used, this timeout
162                applies to each individual attempt and the overall time it
163                takes for this method to complete may be longer. If
164                unspecified, the the default timeout in the client
165                configuration is used. If ``None``, then the RPC method will
166                not time out.
167            metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
168                metadata.
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(name=name, filter=filter_)
184
185        # Create the method used to fetch pages
186        method = functools.partial(self._list_operations, retry=retry, timeout=timeout, metadata=metadata)
187
188        iterator = page_iterator_async.AsyncGRPCIterator(
189            client=None,
190            method=method,
191            request=request,
192            items_field="operations",
193            request_token_field="page_token",
194            response_token_field="next_page_token",
195        )
196
197        return iterator
198
199    async def cancel_operation(
200        self,
201        name,
202        retry=gapic_v1.method_async.DEFAULT,
203        timeout=gapic_v1.method_async.DEFAULT,
204        metadata=None,
205    ):
206        """Starts asynchronous cancellation on a long-running operation.
207
208        The server makes a best effort to cancel the operation, but success is
209        not guaranteed. Clients can use :meth:`get_operation` or service-
210        specific methods to check whether the cancellation succeeded or whether
211        the operation completed despite cancellation. On successful
212        cancellation, the operation is not deleted; instead, it becomes an
213        operation with an ``Operation.error`` value with a
214        ``google.rpc.Status.code`` of ``1``, corresponding to
215        ``Code.CANCELLED``.
216
217        Example:
218            >>> from google.api_core import operations_v1
219            >>> api = operations_v1.OperationsClient()
220            >>> name = ''
221            >>> api.cancel_operation(name)
222
223        Args:
224            name (str): The name of the operation resource to be cancelled.
225            retry (google.api_core.retry.Retry): The retry strategy to use
226                when invoking the RPC. If unspecified, the default retry from
227                the client configuration will be used. If ``None``, then this
228                method will not retry the RPC at all.
229            timeout (float): The amount of time in seconds to wait for the RPC
230                to complete. Note that if ``retry`` is used, this timeout
231                applies to each individual attempt and the overall time it
232                takes for this method to complete may be longer. If
233                unspecified, the the default timeout in the client
234                configuration is used. If ``None``, then the RPC method will
235                not time out.
236
237        Raises:
238            google.api_core.exceptions.MethodNotImplemented: If the server
239                does not support this method. Services are not required to
240                implement this method.
241            google.api_core.exceptions.GoogleAPICallError: If an error occurred
242                while invoking the RPC, the appropriate ``GoogleAPICallError``
243                subclass will be raised.
244            metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
245                metadata.
246        """
247        # Create the request object.
248        request = operations_pb2.CancelOperationRequest(name=name)
249        await self._cancel_operation(request, retry=retry, timeout=timeout, metadata=metadata)
250
251    async def delete_operation(
252        self,
253        name,
254        retry=gapic_v1.method_async.DEFAULT,
255        timeout=gapic_v1.method_async.DEFAULT,
256        metadata=None,
257    ):
258        """Deletes a long-running operation.
259
260        This method indicates that the client is no longer interested in the
261        operation result. It does not cancel the operation.
262
263        Example:
264            >>> from google.api_core import operations_v1
265            >>> api = operations_v1.OperationsClient()
266            >>> name = ''
267            >>> api.delete_operation(name)
268
269        Args:
270            name (str): The name of the operation resource to be deleted.
271            retry (google.api_core.retry.Retry): The retry strategy to use
272                when invoking the RPC. If unspecified, the default retry from
273                the client configuration will be used. If ``None``, then this
274                method will not retry the RPC at all.
275            timeout (float): The amount of time in seconds to wait for the RPC
276                to complete. Note that if ``retry`` is used, this timeout
277                applies to each individual attempt and the overall time it
278                takes for this method to complete may be longer. If
279                unspecified, the the default timeout in the client
280                configuration is used. If ``None``, then the RPC method will
281                not time out.
282            metadata (Optional[List[Tuple[str, str]]]): Additional gRPC
283                metadata.
284
285        Raises:
286            google.api_core.exceptions.MethodNotImplemented: If the server
287                does not support this method. Services are not required to
288                implement this method.
289            google.api_core.exceptions.GoogleAPICallError: If an error occurred
290                while invoking the RPC, the appropriate ``GoogleAPICallError``
291                subclass will be raised.
292        """
293        # Create the request object.
294        request = operations_pb2.DeleteOperationRequest(name=name)
295        await self._delete_operation(request, retry=retry, timeout=timeout, metadata=metadata)
296