1# Copyright 2015 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# https://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. 13from botocore import xform_name 14from botocore.utils import get_service_module_name 15from botocore.docs.method import document_model_driven_method 16 17from boto3.docs.base import BaseDocumenter 18from boto3.docs.utils import get_resource_ignore_params 19from boto3.docs.utils import add_resource_type_overview 20 21 22class WaiterResourceDocumenter(BaseDocumenter): 23 def __init__(self, resource, service_waiter_model): 24 super(WaiterResourceDocumenter, self).__init__(resource) 25 self._service_waiter_model = service_waiter_model 26 27 def document_resource_waiters(self, section): 28 waiters = self._resource.meta.resource_model.waiters 29 add_resource_type_overview( 30 section=section, 31 resource_type='Waiters', 32 description=( 33 'Waiters provide an interface to wait for a resource' 34 ' to reach a specific state.'), 35 intro_link='waiters_intro') 36 waiter_list = [] 37 self.member_map['waiters'] = waiter_list 38 for waiter in waiters: 39 waiter_section = section.add_new_section(waiter.name) 40 waiter_list.append(waiter.name) 41 document_resource_waiter( 42 section=waiter_section, 43 resource_name=self._resource_name, 44 event_emitter=self._resource.meta.client.meta.events, 45 service_model=self._service_model, 46 resource_waiter_model=waiter, 47 service_waiter_model=self._service_waiter_model 48 ) 49 50 51def document_resource_waiter(section, resource_name, event_emitter, 52 service_model, resource_waiter_model, 53 service_waiter_model, include_signature=True): 54 waiter_model = service_waiter_model.get_waiter( 55 resource_waiter_model.waiter_name) 56 operation_model = service_model.operation_model( 57 waiter_model.operation) 58 59 ignore_params = get_resource_ignore_params(resource_waiter_model.params) 60 service_module_name = get_service_module_name(service_model) 61 description = ( 62 'Waits until this %s is %s. This method calls ' 63 ':py:meth:`%s.Waiter.%s.wait` which polls. ' 64 ':py:meth:`%s.Client.%s` every %s seconds until ' 65 'a successful state is reached. An error is returned ' 66 'after %s failed checks.' % ( 67 resource_name, ' '.join(resource_waiter_model.name.split('_')[2:]), 68 service_module_name, 69 xform_name(resource_waiter_model.waiter_name), 70 service_module_name, 71 xform_name(waiter_model.operation), 72 waiter_model.delay, waiter_model.max_attempts)) 73 example_prefix = '%s.%s' % ( 74 xform_name(resource_name), resource_waiter_model.name) 75 document_model_driven_method( 76 section=section, method_name=resource_waiter_model.name, 77 operation_model=operation_model, 78 event_emitter=event_emitter, 79 example_prefix=example_prefix, 80 method_description=description, 81 exclude_input=ignore_params, 82 include_signature=include_signature 83 ) 84 if 'return' in section.available_sections: 85 # Waiters do not return anything so we should remove 86 # any sections that may document the underlying return 87 # value of the client method. 88 return_section = section.get_section('return') 89 return_section.clear_text() 90 return_section.remove_all_sections() 91 return_section.write(':returns: None') 92