Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/botocore/docs/example.py: 16%
129 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_default
17class BaseExampleDocumenter(ShapeDocumenter):
18 def document_example(
19 self, section, shape, prefix=None, include=None, exclude=None
20 ):
21 """Generates an example based on a shape
23 :param section: The section to write the documentation to.
25 :param shape: The shape of the operation.
27 :param prefix: Anything to be included before the example
29 :type include: Dictionary where keys are parameter names and
30 values are the shapes of the parameter names.
31 :param include: The parameter shapes to include in the documentation.
33 :type exclude: List of the names of the parameters to exclude.
34 :param exclude: The names of the parameters to exclude from
35 documentation.
36 """
37 history = []
38 section.style.new_line()
39 section.style.start_codeblock()
40 if prefix is not None:
41 section.write(prefix)
42 self.traverse_and_document_shape(
43 section=section,
44 shape=shape,
45 history=history,
46 include=include,
47 exclude=exclude,
48 )
49 final_blank_line_section = section.add_new_section('final-blank-line')
50 final_blank_line_section.style.new_line()
52 def document_recursive_shape(self, section, shape, **kwargs):
53 section.write('{\'... recursive ...\'}')
55 def document_shape_default(
56 self, section, shape, history, include=None, exclude=None, **kwargs
57 ):
58 py_type = self._get_special_py_default(shape)
59 if py_type is None:
60 py_type = py_default(shape.type_name)
62 if self._context.get('streaming_shape') == shape:
63 py_type = 'StreamingBody()'
64 section.write(py_type)
66 def document_shape_type_string(
67 self, section, shape, history, include=None, exclude=None, **kwargs
68 ):
69 if 'enum' in shape.metadata:
70 for i, enum in enumerate(shape.metadata['enum']):
71 section.write('\'%s\'' % enum)
72 if i < len(shape.metadata['enum']) - 1:
73 section.write('|')
74 else:
75 self.document_shape_default(section, shape, history)
77 def document_shape_type_list(
78 self, section, shape, history, include=None, exclude=None, **kwargs
79 ):
80 param_shape = shape.member
81 list_section = section.add_new_section('list-value')
82 self._start_nested_param(list_section, '[')
83 param_section = list_section.add_new_section(
84 'member', context={'shape': param_shape.name}
85 )
86 self.traverse_and_document_shape(
87 section=param_section, shape=param_shape, history=history
88 )
89 ending_comma_section = list_section.add_new_section('ending-comma')
90 ending_comma_section.write(',')
91 ending_bracket_section = list_section.add_new_section('ending-bracket')
92 self._end_nested_param(ending_bracket_section, ']')
94 def document_shape_type_structure(
95 self, section, shape, history, include=None, exclude=None, **kwargs
96 ):
97 if not shape.members:
98 section.write('{}')
99 return
101 section = section.add_new_section('structure-value')
102 self._start_nested_param(section, '{')
104 input_members = self._add_members_to_shape(shape.members, include)
106 for i, param in enumerate(input_members):
107 if exclude and param in exclude:
108 continue
109 param_section = section.add_new_section(param)
110 param_section.write('\'%s\': ' % param)
111 param_shape = input_members[param]
112 param_value_section = param_section.add_new_section(
113 'member-value', context={'shape': param_shape.name}
114 )
115 self.traverse_and_document_shape(
116 section=param_value_section,
117 shape=param_shape,
118 history=history,
119 name=param,
120 )
121 if i < len(input_members) - 1:
122 ending_comma_section = param_section.add_new_section(
123 'ending-comma'
124 )
125 ending_comma_section.write(',')
126 ending_comma_section.style.new_line()
127 self._end_structure(section, '{', '}')
129 def document_shape_type_map(
130 self, section, shape, history, include=None, exclude=None, **kwargs
131 ):
132 map_section = section.add_new_section('map-value')
133 self._start_nested_param(map_section, '{')
134 value_shape = shape.value
135 key_section = map_section.add_new_section(
136 'key', context={'shape': shape.key.name}
137 )
138 key_section.write('\'string\': ')
139 value_section = map_section.add_new_section(
140 'value', context={'shape': value_shape.name}
141 )
142 self.traverse_and_document_shape(
143 section=value_section, shape=value_shape, history=history
144 )
145 end_bracket_section = map_section.add_new_section('ending-bracket')
146 self._end_nested_param(end_bracket_section, '}')
148 def _add_members_to_shape(self, members, include):
149 if include:
150 members = members.copy()
151 for param in include:
152 members[param.name] = param
153 return members
155 def _start_nested_param(self, section, start=None):
156 if start is not None:
157 section.write(start)
158 section.style.indent()
159 section.style.indent()
160 section.style.new_line()
162 def _end_nested_param(self, section, end=None):
163 section.style.dedent()
164 section.style.dedent()
165 section.style.new_line()
166 if end is not None:
167 section.write(end)
169 def _end_structure(self, section, start, end):
170 # If there are no members in the strucuture, then make sure the
171 # start and the end bracket are on the same line, by removing all
172 # previous text and writing the start and end.
173 if not section.available_sections:
174 section.clear_text()
175 section.write(start + end)
176 self._end_nested_param(section)
177 else:
178 end_bracket_section = section.add_new_section('ending-bracket')
179 self._end_nested_param(end_bracket_section, end)
182class ResponseExampleDocumenter(BaseExampleDocumenter):
183 EVENT_NAME = 'response-example'
185 def document_shape_type_event_stream(
186 self, section, shape, history, **kwargs
187 ):
188 section.write('EventStream(')
189 self.document_shape_type_structure(section, shape, history, **kwargs)
190 end_section = section.add_new_section('event-stream-end')
191 end_section.write(')')
194class RequestExampleDocumenter(BaseExampleDocumenter):
195 EVENT_NAME = 'request-example'
197 def document_shape_type_structure(
198 self, section, shape, history, include=None, exclude=None, **kwargs
199 ):
200 param_format = '\'%s\''
201 operator = ': '
202 start = '{'
203 end = '}'
205 if len(history) <= 1:
206 operator = '='
207 start = '('
208 end = ')'
209 param_format = '%s'
210 section = section.add_new_section('structure-value')
211 self._start_nested_param(section, start)
212 input_members = self._add_members_to_shape(shape.members, include)
214 for i, param in enumerate(input_members):
215 if exclude and param in exclude:
216 continue
217 param_section = section.add_new_section(param)
218 param_section.write(param_format % param)
219 param_section.write(operator)
220 param_shape = input_members[param]
221 param_value_section = param_section.add_new_section(
222 'member-value', context={'shape': param_shape.name}
223 )
224 self.traverse_and_document_shape(
225 section=param_value_section,
226 shape=param_shape,
227 history=history,
228 name=param,
229 )
230 if i < len(input_members) - 1:
231 ending_comma_section = param_section.add_new_section(
232 'ending-comma'
233 )
234 ending_comma_section.write(',')
235 ending_comma_section.style.new_line()
236 self._end_structure(section, start, end)