Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/botocore/docs/waiter.py: 24%
55 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-08 06:51 +0000
« prev ^ index » next coverage.py v7.3.2, created at 2023-12-08 06:51 +0000
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# 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.
13import os
15from botocore import xform_name
16from botocore.compat import OrderedDict
17from botocore.docs.bcdoc.restdoc import DocumentStructure
18from botocore.docs.method import document_model_driven_method
19from botocore.docs.utils import DocumentedShape
20from botocore.utils import get_service_module_name
23class WaiterDocumenter:
24 def __init__(self, client, service_waiter_model, root_docs_path):
25 self._client = client
26 self._client_class_name = self._client.__class__.__name__
27 self._service_name = self._client.meta.service_model.service_name
28 self._service_waiter_model = service_waiter_model
29 self._root_docs_path = root_docs_path
30 self._USER_GUIDE_LINK = (
31 'https://boto3.amazonaws.com/'
32 'v1/documentation/api/latest/guide/clients.html#waiters'
33 )
35 def document_waiters(self, section):
36 """Documents the various waiters for a service.
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>.rst
54 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)
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 )
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()
79 # Add information on the wait() method
80 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 )
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()
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 waiter
115 :param section: The section to write to
117 :param waiter_name: The name of the waiter
119 :param event_emitter: The event emitter to use to emit events
121 :param service_model: The service model
123 :param service_waiter_model: The waiter model associated to the service
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)
131 waiter_config_members = OrderedDict()
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 )
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 )
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 ]
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 )
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 )