waiter.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367
  1. # Copyright 2012-2014 Amazon.com, Inc. or its affiliates. All Rights Reserved.
  2. #
  3. # Licensed under the Apache License, Version 2.0 (the "License"). You
  4. # may not use this file except in compliance with the License. A copy of
  5. # the License is located at
  6. #
  7. # http://aws.amazon.com/apache2.0/
  8. #
  9. # or in the "license" file accompanying this file. This file is
  10. # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
  11. # ANY KIND, either express or implied. See the License for the specific
  12. # language governing permissions and limitations under the License.
  13. import jmespath
  14. import logging
  15. import time
  16. from botocore.utils import get_service_module_name
  17. from botocore.docs.docstring import WaiterDocstring
  18. from .exceptions import WaiterError, ClientError, WaiterConfigError
  19. from . import xform_name
  20. logger = logging.getLogger(__name__)
  21. def create_waiter_with_client(waiter_name, waiter_model, client):
  22. """
  23. :type waiter_name: str
  24. :param waiter_name: The name of the waiter. The name should match
  25. the name (including the casing) of the key name in the waiter
  26. model file (typically this is CamelCasing).
  27. :type waiter_model: botocore.waiter.WaiterModel
  28. :param waiter_model: The model for the waiter configuration.
  29. :type client: botocore.client.BaseClient
  30. :param client: The botocore client associated with the service.
  31. :rtype: botocore.waiter.Waiter
  32. :return: The waiter object.
  33. """
  34. single_waiter_config = waiter_model.get_waiter(waiter_name)
  35. operation_name = xform_name(single_waiter_config.operation)
  36. operation_method = NormalizedOperationMethod(
  37. getattr(client, operation_name))
  38. # Create a new wait method that will serve as a proxy to the underlying
  39. # Waiter.wait method. This is needed to attach a docstring to the
  40. # method.
  41. def wait(self, **kwargs):
  42. Waiter.wait(self, **kwargs)
  43. wait.__doc__ = WaiterDocstring(
  44. waiter_name=waiter_name,
  45. event_emitter=client.meta.events,
  46. service_model=client.meta.service_model,
  47. service_waiter_model=waiter_model,
  48. include_signature=False
  49. )
  50. # Rename the waiter class based on the type of waiter.
  51. waiter_class_name = str('%s.Waiter.%s' % (
  52. get_service_module_name(client.meta.service_model),
  53. waiter_name))
  54. # Create the new waiter class
  55. documented_waiter_cls = type(
  56. waiter_class_name, (Waiter,), {'wait': wait})
  57. # Return an instance of the new waiter class.
  58. return documented_waiter_cls(
  59. waiter_name, single_waiter_config, operation_method
  60. )
  61. def is_valid_waiter_error(response):
  62. error = response.get('Error')
  63. if isinstance(error, dict) and 'Code' in error:
  64. return True
  65. return False
  66. class NormalizedOperationMethod(object):
  67. def __init__(self, client_method):
  68. self._client_method = client_method
  69. def __call__(self, **kwargs):
  70. try:
  71. return self._client_method(**kwargs)
  72. except ClientError as e:
  73. return e.response
  74. class WaiterModel(object):
  75. SUPPORTED_VERSION = 2
  76. def __init__(self, waiter_config):
  77. """
  78. Note that the WaiterModel takes ownership of the waiter_config.
  79. It may or may not mutate the waiter_config. If this is a concern,
  80. it is best to make a copy of the waiter config before passing it to
  81. the WaiterModel.
  82. :type waiter_config: dict
  83. :param waiter_config: The loaded waiter config
  84. from the <service>*.waiters.json file. This can be
  85. obtained from a botocore Loader object as well.
  86. """
  87. self._waiter_config = waiter_config['waiters']
  88. # These are part of the public API. Changing these
  89. # will result in having to update the consuming code,
  90. # so don't change unless you really need to.
  91. version = waiter_config.get('version', 'unknown')
  92. self._verify_supported_version(version)
  93. self.version = version
  94. self.waiter_names = list(sorted(waiter_config['waiters'].keys()))
  95. def _verify_supported_version(self, version):
  96. if version != self.SUPPORTED_VERSION:
  97. raise WaiterConfigError(
  98. error_msg=("Unsupported waiter version, supported version "
  99. "must be: %s, but version of waiter config "
  100. "is: %s" % (self.SUPPORTED_VERSION,
  101. version)))
  102. def get_waiter(self, waiter_name):
  103. try:
  104. single_waiter_config = self._waiter_config[waiter_name]
  105. except KeyError:
  106. raise ValueError("Waiter does not exist: %s" % waiter_name)
  107. return SingleWaiterConfig(single_waiter_config)
  108. class SingleWaiterConfig(object):
  109. """Represents the waiter configuration for a single waiter.
  110. A single waiter is considered the configuration for a single
  111. value associated with a named waiter (i.e TableExists).
  112. """
  113. def __init__(self, single_waiter_config):
  114. self._config = single_waiter_config
  115. # These attributes are part of the public API.
  116. self.description = single_waiter_config.get('description', '')
  117. # Per the spec, these three fields are required.
  118. self.operation = single_waiter_config['operation']
  119. self.delay = single_waiter_config['delay']
  120. self.max_attempts = single_waiter_config['maxAttempts']
  121. @property
  122. def acceptors(self):
  123. acceptors = []
  124. for acceptor_config in self._config['acceptors']:
  125. acceptor = AcceptorConfig(acceptor_config)
  126. acceptors.append(acceptor)
  127. return acceptors
  128. class AcceptorConfig(object):
  129. def __init__(self, config):
  130. self.state = config['state']
  131. self.matcher = config['matcher']
  132. self.expected = config['expected']
  133. self.argument = config.get('argument')
  134. self.matcher_func = self._create_matcher_func()
  135. @property
  136. def explanation(self):
  137. if self.matcher == 'path':
  138. return 'For expression "%s" we matched expected path: "%s"' % (self.argument, self.expected)
  139. elif self.matcher == 'pathAll':
  140. return 'For expression "%s" all members matched excepted path: "%s"' % (self.argument, self.expected)
  141. elif self.matcher == 'pathAny':
  142. return 'For expression "%s" we matched expected path: "%s" at least once' % (self.argument, self.expected)
  143. elif self.matcher == 'status':
  144. return 'Matched expected HTTP status code: %s' % self.expected
  145. elif self.matcher == 'error':
  146. return 'Matched expected service error code: %s' % self.expected
  147. else:
  148. return 'No explanation for unknown waiter type: "%s"' % self.matcher
  149. def _create_matcher_func(self):
  150. # An acceptor function is a callable that takes a single value. The
  151. # parsed AWS response. Note that the parsed error response is also
  152. # provided in the case of errors, so it's entirely possible to
  153. # handle all the available matcher capabilities in the future.
  154. # There's only three supported matchers, so for now, this is all
  155. # contained to a single method. If this grows, we can expand this
  156. # out to separate methods or even objects.
  157. if self.matcher == 'path':
  158. return self._create_path_matcher()
  159. elif self.matcher == 'pathAll':
  160. return self._create_path_all_matcher()
  161. elif self.matcher == 'pathAny':
  162. return self._create_path_any_matcher()
  163. elif self.matcher == 'status':
  164. return self._create_status_matcher()
  165. elif self.matcher == 'error':
  166. return self._create_error_matcher()
  167. else:
  168. raise WaiterConfigError(
  169. error_msg="Unknown acceptor: %s" % self.matcher)
  170. def _create_path_matcher(self):
  171. expression = jmespath.compile(self.argument)
  172. expected = self.expected
  173. def acceptor_matches(response):
  174. if is_valid_waiter_error(response):
  175. return
  176. return expression.search(response) == expected
  177. return acceptor_matches
  178. def _create_path_all_matcher(self):
  179. expression = jmespath.compile(self.argument)
  180. expected = self.expected
  181. def acceptor_matches(response):
  182. if is_valid_waiter_error(response):
  183. return
  184. result = expression.search(response)
  185. if not isinstance(result, list) or not result:
  186. # pathAll matcher must result in a list.
  187. # Also we require at least one element in the list,
  188. # that is, an empty list should not result in this
  189. # acceptor match.
  190. return False
  191. for element in result:
  192. if element != expected:
  193. return False
  194. return True
  195. return acceptor_matches
  196. def _create_path_any_matcher(self):
  197. expression = jmespath.compile(self.argument)
  198. expected = self.expected
  199. def acceptor_matches(response):
  200. if is_valid_waiter_error(response):
  201. return
  202. result = expression.search(response)
  203. if not isinstance(result, list) or not result:
  204. # pathAny matcher must result in a list.
  205. # Also we require at least one element in the list,
  206. # that is, an empty list should not result in this
  207. # acceptor match.
  208. return False
  209. for element in result:
  210. if element == expected:
  211. return True
  212. return False
  213. return acceptor_matches
  214. def _create_status_matcher(self):
  215. expected = self.expected
  216. def acceptor_matches(response):
  217. # We don't have any requirements on the expected incoming data
  218. # other than it is a dict, so we don't assume there's
  219. # a ResponseMetadata.HTTPStatusCode.
  220. status_code = response.get('ResponseMetadata', {}).get(
  221. 'HTTPStatusCode')
  222. return status_code == expected
  223. return acceptor_matches
  224. def _create_error_matcher(self):
  225. expected = self.expected
  226. def acceptor_matches(response):
  227. # When the client encounters an error, it will normally raise
  228. # an exception. However, the waiter implementation will catch
  229. # this exception, and instead send us the parsed error
  230. # response. So response is still a dictionary, and in the case
  231. # of an error response will contain the "Error" and
  232. # "ResponseMetadata" key.
  233. return response.get("Error", {}).get("Code", "") == expected
  234. return acceptor_matches
  235. class Waiter(object):
  236. def __init__(self, name, config, operation_method):
  237. """
  238. :type name: string
  239. :param name: The name of the waiter
  240. :type config: botocore.waiter.SingleWaiterConfig
  241. :param config: The configuration for the waiter.
  242. :type operation_method: callable
  243. :param operation_method: A callable that accepts **kwargs
  244. and returns a response. For example, this can be
  245. a method from a botocore client.
  246. """
  247. self._operation_method = operation_method
  248. # The two attributes are exposed to allow for introspection
  249. # and documentation.
  250. self.name = name
  251. self.config = config
  252. def wait(self, **kwargs):
  253. acceptors = list(self.config.acceptors)
  254. current_state = 'waiting'
  255. # pop the invocation specific config
  256. config = kwargs.pop('WaiterConfig', {})
  257. sleep_amount = config.get('Delay', self.config.delay)
  258. max_attempts = config.get('MaxAttempts', self.config.max_attempts)
  259. last_matched_acceptor = None
  260. num_attempts = 0
  261. while True:
  262. response = self._operation_method(**kwargs)
  263. num_attempts += 1
  264. for acceptor in acceptors:
  265. if acceptor.matcher_func(response):
  266. last_matched_acceptor = acceptor
  267. current_state = acceptor.state
  268. break
  269. else:
  270. # If none of the acceptors matched, we should
  271. # transition to the failure state if an error
  272. # response was received.
  273. if is_valid_waiter_error(response):
  274. # Transition to a failure state, which we
  275. # can just handle here by raising an exception.
  276. raise WaiterError(
  277. name=self.name,
  278. reason='An error occurred (%s): %s' % (
  279. response['Error'].get('Code', 'Unknown'),
  280. response['Error'].get('Message', 'Unknown'),
  281. ),
  282. last_response=response,
  283. )
  284. if current_state == 'success':
  285. logger.debug("Waiting complete, waiter matched the "
  286. "success state.")
  287. return
  288. if current_state == 'failure':
  289. reason = 'Waiter encountered a terminal failure state: %s' % (
  290. acceptor.explanation
  291. )
  292. raise WaiterError(
  293. name=self.name,
  294. reason=reason,
  295. last_response=response,
  296. )
  297. if num_attempts >= max_attempts:
  298. if last_matched_acceptor is None:
  299. reason = 'Max attempts exceeded'
  300. else:
  301. reason = 'Max attempts exceeded. Previously accepted state: %s' %(
  302. acceptor.explanation
  303. )
  304. raise WaiterError(
  305. name=self.name,
  306. reason=reason,
  307. last_response=response,
  308. )
  309. time.sleep(sleep_amount)