codekingpro/portable-devtools

1# Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.2#3# Licensed under the Apache License, Version 2.0 (the "License"). You4# may not use this file except in compliance with the License. A copy of5# the License is located at6#7# http://aws.amazon.com/apache2.0/8#9# or in the "license" file accompanying this file. This file is10# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF11# ANY KIND, either express or implied. See the License for the specific12# language governing permissions and limitations under the License.13import os14 15from botocore import xform_name16from botocore.compat import OrderedDict17from botocore.docs.bcdoc.restdoc import DocumentStructure18from botocore.docs.method import document_model_driven_method19from botocore.docs.utils import DocumentedShape20from botocore.utils import get_service_module_name21 22 23class WaiterDocumenter:24    def __init__(self, client, service_waiter_model, root_docs_path):25        self._client = client26        self._client_class_name = self._client.__class__.__name__27        self._service_name = self._client.meta.service_model.service_name28        self._service_waiter_model = service_waiter_model29        self._root_docs_path = root_docs_path30        self._USER_GUIDE_LINK = (31            'https://boto3.amazonaws.com/'32            'v1/documentation/api/latest/guide/clients.html#waiters'33        )34 35    def document_waiters(self, section):36        """Documents the various waiters for a service.37 38        :param section: The section to write to.39        """40        section.style.h2('Waiters')41        self._add_overview(section)42        section.style.new_line()43        section.writeln('The available waiters are:')44        section.style.toctree()45        for waiter_name in self._service_waiter_model.waiter_names:46            section.style.tocitem(f'{self._service_name}/waiter/{waiter_name}')47            # Create a new DocumentStructure for each waiter and add contents.48            waiter_doc_structure = DocumentStructure(49                waiter_name, target='html'50            )51            self._add_single_waiter(waiter_doc_structure, waiter_name)52            # Write waiters in individual/nested files.53            # Path: <root>/reference/services/<service>/waiter/<waiter_name>.rst54            waiter_dir_path = os.path.join(55                self._root_docs_path, self._service_name, 'waiter'56            )57            waiter_doc_structure.write_to_file(waiter_dir_path, waiter_name)58 59    def _add_single_waiter(self, section, waiter_name):60        breadcrumb_section = section.add_new_section('breadcrumb')61        breadcrumb_section.style.ref(62            self._client_class_name, f'../../{self._service_name}'63        )64        breadcrumb_section.write(f' / Waiter / {waiter_name}')65        section.add_title_section(waiter_name)66        waiter_section = section.add_new_section(waiter_name)67        waiter_section.style.start_sphinx_py_class(68            class_name=f"{self._client_class_name}.Waiter.{waiter_name}"69        )70 71        # Add example on how to instantiate waiter.72        waiter_section.style.start_codeblock()73        waiter_section.style.new_line()74        waiter_section.write(75            'waiter = client.get_waiter(\'%s\')' % xform_name(waiter_name)76        )77        waiter_section.style.end_codeblock()78 79        # Add information on the wait() method80        waiter_section.style.new_line()81        document_wait_method(82            section=waiter_section,83            waiter_name=waiter_name,84            event_emitter=self._client.meta.events,85            service_model=self._client.meta.service_model,86            service_waiter_model=self._service_waiter_model,87        )88 89    def _add_overview(self, section):90        section.style.new_line()91        section.write(92            'Waiters are available on a client instance '93            'via the ``get_waiter`` method. For more detailed instructions '94            'and examples on the usage or waiters, see the '95            'waiters '96        )97        section.style.external_link(98            title='user guide',99            link=self._USER_GUIDE_LINK,100        )101        section.write('.')102        section.style.new_line()103 104 105def document_wait_method(106    section,107    waiter_name,108    event_emitter,109    service_model,110    service_waiter_model,111    include_signature=True,112):113    """Documents a the wait method of a waiter114 115    :param section: The section to write to116 117    :param waiter_name: The name of the waiter118 119    :param event_emitter: The event emitter to use to emit events120 121    :param service_model: The service model122 123    :param service_waiter_model: The waiter model associated to the service124 125    :param include_signature: Whether or not to include the signature.126        It is useful for generating docstrings.127    """128    waiter_model = service_waiter_model.get_waiter(waiter_name)129    operation_model = service_model.operation_model(waiter_model.operation)130 131    waiter_config_members = OrderedDict()132 133    waiter_config_members['Delay'] = DocumentedShape(134        name='Delay',135        type_name='integer',136        documentation=(137            '<p>The amount of time in seconds to wait between '138            'attempts. Default: {}</p>'.format(waiter_model.delay)139        ),140    )141 142    waiter_config_members['MaxAttempts'] = DocumentedShape(143        name='MaxAttempts',144        type_name='integer',145        documentation=(146            '<p>The maximum number of attempts to be made. '147            'Default: {}</p>'.format(waiter_model.max_attempts)148        ),149    )150 151    botocore_waiter_params = [152        DocumentedShape(153            name='WaiterConfig',154            type_name='structure',155            documentation=(156                '<p>A dictionary that provides parameters to control '157                'waiting behavior.</p>'158            ),159            members=waiter_config_members,160        )161    ]162 163    wait_description = (164        'Polls :py:meth:`{}.Client.{}` every {} '165        'seconds until a successful state is reached. An error is '166        'returned after {} failed checks.'.format(167            get_service_module_name(service_model),168            xform_name(waiter_model.operation),169            waiter_model.delay,170            waiter_model.max_attempts,171        )172    )173 174    document_model_driven_method(175        section,176        'wait',177        operation_model,178        event_emitter=event_emitter,179        method_description=wait_description,180        example_prefix='waiter.wait',181        include_input=botocore_waiter_params,182        document_output=False,183        include_signature=include_signature,184    )185