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