diff options
Diffstat (limited to '.venv/lib/python3.12/site-packages/botocore/docs/params.py')
| -rw-r--r-- | .venv/lib/python3.12/site-packages/botocore/docs/params.py | 303 |
1 files changed, 303 insertions, 0 deletions
diff --git a/.venv/lib/python3.12/site-packages/botocore/docs/params.py b/.venv/lib/python3.12/site-packages/botocore/docs/params.py new file mode 100644 index 00000000..74747ec2 --- /dev/null +++ b/.venv/lib/python3.12/site-packages/botocore/docs/params.py @@ -0,0 +1,303 @@ +# Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"). You +# may not use this file except in compliance with the License. A copy of +# the License is located at +# +# http://aws.amazon.com/apache2.0/ +# +# or in the "license" file accompanying this file. This file is +# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF +# ANY KIND, either express or implied. See the License for the specific +# language governing permissions and limitations under the License. +from botocore.docs.shape import ShapeDocumenter +from botocore.docs.utils import py_type_name + + +class BaseParamsDocumenter(ShapeDocumenter): + def document_params(self, section, shape, include=None, exclude=None): + """Fills out the documentation for a section given a model shape. + + :param section: The section to write the documentation to. + + :param shape: The shape of the operation. + + :type include: Dictionary where keys are parameter names and + values are the shapes of the parameter names. + :param include: The parameter shapes to include in the documentation. + + :type exclude: List of the names of the parameters to exclude. + :param exclude: The names of the parameters to exclude from + documentation. + """ + history = [] + self.traverse_and_document_shape( + section=section, + shape=shape, + history=history, + name=None, + include=include, + exclude=exclude, + ) + + def document_recursive_shape(self, section, shape, **kwargs): + self._add_member_documentation(section, shape, **kwargs) + + def document_shape_default( + self, section, shape, history, include=None, exclude=None, **kwargs + ): + self._add_member_documentation(section, shape, **kwargs) + + def document_shape_type_list( + self, section, shape, history, include=None, exclude=None, **kwargs + ): + self._add_member_documentation(section, shape, **kwargs) + param_shape = shape.member + param_section = section.add_new_section( + param_shape.name, context={'shape': shape.member.name} + ) + self._start_nested_param(param_section) + self.traverse_and_document_shape( + section=param_section, + shape=param_shape, + history=history, + name=None, + ) + section = section.add_new_section('end-list') + self._end_nested_param(section) + + def document_shape_type_map( + self, section, shape, history, include=None, exclude=None, **kwargs + ): + self._add_member_documentation(section, shape, **kwargs) + + key_section = section.add_new_section( + 'key', context={'shape': shape.key.name} + ) + self._start_nested_param(key_section) + self._add_member_documentation(key_section, shape.key) + + param_section = section.add_new_section( + shape.value.name, context={'shape': shape.value.name} + ) + param_section.style.indent() + self._start_nested_param(param_section) + self.traverse_and_document_shape( + section=param_section, + shape=shape.value, + history=history, + name=None, + ) + + end_section = section.add_new_section('end-map') + self._end_nested_param(end_section) + self._end_nested_param(end_section) + + def document_shape_type_structure( + self, + section, + shape, + history, + include=None, + exclude=None, + name=None, + **kwargs, + ): + members = self._add_members_to_shape(shape.members, include) + self._add_member_documentation(section, shape, name=name) + for param in members: + if exclude and param in exclude: + continue + param_shape = members[param] + param_section = section.add_new_section( + param, context={'shape': param_shape.name} + ) + self._start_nested_param(param_section) + self.traverse_and_document_shape( + section=param_section, + shape=param_shape, + history=history, + name=param, + ) + section = section.add_new_section('end-structure') + self._end_nested_param(section) + + def _add_member_documentation(self, section, shape, **kwargs): + pass + + def _add_members_to_shape(self, members, include): + if include: + members = members.copy() + for param in include: + members[param.name] = param + return members + + def _document_non_top_level_param_type(self, type_section, shape): + special_py_type = self._get_special_py_type_name(shape) + py_type = py_type_name(shape.type_name) + + type_format = '(%s) --' + if special_py_type is not None: + # Special type can reference a linked class. + # Italicizing it blows away the link. + type_section.write(type_format % special_py_type) + else: + type_section.style.italics(type_format % py_type) + type_section.write(' ') + + def _start_nested_param(self, section): + section.style.indent() + section.style.new_line() + + def _end_nested_param(self, section): + section.style.dedent() + section.style.new_line() + + +class ResponseParamsDocumenter(BaseParamsDocumenter): + """Generates the description for the response parameters""" + + EVENT_NAME = 'response-params' + + def _add_member_documentation(self, section, shape, name=None, **kwargs): + name_section = section.add_new_section('param-name') + name_section.write('- ') + if name is not None: + name_section.style.bold(f'{name}') + name_section.write(' ') + type_section = section.add_new_section('param-type') + self._document_non_top_level_param_type(type_section, shape) + + documentation_section = section.add_new_section('param-documentation') + if shape.documentation: + documentation_section.style.indent() + if getattr(shape, 'is_tagged_union', False): + tagged_union_docs = section.add_new_section( + 'param-tagged-union-docs' + ) + note = ( + '.. note::' + ' This is a Tagged Union structure. Only one of the ' + ' following top level keys will be set: %s. ' + ' If a client receives an unknown member it will ' + ' set ``SDK_UNKNOWN_MEMBER`` as the top level key, ' + ' which maps to the name or tag of the unknown ' + ' member. The structure of ``SDK_UNKNOWN_MEMBER`` is ' + ' as follows' + ) + tagged_union_members_str = ', '.join( + [f'``{key}``' for key in shape.members.keys()] + ) + unknown_code_example = ( + '\'SDK_UNKNOWN_MEMBER\': ' + '{\'name\': \'UnknownMemberName\'}' + ) + tagged_union_docs.write(note % (tagged_union_members_str)) + example = section.add_new_section('param-unknown-example') + example.style.codeblock(unknown_code_example) + documentation_section.include_doc_string(shape.documentation) + section.style.new_paragraph() + + def document_shape_type_event_stream( + self, section, shape, history, **kwargs + ): + self.document_shape_type_structure(section, shape, history, **kwargs) + + +class RequestParamsDocumenter(BaseParamsDocumenter): + """Generates the description for the request parameters""" + + EVENT_NAME = 'request-params' + + def document_shape_type_structure( + self, section, shape, history, include=None, exclude=None, **kwargs + ): + if len(history) > 1: + self._add_member_documentation(section, shape, **kwargs) + section.style.indent() + members = self._add_members_to_shape(shape.members, include) + for i, param in enumerate(members): + if exclude and param in exclude: + continue + param_shape = members[param] + param_section = section.add_new_section( + param, context={'shape': param_shape.name} + ) + param_section.style.new_line() + is_required = param in shape.required_members + self.traverse_and_document_shape( + section=param_section, + shape=param_shape, + history=history, + name=param, + is_required=is_required, + ) + section = section.add_new_section('end-structure') + if len(history) > 1: + section.style.dedent() + section.style.new_line() + + def _add_member_documentation( + self, + section, + shape, + name=None, + is_top_level_param=False, + is_required=False, + **kwargs, + ): + py_type = self._get_special_py_type_name(shape) + if py_type is None: + py_type = py_type_name(shape.type_name) + if is_top_level_param: + type_section = section.add_new_section('param-type') + type_section.write(f':type {name}: {py_type}') + end_type_section = type_section.add_new_section('end-param-type') + end_type_section.style.new_line() + name_section = section.add_new_section('param-name') + name_section.write(f':param {name}: ') + + else: + name_section = section.add_new_section('param-name') + name_section.write('- ') + if name is not None: + name_section.style.bold(f'{name}') + name_section.write(' ') + type_section = section.add_new_section('param-type') + self._document_non_top_level_param_type(type_section, shape) + + if is_required: + is_required_section = section.add_new_section('is-required') + is_required_section.style.indent() + is_required_section.style.bold('[REQUIRED]') + is_required_section.write(' ') + if shape.documentation: + documentation_section = section.add_new_section( + 'param-documentation' + ) + documentation_section.style.indent() + if getattr(shape, 'is_tagged_union', False): + tagged_union_docs = section.add_new_section( + 'param-tagged-union-docs' + ) + note = ( + '.. note::' + ' This is a Tagged Union structure. Only one of the ' + ' following top level keys can be set: %s. ' + ) + tagged_union_members_str = ', '.join( + [f'``{key}``' for key in shape.members.keys()] + ) + tagged_union_docs.write(note % (tagged_union_members_str)) + documentation_section.include_doc_string(shape.documentation) + self._add_special_trait_documentation(documentation_section, shape) + end_param_section = section.add_new_section('end-param') + end_param_section.style.new_paragraph() + + def _add_special_trait_documentation(self, section, shape): + if 'idempotencyToken' in shape.metadata: + self._append_idempotency_documentation(section) + + def _append_idempotency_documentation(self, section): + docstring = 'This field is autopopulated if not provided.' + section.write(docstring) |