Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/botocore/docs/params.py: 16%
149 statements
« 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.
13from botocore.docs.shape import ShapeDocumenter
14from botocore.docs.utils import py_type_name
17class BaseParamsDocumenter(ShapeDocumenter):
18 def document_params(self, section, shape, include=None, exclude=None):
19 """Fills out the documentation for a section given a model shape.
21 :param section: The section to write the documentation to.
23 :param shape: The shape of the operation.
25 :type include: Dictionary where keys are parameter names and
26 values are the shapes of the parameter names.
27 :param include: The parameter shapes to include in the documentation.
29 :type exclude: List of the names of the parameters to exclude.
30 :param exclude: The names of the parameters to exclude from
31 documentation.
32 """
33 history = []
34 self.traverse_and_document_shape(
35 section=section,
36 shape=shape,
37 history=history,
38 name=None,
39 include=include,
40 exclude=exclude,
41 )
43 def document_recursive_shape(self, section, shape, **kwargs):
44 self._add_member_documentation(section, shape, **kwargs)
46 def document_shape_default(
47 self, section, shape, history, include=None, exclude=None, **kwargs
48 ):
49 self._add_member_documentation(section, shape, **kwargs)
51 def document_shape_type_list(
52 self, section, shape, history, include=None, exclude=None, **kwargs
53 ):
54 self._add_member_documentation(section, shape, **kwargs)
55 param_shape = shape.member
56 param_section = section.add_new_section(
57 param_shape.name, context={'shape': shape.member.name}
58 )
59 self._start_nested_param(param_section)
60 self.traverse_and_document_shape(
61 section=param_section,
62 shape=param_shape,
63 history=history,
64 name=None,
65 )
66 section = section.add_new_section('end-list')
67 self._end_nested_param(section)
69 def document_shape_type_map(
70 self, section, shape, history, include=None, exclude=None, **kwargs
71 ):
72 self._add_member_documentation(section, shape, **kwargs)
74 key_section = section.add_new_section(
75 'key', context={'shape': shape.key.name}
76 )
77 self._start_nested_param(key_section)
78 self._add_member_documentation(key_section, shape.key)
80 param_section = section.add_new_section(
81 shape.value.name, context={'shape': shape.value.name}
82 )
83 param_section.style.indent()
84 self._start_nested_param(param_section)
85 self.traverse_and_document_shape(
86 section=param_section,
87 shape=shape.value,
88 history=history,
89 name=None,
90 )
92 end_section = section.add_new_section('end-map')
93 self._end_nested_param(end_section)
94 self._end_nested_param(end_section)
96 def document_shape_type_structure(
97 self,
98 section,
99 shape,
100 history,
101 include=None,
102 exclude=None,
103 name=None,
104 **kwargs,
105 ):
106 members = self._add_members_to_shape(shape.members, include)
107 self._add_member_documentation(section, shape, name=name)
108 for param in members:
109 if exclude and param in exclude:
110 continue
111 param_shape = members[param]
112 param_section = section.add_new_section(
113 param, context={'shape': param_shape.name}
114 )
115 self._start_nested_param(param_section)
116 self.traverse_and_document_shape(
117 section=param_section,
118 shape=param_shape,
119 history=history,
120 name=param,
121 )
122 section = section.add_new_section('end-structure')
123 self._end_nested_param(section)
125 def _add_member_documentation(self, section, shape, **kwargs):
126 pass
128 def _add_members_to_shape(self, members, include):
129 if include:
130 members = members.copy()
131 for param in include:
132 members[param.name] = param
133 return members
135 def _document_non_top_level_param_type(self, type_section, shape):
136 special_py_type = self._get_special_py_type_name(shape)
137 py_type = py_type_name(shape.type_name)
139 type_format = '(%s) --'
140 if special_py_type is not None:
141 # Special type can reference a linked class.
142 # Italicizing it blows away the link.
143 type_section.write(type_format % special_py_type)
144 else:
145 type_section.style.italics(type_format % py_type)
146 type_section.write(' ')
148 def _start_nested_param(self, section):
149 section.style.indent()
150 section.style.new_line()
152 def _end_nested_param(self, section):
153 section.style.dedent()
154 section.style.new_line()
157class ResponseParamsDocumenter(BaseParamsDocumenter):
158 """Generates the description for the response parameters"""
160 EVENT_NAME = 'response-params'
162 def _add_member_documentation(self, section, shape, name=None, **kwargs):
163 name_section = section.add_new_section('param-name')
164 name_section.write('- ')
165 if name is not None:
166 name_section.style.bold('%s' % name)
167 name_section.write(' ')
168 type_section = section.add_new_section('param-type')
169 self._document_non_top_level_param_type(type_section, shape)
171 documentation_section = section.add_new_section('param-documentation')
172 if shape.documentation:
173 documentation_section.style.indent()
174 if getattr(shape, 'is_tagged_union', False):
175 tagged_union_docs = section.add_new_section(
176 'param-tagged-union-docs'
177 )
178 note = (
179 '.. note::'
180 ' This is a Tagged Union structure. Only one of the '
181 ' following top level keys will be set: %s. '
182 ' If a client receives an unknown member it will '
183 ' set ``SDK_UNKNOWN_MEMBER`` as the top level key, '
184 ' which maps to the name or tag of the unknown '
185 ' member. The structure of ``SDK_UNKNOWN_MEMBER`` is '
186 ' as follows'
187 )
188 tagged_union_members_str = ', '.join(
189 ['``%s``' % key for key in shape.members.keys()]
190 )
191 unknown_code_example = (
192 '\'SDK_UNKNOWN_MEMBER\': '
193 '{\'name\': \'UnknownMemberName\'}'
194 )
195 tagged_union_docs.write(note % (tagged_union_members_str))
196 example = section.add_new_section('param-unknown-example')
197 example.style.codeblock(unknown_code_example)
198 documentation_section.include_doc_string(shape.documentation)
199 section.style.new_paragraph()
201 def document_shape_type_event_stream(
202 self, section, shape, history, **kwargs
203 ):
204 self.document_shape_type_structure(section, shape, history, **kwargs)
207class RequestParamsDocumenter(BaseParamsDocumenter):
208 """Generates the description for the request parameters"""
210 EVENT_NAME = 'request-params'
212 def document_shape_type_structure(
213 self, section, shape, history, include=None, exclude=None, **kwargs
214 ):
215 if len(history) > 1:
216 self._add_member_documentation(section, shape, **kwargs)
217 section.style.indent()
218 members = self._add_members_to_shape(shape.members, include)
219 for i, param in enumerate(members):
220 if exclude and param in exclude:
221 continue
222 param_shape = members[param]
223 param_section = section.add_new_section(
224 param, context={'shape': param_shape.name}
225 )
226 param_section.style.new_line()
227 is_required = param in shape.required_members
228 self.traverse_and_document_shape(
229 section=param_section,
230 shape=param_shape,
231 history=history,
232 name=param,
233 is_required=is_required,
234 )
235 section = section.add_new_section('end-structure')
236 if len(history) > 1:
237 section.style.dedent()
238 section.style.new_line()
240 def _add_member_documentation(
241 self,
242 section,
243 shape,
244 name=None,
245 is_top_level_param=False,
246 is_required=False,
247 **kwargs,
248 ):
249 py_type = self._get_special_py_type_name(shape)
250 if py_type is None:
251 py_type = py_type_name(shape.type_name)
252 if is_top_level_param:
253 type_section = section.add_new_section('param-type')
254 type_section.write(f':type {name}: {py_type}')
255 end_type_section = type_section.add_new_section('end-param-type')
256 end_type_section.style.new_line()
257 name_section = section.add_new_section('param-name')
258 name_section.write(':param %s: ' % name)
260 else:
261 name_section = section.add_new_section('param-name')
262 name_section.write('- ')
263 if name is not None:
264 name_section.style.bold('%s' % name)
265 name_section.write(' ')
266 type_section = section.add_new_section('param-type')
267 self._document_non_top_level_param_type(type_section, shape)
269 if is_required:
270 is_required_section = section.add_new_section('is-required')
271 is_required_section.style.indent()
272 is_required_section.style.bold('[REQUIRED]')
273 is_required_section.write(' ')
274 if shape.documentation:
275 documentation_section = section.add_new_section(
276 'param-documentation'
277 )
278 documentation_section.style.indent()
279 if getattr(shape, 'is_tagged_union', False):
280 tagged_union_docs = section.add_new_section(
281 'param-tagged-union-docs'
282 )
283 note = (
284 '.. note::'
285 ' This is a Tagged Union structure. Only one of the '
286 ' following top level keys can be set: %s. '
287 )
288 tagged_union_members_str = ', '.join(
289 ['``%s``' % key for key in shape.members.keys()]
290 )
291 tagged_union_docs.write(note % (tagged_union_members_str))
292 documentation_section.include_doc_string(shape.documentation)
293 self._add_special_trait_documentation(documentation_section, shape)
294 end_param_section = section.add_new_section('end-param')
295 end_param_section.style.new_paragraph()
297 def _add_special_trait_documentation(self, section, shape):
298 if 'idempotencyToken' in shape.metadata:
299 self._append_idempotency_documentation(section)
301 def _append_idempotency_documentation(self, section):
302 docstring = 'This field is autopopulated if not provided.'
303 section.write(docstring)