Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/botocore/docs/params.py: 16%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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(f'{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 [f'``{key}``' for key in shape.members.keys()]
190 )
191 unknown_code_example = (
192 '\'SDK_UNKNOWN_MEMBER\': {\'name\': \'UnknownMemberName\'}'
193 )
194 tagged_union_docs.write(note % (tagged_union_members_str))
195 example = section.add_new_section('param-unknown-example')
196 example.style.codeblock(unknown_code_example)
197 documentation_section.include_doc_string(shape.documentation)
198 section.style.new_paragraph()
200 def document_shape_type_event_stream(
201 self, section, shape, history, **kwargs
202 ):
203 self.document_shape_type_structure(section, shape, history, **kwargs)
206class RequestParamsDocumenter(BaseParamsDocumenter):
207 """Generates the description for the request parameters"""
209 EVENT_NAME = 'request-params'
211 def document_shape_type_structure(
212 self, section, shape, history, include=None, exclude=None, **kwargs
213 ):
214 if len(history) > 1:
215 self._add_member_documentation(section, shape, **kwargs)
216 section.style.indent()
217 members = self._add_members_to_shape(shape.members, include)
218 for i, param in enumerate(members):
219 if exclude and param in exclude:
220 continue
221 param_shape = members[param]
222 param_section = section.add_new_section(
223 param, context={'shape': param_shape.name}
224 )
225 param_section.style.new_line()
226 is_required = param in shape.required_members
227 self.traverse_and_document_shape(
228 section=param_section,
229 shape=param_shape,
230 history=history,
231 name=param,
232 is_required=is_required,
233 )
234 section = section.add_new_section('end-structure')
235 if len(history) > 1:
236 section.style.dedent()
237 section.style.new_line()
239 def _add_member_documentation(
240 self,
241 section,
242 shape,
243 name=None,
244 is_top_level_param=False,
245 is_required=False,
246 **kwargs,
247 ):
248 py_type = self._get_special_py_type_name(shape)
249 if py_type is None:
250 py_type = py_type_name(shape.type_name)
251 if is_top_level_param:
252 type_section = section.add_new_section('param-type')
253 type_section.write(f':type {name}: {py_type}')
254 end_type_section = type_section.add_new_section('end-param-type')
255 end_type_section.style.new_line()
256 name_section = section.add_new_section('param-name')
257 name_section.write(f':param {name}: ')
259 else:
260 name_section = section.add_new_section('param-name')
261 name_section.write('- ')
262 if name is not None:
263 name_section.style.bold(f'{name}')
264 name_section.write(' ')
265 type_section = section.add_new_section('param-type')
266 self._document_non_top_level_param_type(type_section, shape)
268 if is_required:
269 is_required_section = section.add_new_section('is-required')
270 is_required_section.style.indent()
271 is_required_section.style.bold('[REQUIRED]')
272 is_required_section.write(' ')
273 if shape.documentation:
274 documentation_section = section.add_new_section(
275 'param-documentation'
276 )
277 documentation_section.style.indent()
278 if getattr(shape, 'is_tagged_union', False):
279 tagged_union_docs = section.add_new_section(
280 'param-tagged-union-docs'
281 )
282 note = (
283 '.. note::'
284 ' This is a Tagged Union structure. Only one of the '
285 ' following top level keys can be set: %s. '
286 )
287 tagged_union_members_str = ', '.join(
288 [f'``{key}``' for key in shape.members.keys()]
289 )
290 tagged_union_docs.write(note % (tagged_union_members_str))
291 documentation_section.include_doc_string(shape.documentation)
292 self._add_special_trait_documentation(documentation_section, shape)
293 end_param_section = section.add_new_section('end-param')
294 end_param_section.style.new_paragraph()
296 def _add_special_trait_documentation(self, section, shape):
297 if 'idempotencyToken' in shape.metadata:
298 self._append_idempotency_documentation(section)
300 def _append_idempotency_documentation(self, section):
301 docstring = 'This field is autopopulated if not provided.'
302 section.write(docstring)