Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/botocore/docs/shape.py: 19%

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. 

13 

14 

15# NOTE: This class should not be instantiated and its 

16# ``traverse_and_document_shape`` method called directly. It should be 

17# inherited from a Documenter class with the appropriate methods 

18# and attributes. 

19from botocore.utils import is_json_value_header 

20 

21 

22class ShapeDocumenter: 

23 EVENT_NAME = '' 

24 

25 def __init__( 

26 self, service_name, operation_name, event_emitter, context=None 

27 ): 

28 self._service_name = service_name 

29 self._operation_name = operation_name 

30 self._event_emitter = event_emitter 

31 self._context = context 

32 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 shape 

46 

47 Will take a self class and call its appropriate methods as a shape 

48 is traversed. 

49 

50 :param section: The section to document. 

51 

52 :param history: A list of the names of the shapes that have been 

53 traversed. 

54 

55 :type include: Dictionary where keys are parameter names and 

56 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 from 

61 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_name 

68 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) == 2 

75 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) == 1 

97 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 None