codekingpro/portable-devtools

1# Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.2#3# Licensed under the Apache License, Version 2.0 (the "License"). You4# may not use this file except in compliance with the License. A copy of5# the License is located at6#7# http://aws.amazon.com/apache2.0/8#9# or in the "license" file accompanying this file. This file is10# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF11# ANY KIND, either express or implied. See the License for the specific12# language governing permissions and limitations under the License.13from botocore.docs.shape import ShapeDocumenter14from botocore.docs.utils import py_type_name15 16 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.20 21        :param section: The section to write the documentation to.22 23        :param shape: The shape of the operation.24 25        :type include: Dictionary where keys are parameter names and26            values are the shapes of the parameter names.27        :param include: The parameter shapes to include in the documentation.28 29        :type exclude: List of the names of the parameters to exclude.30        :param exclude: The names of the parameters to exclude from31            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        )42 43    def document_recursive_shape(self, section, shape, **kwargs):44        self._add_member_documentation(section, shape, **kwargs)45 46    def document_shape_default(47        self, section, shape, history, include=None, exclude=None, **kwargs48    ):49        self._add_member_documentation(section, shape, **kwargs)50 51    def document_shape_type_list(52        self, section, shape, history, include=None, exclude=None, **kwargs53    ):54        self._add_member_documentation(section, shape, **kwargs)55        param_shape = shape.member56        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)68 69    def document_shape_type_map(70        self, section, shape, history, include=None, exclude=None, **kwargs71    ):72        self._add_member_documentation(section, shape, **kwargs)73 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)79 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        )91 92        end_section = section.add_new_section('end-map')93        self._end_nested_param(end_section)94        self._end_nested_param(end_section)95 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                continue111            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)124 125    def _add_member_documentation(self, section, shape, **kwargs):126        pass127 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] = param133        return members134 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)138 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(' ')147 148    def _start_nested_param(self, section):149        section.style.indent()150        section.style.new_line()151 152    def _end_nested_param(self, section):153        section.style.dedent()154        section.style.new_line()155 156 157class ResponseParamsDocumenter(BaseParamsDocumenter):158    """Generates the description for the response parameters"""159 160    EVENT_NAME = 'response-params'161 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)170 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()200 201    def document_shape_type_event_stream(202        self, section, shape, history, **kwargs203    ):204        self.document_shape_type_structure(section, shape, history, **kwargs)205 206 207class RequestParamsDocumenter(BaseParamsDocumenter):208    """Generates the description for the request parameters"""209 210    EVENT_NAME = 'request-params'211 212    def document_shape_type_structure(213        self, section, shape, history, include=None, exclude=None, **kwargs214    ):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                continue222            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_members228            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()239 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)259 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)268 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()296 297    def _add_special_trait_documentation(self, section, shape):298        if 'idempotencyToken' in shape.metadata:299            self._append_idempotency_documentation(section)300 301    def _append_idempotency_documentation(self, section):302        docstring = 'This field is autopopulated if not provided.'303        section.write(docstring)304