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.13 14 15# NOTE: This class should not be instantiated and its16# ``traverse_and_document_shape`` method called directly. It should be17# inherited from a Documenter class with the appropriate methods18# and attributes.19from botocore.utils import is_json_value_header20 21 22class ShapeDocumenter:23    EVENT_NAME = ''24 25    def __init__(26        self, service_name, operation_name, event_emitter, context=None27    ):28        self._service_name = service_name29        self._operation_name = operation_name30        self._event_emitter = event_emitter31        self._context = context32        if context is None:33            self._context = {'special_shape_types': {}}34 35    def traverse_and_document_shape(36        self,37        section,38        shape,39        history,40        include=None,41        exclude=None,42        name=None,43        is_required=False,44    ):45        """Traverses and documents a shape46 47        Will take a self class and call its appropriate methods as a shape48        is traversed.49 50        :param section: The section to document.51 52        :param history: A list of the names of the shapes that have been53            traversed.54 55        :type include: Dictionary where keys are parameter names and56            values are the shapes of the parameter names.57        :param include: The parameter shapes to include in the documentation.58 59        :type exclude: List of the names of the parameters to exclude.60        :param exclude: The names of the parameters to exclude from61            documentation.62 63        :param name: The name of the shape.64 65        :param is_required: If the shape is a required member.66        """67        param_type = shape.type_name68        if getattr(shape, 'serialization', {}).get('eventstream'):69            param_type = 'event_stream'70        if shape.name in history:71            self.document_recursive_shape(section, shape, name=name)72        else:73            history.append(shape.name)74            is_top_level_param = len(history) == 275            if hasattr(shape, 'is_document_type') and shape.is_document_type:76                param_type = 'document'77            getattr(78                self,79                f"document_shape_type_{param_type}",80                self.document_shape_default,81            )(82                section,83                shape,84                history=history,85                name=name,86                include=include,87                exclude=exclude,88                is_top_level_param=is_top_level_param,89                is_required=is_required,90            )91            if is_top_level_param:92                self._event_emitter.emit(93                    f"docs.{self.EVENT_NAME}.{self._service_name}.{self._operation_name}.{name}",94                    section=section,95                )96            at_overlying_method_section = len(history) == 197            if at_overlying_method_section:98                self._event_emitter.emit(99                    f"docs.{self.EVENT_NAME}.{self._service_name}.{self._operation_name}.complete-section",100                    section=section,101                )102            history.pop()103 104    def _get_special_py_default(self, shape):105        special_defaults = {106            'document_type': '{...}|[...]|123|123.4|\'string\'|True|None',107            'jsonvalue_header': '{...}|[...]|123|123.4|\'string\'|True|None',108            'streaming_input_shape': 'b\'bytes\'|file',109            'streaming_output_shape': 'StreamingBody()',110            'eventstream_output_shape': 'EventStream()',111        }112        return self._get_value_for_special_type(shape, special_defaults)113 114    def _get_special_py_type_name(self, shape):115        special_type_names = {116            'document_type': ':ref:`document<document>`',117            'jsonvalue_header': 'JSON serializable',118            'streaming_input_shape': 'bytes or seekable file-like object',119            'streaming_output_shape': ':class:`.StreamingBody`',120            'eventstream_output_shape': ':class:`.EventStream`',121        }122        return self._get_value_for_special_type(shape, special_type_names)123 124    def _get_value_for_special_type(self, shape, special_type_map):125        if is_json_value_header(shape):126            return special_type_map['jsonvalue_header']127        if hasattr(shape, 'is_document_type') and shape.is_document_type:128            return special_type_map['document_type']129        for special_type, marked_shape in self._context[130            'special_shape_types'131        ].items():132            if special_type in special_type_map:133                if shape == marked_shape:134                    return special_type_map[special_type]135        return None136