Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/boto3/docs/action.py: 27%

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# https://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. 

13import os 

14 

15from botocore import xform_name 

16from botocore.docs.bcdoc.restdoc import DocumentStructure 

17from botocore.docs.method import ( 

18 document_custom_method, 

19 document_model_driven_method, 

20) 

21from botocore.model import OperationModel 

22from botocore.utils import get_service_module_name 

23 

24from boto3.docs.base import NestedDocumenter 

25from boto3.docs.method import document_model_driven_resource_method 

26from boto3.docs.utils import ( 

27 add_resource_type_overview, 

28 get_resource_ignore_params, 

29 get_resource_public_actions, 

30) 

31 

32PUT_DATA_WARNING_MESSAGE = """ 

33.. warning:: 

34 It is recommended to use the :py:meth:`put_metric_data` 

35 :doc:`client method <../../cloudwatch/client/put_metric_data>` 

36 instead. If you would still like to use this resource method, 

37 please make sure that ``MetricData[].MetricName`` is equal to 

38 the metric resource's ``name`` attribute. 

39""" 

40 

41WARNING_MESSAGES = { 

42 "Metric": {"put_data": PUT_DATA_WARNING_MESSAGE}, 

43} 

44 

45IGNORE_PARAMS = {"Metric": {"put_data": ["Namespace"]}} 

46 

47 

48class ActionDocumenter(NestedDocumenter): 

49 def document_actions(self, section): 

50 modeled_actions_list = self._resource_model.actions 

51 modeled_actions = {} 

52 for modeled_action in modeled_actions_list: 

53 modeled_actions[modeled_action.name] = modeled_action 

54 resource_actions = get_resource_public_actions( 

55 self._resource.__class__ 

56 ) 

57 self.member_map['actions'] = sorted(resource_actions) 

58 add_resource_type_overview( 

59 section=section, 

60 resource_type='Actions', 

61 description=( 

62 'Actions call operations on resources. They may ' 

63 'automatically handle the passing in of arguments set ' 

64 'from identifiers and some attributes.' 

65 ), 

66 intro_link='actions_intro', 

67 ) 

68 resource_warnings = WARNING_MESSAGES.get(self._resource_name, {}) 

69 for action_name in sorted(resource_actions): 

70 # Create a new DocumentStructure for each action and add contents. 

71 action_doc = DocumentStructure(action_name, target='html') 

72 breadcrumb_section = action_doc.add_new_section('breadcrumb') 

73 breadcrumb_section.style.ref(self._resource_class_name, 'index') 

74 breadcrumb_section.write(f' / Action / {action_name}') 

75 action_doc.add_title_section(action_name) 

76 warning_message = resource_warnings.get(action_name) 

77 if warning_message is not None: 

78 action_doc.add_new_section("warning").write(warning_message) 

79 action_section = action_doc.add_new_section( 

80 action_name, 

81 context={'qualifier': f'{self.class_name}.'}, 

82 ) 

83 if action_name in ['load', 'reload'] and self._resource_model.load: 

84 document_load_reload_action( 

85 section=action_section, 

86 action_name=action_name, 

87 resource_name=self._resource_name, 

88 event_emitter=self._resource.meta.client.meta.events, 

89 load_model=self._resource_model.load, 

90 service_model=self._service_model, 

91 ) 

92 elif action_name in modeled_actions: 

93 document_action( 

94 section=action_section, 

95 resource_name=self._resource_name, 

96 event_emitter=self._resource.meta.client.meta.events, 

97 action_model=modeled_actions[action_name], 

98 service_model=self._service_model, 

99 ) 

100 else: 

101 document_custom_method( 

102 action_section, action_name, resource_actions[action_name] 

103 ) 

104 # Write actions in individual/nested files. 

105 # Path: <root>/reference/services/<service>/<resource_name>/<action_name>.rst 

106 actions_dir_path = os.path.join( 

107 self._root_docs_path, 

108 f'{self._service_name}', 

109 f'{self._resource_sub_path}', 

110 ) 

111 action_doc.write_to_file(actions_dir_path, action_name) 

112 

113 

114def document_action( 

115 section, 

116 resource_name, 

117 event_emitter, 

118 action_model, 

119 service_model, 

120 include_signature=True, 

121): 

122 """Documents a resource action 

123 

124 :param section: The section to write to 

125 

126 :param resource_name: The name of the resource 

127 

128 :param event_emitter: The event emitter to use to emit events 

129 

130 :param action_model: The model of the action 

131 

132 :param service_model: The model of the service 

133 

134 :param include_signature: Whether or not to include the signature. 

135 It is useful for generating docstrings. 

136 """ 

137 operation_model = service_model.operation_model( 

138 action_model.request.operation 

139 ) 

140 ignore_params = IGNORE_PARAMS.get(resource_name, {}).get( 

141 action_model.name, 

142 get_resource_ignore_params(action_model.request.params), 

143 ) 

144 example_return_value = 'response' 

145 if action_model.resource: 

146 example_return_value = xform_name(action_model.resource.type) 

147 example_resource_name = xform_name(resource_name) 

148 if service_model.service_name == resource_name: 

149 example_resource_name = resource_name 

150 example_prefix = '{} = {}.{}'.format( 

151 example_return_value, example_resource_name, action_model.name 

152 ) 

153 full_action_name = ( 

154 f"{section.context.get('qualifier', '')}{action_model.name}" 

155 ) 

156 document_model_driven_resource_method( 

157 section=section, 

158 method_name=full_action_name, 

159 operation_model=operation_model, 

160 event_emitter=event_emitter, 

161 method_description=operation_model.documentation, 

162 example_prefix=example_prefix, 

163 exclude_input=ignore_params, 

164 resource_action_model=action_model, 

165 include_signature=include_signature, 

166 ) 

167 

168 

169def document_load_reload_action( 

170 section, 

171 action_name, 

172 resource_name, 

173 event_emitter, 

174 load_model, 

175 service_model, 

176 include_signature=True, 

177): 

178 """Documents the resource load action 

179 

180 :param section: The section to write to 

181 

182 :param action_name: The name of the loading action should be load or reload 

183 

184 :param resource_name: The name of the resource 

185 

186 :param event_emitter: The event emitter to use to emit events 

187 

188 :param load_model: The model of the load action 

189 

190 :param service_model: The model of the service 

191 

192 :param include_signature: Whether or not to include the signature. 

193 It is useful for generating docstrings. 

194 """ 

195 description = ( 

196 'Calls :py:meth:`{}.Client.{}` to update the attributes of the ' 

197 '{} resource. Note that the load and reload methods are ' 

198 'the same method and can be used interchangeably.'.format( 

199 get_service_module_name(service_model), 

200 xform_name(load_model.request.operation), 

201 resource_name, 

202 ) 

203 ) 

204 example_resource_name = xform_name(resource_name) 

205 if service_model.service_name == resource_name: 

206 example_resource_name = resource_name 

207 example_prefix = f'{example_resource_name}.{action_name}' 

208 full_action_name = f"{section.context.get('qualifier', '')}{action_name}" 

209 document_model_driven_method( 

210 section=section, 

211 method_name=full_action_name, 

212 operation_model=OperationModel({}, service_model), 

213 event_emitter=event_emitter, 

214 method_description=description, 

215 example_prefix=example_prefix, 

216 include_signature=include_signature, 

217 )