Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/google/api_core/future/ 40%

67 statements  

« prev     ^ index     » next v7.3.2, created at 2023-12-08 06:45 +0000

1# Copyright 2017, Google LLC 


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 




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"""Abstract and helper bases for Future implementations.""" 


17import abc 

18import concurrent.futures 


20from google.api_core import exceptions 

21from google.api_core import retry as retries 

22from google.api_core.future import _helpers 

23from google.api_core.future import base 



26class _OperationNotComplete(Exception): 

27 """Private exception used for polling via retry.""" 


29 pass 



32# DEPRECATED as it conflates RPC retry and polling concepts into one. 

33# Use POLLING_PREDICATE instead to configure polling. 

34RETRY_PREDICATE = retries.if_exception_type( 

35 _OperationNotComplete, 

36 exceptions.TooManyRequests, 

37 exceptions.InternalServerError, 

38 exceptions.BadGateway, 

39 exceptions.ServiceUnavailable, 



42# DEPRECATED: use DEFAULT_POLLING to configure LRO polling logic. Construct 

43# Retry object using its default values as a baseline for any custom retry logic 

44# (not to be confused with polling logic). 

45DEFAULT_RETRY = retries.Retry(predicate=RETRY_PREDICATE) 


47# POLLING_PREDICATE is supposed to poll only on _OperationNotComplete. 

48# Any RPC-specific errors (like ServiceUnavailable) will be handled 

49# by retry logic (not to be confused with polling logic) which is triggered for 

50# every polling RPC independently of polling logic but within its context. 

51POLLING_PREDICATE = retries.if_exception_type( 

52 _OperationNotComplete, 



55# Default polling configuration 

56DEFAULT_POLLING = retries.Retry( 

57 predicate=POLLING_PREDICATE, 

58 initial=1.0, # seconds 

59 maximum=20.0, # seconds 

60 multiplier=1.5, 

61 timeout=900, # seconds 




65class PollingFuture(base.Future): 

66 """A Future that needs to poll some service to check its status. 


68 The :meth:`done` method should be implemented by subclasses. The polling 

69 behavior will repeatedly call ``done`` until it returns True. 


71 The actual polling logic is encapsulated in :meth:`result` method. See 

72 documentation for that method for details on how polling works. 


74 .. note:: 


76 Privacy here is intended to prevent the final class from 

77 overexposing, not to prevent subclasses from accessing methods. 


79 Args: 

80 polling (google.api_core.retry.Retry): The configuration used for polling. 

81 This parameter controls how often :meth:`done` is polled. If the 

82 ``timeout`` argument is specified in :meth:`result` method it will 

83 override the ``polling.timeout`` property. 

84 retry (google.api_core.retry.Retry): DEPRECATED use ``polling`` instead. 

85 If set, it will override ``polling`` parameter for backward 

86 compatibility. 

87 """ 


89 _DEFAULT_VALUE = object() 


91 def __init__(self, polling=DEFAULT_POLLING, **kwargs): 

92 super(PollingFuture, self).__init__() 

93 self._polling = kwargs.get("retry", polling) 

94 self._result = None 

95 self._exception = None 

96 self._result_set = False 

97 """bool: Set to True when the result has been set via set_result or 

98 set_exception.""" 

99 self._polling_thread = None 

100 self._done_callbacks = [] 


102 @abc.abstractmethod 

103 def done(self, retry=None): 

104 """Checks to see if the operation is complete. 


106 Args: 

107 retry (google.api_core.retry.Retry): (Optional) How to retry the 

108 polling RPC (to not be confused with polling configuration. See 

109 the documentation for :meth:`result` for details). 


111 Returns: 

112 bool: True if the operation is complete, False otherwise. 

113 """ 

114 # pylint: disable=redundant-returns-doc, missing-raises-doc 

115 raise NotImplementedError() 


117 def _done_or_raise(self, retry=None): 

118 """Check if the future is done and raise if it's not.""" 

119 if not self.done(retry=retry): 

120 raise _OperationNotComplete() 


122 def running(self): 

123 """True if the operation is currently running.""" 

124 return not self.done() 


126 def _blocking_poll(self, timeout=_DEFAULT_VALUE, retry=None, polling=None): 

127 """Poll and wait for the Future to be resolved.""" 


129 if self._result_set: 

130 return 


132 polling = polling or self._polling 

133 if timeout is not PollingFuture._DEFAULT_VALUE: 

134 polling = polling.with_timeout(timeout) 


136 try: 

137 polling(self._done_or_raise)(retry=retry) 

138 except exceptions.RetryError: 

139 raise concurrent.futures.TimeoutError( 

140 f"Operation did not complete within the designated timeout of " 

141 f"{polling.timeout} seconds." 

142 ) 


144 def result(self, timeout=_DEFAULT_VALUE, retry=None, polling=None): 

145 """Get the result of the operation. 


147 This method will poll for operation status periodically, blocking if 

148 necessary. If you just want to make sure that this method does not block 

149 for more than X seconds and you do not care about the nitty-gritty of 

150 how this method operates, just call it with ``result(timeout=X)``. The 

151 other parameters are for advanced use only. 


153 Every call to this method is controlled by the following three 

154 parameters, each of which has a specific, distinct role, even though all three 

155 may look very similar: ``timeout``, ``retry`` and ``polling``. In most 

156 cases users do not need to specify any custom values for any of these 

157 parameters and may simply rely on default ones instead. 


159 If you choose to specify custom parameters, please make sure you've 

160 read the documentation below carefully. 


162 First, please check :class:`google.api_core.retry.Retry` 

163 class documentation for the proper definition of timeout and deadline 

164 terms and for the definition the three different types of timeouts. 

165 This class operates in terms of Retry Timeout and Polling Timeout. It 

166 does not let customizing RPC timeout and the user is expected to rely on 

167 default behavior for it. 


169 The roles of each argument of this method are as follows: 


171 ``timeout`` (int): (Optional) The Polling Timeout as defined in 

172 :class:`google.api_core.retry.Retry`. If the operation does not complete 

173 within this timeout an exception will be thrown. This parameter affects 

174 neither Retry Timeout nor RPC Timeout. 


176 ``retry`` (google.api_core.retry.Retry): (Optional) How to retry the 

177 polling RPC. The ``retry.timeout`` property of this parameter is the 

178 Retry Timeout as defined in :class:`google.api_core.retry.Retry`. 

179 This parameter defines ONLY how the polling RPC call is retried 

180 (i.e. what to do if the RPC we used for polling returned an error). It 

181 does NOT define how the polling is done (i.e. how frequently and for 

182 how long to call the polling RPC); use the ``polling`` parameter for that. 

183 If a polling RPC throws and error and retrying it fails, the whole 

184 future fails with the corresponding exception. If you want to tune which 

185 server response error codes are not fatal for operation polling, use this 

186 parameter to control that (``retry.predicate`` in particular). 


188 ``polling`` (google.api_core.retry.Retry): (Optional) How often and 

189 for how long to call the polling RPC periodically (i.e. what to do if 

190 a polling rpc returned successfully but its returned result indicates 

191 that the long running operation is not completed yet, so we need to 

192 check it again at some point in future). This parameter does NOT define 

193 how to retry each individual polling RPC in case of an error; use the 

194 ``retry`` parameter for that. The ``polling.timeout`` of this parameter 

195 is Polling Timeout as defined in as defined in 

196 :class:`google.api_core.retry.Retry`. 


198 For each of the arguments, there are also default values in place, which 

199 will be used if a user does not specify their own. The default values 

200 for the three parameters are not to be confused with the default values 

201 for the corresponding arguments in this method (those serve as "not set" 

202 markers for the resolution logic). 


204 If ``timeout`` is provided (i.e.``timeout is not _DEFAULT VALUE``; note 

205 the ``None`` value means "infinite timeout"), it will be used to control 

206 the actual Polling Timeout. Otherwise, the ``polling.timeout`` value 

207 will be used instead (see below for how the ``polling`` config itself 

208 gets resolved). In other words, this parameter effectively overrides 

209 the ``polling.timeout`` value if specified. This is so to preserve 

210 backward compatibility. 


212 If ``retry`` is provided (i.e. ``retry is not None``) it will be used to 

213 control retry behavior for the polling RPC and the ``retry.timeout`` 

214 will determine the Retry Timeout. If not provided, the 

215 polling RPC will be called with whichever default retry config was 

216 specified for the polling RPC at the moment of the construction of the 

217 polling RPC's client. For example, if the polling RPC is 

218 ``operations_client.get_operation()``, the ``retry`` parameter will be 

219 controlling its retry behavior (not polling behavior) and, if not 

220 specified, that specific method (``operations_client.get_operation()``) 

221 will be retried according to the default retry config provided during 

222 creation of ``operations_client`` client instead. This argument exists 

223 mainly for backward compatibility; users are very unlikely to ever need 

224 to set this parameter explicitly. 


226 If ``polling`` is provided (i.e. ``polling is not None``), it will be used 

227 to control the overall polling behavior and ``polling.timeout`` will 

228 control Polling Timeout unless it is overridden by ``timeout`` parameter 

229 as described above. If not provided, the``polling`` parameter specified 

230 during construction of this future (the ``polling`` argument in the 

231 constructor) will be used instead. Note: since the ``timeout`` argument may 

232 override ``polling.timeout`` value, this parameter should be viewed as 

233 coupled with the ``timeout`` parameter as described above. 


235 Args: 

236 timeout (int): (Optional) How long (in seconds) to wait for the 

237 operation to complete. If None, wait indefinitely. 

238 retry (google.api_core.retry.Retry): (Optional) How to retry the 

239 polling RPC. This defines ONLY how the polling RPC call is 

240 retried (i.e. what to do if the RPC we used for polling returned 

241 an error). It does NOT define how the polling is done (i.e. how 

242 frequently and for how long to call the polling RPC). 

243 polling (google.api_core.retry.Retry): (Optional) How often and 

244 for how long to call polling RPC periodically. This parameter 

245 does NOT define how to retry each individual polling RPC call 

246 (use the ``retry`` parameter for that). 


248 Returns: 

249 google.protobuf.Message: The Operation's result. 


251 Raises: 

252 google.api_core.GoogleAPICallError: If the operation errors or if 

253 the timeout is reached before the operation completes. 

254 """ 


256 self._blocking_poll(timeout=timeout, retry=retry, polling=polling) 


258 if self._exception is not None: 

259 # pylint: disable=raising-bad-type 

260 # Pylint doesn't recognize that this is valid in this case. 

261 raise self._exception 


263 return self._result 


265 def exception(self, timeout=_DEFAULT_VALUE): 

266 """Get the exception from the operation, blocking if necessary. 


268 See the documentation for the :meth:`result` method for details on how 

269 this method operates, as both ``result`` and this method rely on the 

270 exact same polling logic. The only difference is that this method does 

271 not accept ``retry`` and ``polling`` arguments but relies on the default ones 

272 instead. 


274 Args: 

275 timeout (int): How long to wait for the operation to complete. 

276 If None, wait indefinitely. 


278 Returns: 

279 Optional[google.api_core.GoogleAPICallError]: The operation's 

280 error. 

281 """ 

282 self._blocking_poll(timeout=timeout) 

283 return self._exception 


285 def add_done_callback(self, fn): 

286 """Add a callback to be executed when the operation is complete. 


288 If the operation is not already complete, this will start a helper 

289 thread to poll for the status of the operation in the background. 


291 Args: 

292 fn (Callable[Future]): The callback to execute when the operation 

293 is complete. 

294 """ 

295 if self._result_set: 

296 _helpers.safe_invoke_callback(fn, self) 

297 return 


299 self._done_callbacks.append(fn) 


301 if self._polling_thread is None: 

302 # The polling thread will exit on its own as soon as the operation 

303 # is done. 

304 self._polling_thread = _helpers.start_daemon_thread( 

305 target=self._blocking_poll 

306 ) 


308 def _invoke_callbacks(self, *args, **kwargs): 

309 """Invoke all done callbacks.""" 

310 for callback in self._done_callbacks: 

311 _helpers.safe_invoke_callback(callback, *args, **kwargs) 


313 def set_result(self, result): 

314 """Set the Future's result.""" 

315 self._result = result 

316 self._result_set = True 

317 self._invoke_callbacks(self) 


319 def set_exception(self, exception): 

320 """Set the Future's exception.""" 

321 self._exception = exception 

322 self._result_set = True 

323 self._invoke_callbacks(self)