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

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 get_instance_public_methods 

18from botocore.docs.utils import DocumentedShape 

19 

20from boto3.docs.base import NestedDocumenter 

21from boto3.docs.method import document_model_driven_resource_method 

22from boto3.docs.utils import ( 

23 add_resource_type_overview, 

24 get_resource_ignore_params, 

25) 

26 

27 

28class CollectionDocumenter(NestedDocumenter): 

29 def document_collections(self, section): 

30 collections = self._resource.meta.resource_model.collections 

31 collections_list = [] 

32 add_resource_type_overview( 

33 section=section, 

34 resource_type='Collections', 

35 description=( 

36 'Collections provide an interface to iterate over and ' 

37 'manipulate groups of resources. ' 

38 ), 

39 intro_link='guide_collections', 

40 ) 

41 self.member_map['collections'] = collections_list 

42 for collection in collections: 

43 collections_list.append(collection.name) 

44 # Create a new DocumentStructure for each collection and add contents. 

45 collection_doc = DocumentStructure(collection.name, target='html') 

46 breadcrumb_section = collection_doc.add_new_section('breadcrumb') 

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

48 breadcrumb_section.write(f' / Collection / {collection.name}') 

49 collection_doc.add_title_section(collection.name) 

50 collection_section = collection_doc.add_new_section( 

51 collection.name, 

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

53 ) 

54 self._document_collection(collection_section, collection) 

55 

56 # Write collections in individual/nested files. 

57 # Path: <root>/reference/services/<service>/<resource_name>/<collection_name>.rst 

58 collections_dir_path = os.path.join( 

59 self._root_docs_path, 

60 f'{self._service_name}', 

61 f'{self._resource_sub_path}', 

62 ) 

63 collection_doc.write_to_file(collections_dir_path, collection.name) 

64 

65 def _document_collection(self, section, collection): 

66 methods = get_instance_public_methods( 

67 getattr(self._resource, collection.name) 

68 ) 

69 document_collection_object(section, collection) 

70 batch_actions = {} 

71 for batch_action in collection.batch_actions: 

72 batch_actions[batch_action.name] = batch_action 

73 

74 for method in sorted(methods): 

75 method_section = section.add_new_section(method) 

76 if method in batch_actions: 

77 document_batch_action( 

78 section=method_section, 

79 resource_name=self._resource_name, 

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

81 batch_action_model=batch_actions[method], 

82 collection_model=collection, 

83 service_model=self._resource.meta.client.meta.service_model, 

84 ) 

85 else: 

86 document_collection_method( 

87 section=method_section, 

88 resource_name=self._resource_name, 

89 action_name=method, 

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

91 collection_model=collection, 

92 service_model=self._resource.meta.client.meta.service_model, 

93 ) 

94 

95 

96def document_collection_object( 

97 section, 

98 collection_model, 

99 include_signature=True, 

100): 

101 """Documents a collection resource object 

102 

103 :param section: The section to write to 

104 

105 :param collection_model: The model of the collection 

106 

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

108 It is useful for generating docstrings. 

109 """ 

110 if include_signature: 

111 full_collection_name = ( 

112 f"{section.context.get('qualifier', '')}{collection_model.name}" 

113 ) 

114 section.style.start_sphinx_py_attr(full_collection_name) 

115 section.include_doc_string( 

116 f'A collection of {collection_model.resource.type} resources.' 

117 ) 

118 section.include_doc_string( 

119 f'A {collection_model.resource.type} Collection will include all ' 

120 f'resources by default, and extreme caution should be taken when ' 

121 f'performing actions on all resources.' 

122 ) 

123 

124 

125def document_batch_action( 

126 section, 

127 resource_name, 

128 event_emitter, 

129 batch_action_model, 

130 service_model, 

131 collection_model, 

132 include_signature=True, 

133): 

134 """Documents a collection's batch action 

135 

136 :param section: The section to write to 

137 

138 :param resource_name: The name of the resource 

139 

140 :param action_name: The name of collection action. Currently only 

141 can be all, filter, limit, or page_size 

142 

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

144 

145 :param batch_action_model: The model of the batch action 

146 

147 :param collection_model: The model of the collection 

148 

149 :param service_model: The model of the service 

150 

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

152 It is useful for generating docstrings. 

153 """ 

154 operation_model = service_model.operation_model( 

155 batch_action_model.request.operation 

156 ) 

157 ignore_params = get_resource_ignore_params( 

158 batch_action_model.request.params 

159 ) 

160 

161 example_return_value = 'response' 

162 if batch_action_model.resource: 

163 example_return_value = xform_name(batch_action_model.resource.type) 

164 

165 example_resource_name = xform_name(resource_name) 

166 if service_model.service_name == resource_name: 

167 example_resource_name = resource_name 

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

169 example_return_value, 

170 example_resource_name, 

171 collection_model.name, 

172 batch_action_model.name, 

173 ) 

174 document_model_driven_resource_method( 

175 section=section, 

176 method_name=batch_action_model.name, 

177 operation_model=operation_model, 

178 event_emitter=event_emitter, 

179 method_description=operation_model.documentation, 

180 example_prefix=example_prefix, 

181 exclude_input=ignore_params, 

182 resource_action_model=batch_action_model, 

183 include_signature=include_signature, 

184 ) 

185 

186 

187def document_collection_method( 

188 section, 

189 resource_name, 

190 action_name, 

191 event_emitter, 

192 collection_model, 

193 service_model, 

194 include_signature=True, 

195): 

196 """Documents a collection method 

197 

198 :param section: The section to write to 

199 

200 :param resource_name: The name of the resource 

201 

202 :param action_name: The name of collection action. Currently only 

203 can be all, filter, limit, or page_size 

204 

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

206 

207 :param collection_model: The model of the collection 

208 

209 :param service_model: The model of the service 

210 

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

212 It is useful for generating docstrings. 

213 """ 

214 operation_model = service_model.operation_model( 

215 collection_model.request.operation 

216 ) 

217 

218 underlying_operation_members = [] 

219 if operation_model.input_shape: 

220 underlying_operation_members = operation_model.input_shape.members 

221 

222 example_resource_name = xform_name(resource_name) 

223 if service_model.service_name == resource_name: 

224 example_resource_name = resource_name 

225 

226 custom_action_info_dict = { 

227 'all': { 

228 'method_description': ( 

229 f'Creates an iterable of all {collection_model.resource.type} ' 

230 f'resources in the collection.' 

231 ), 

232 'example_prefix': '{}_iterator = {}.{}.all'.format( 

233 xform_name(collection_model.resource.type), 

234 example_resource_name, 

235 collection_model.name, 

236 ), 

237 'exclude_input': underlying_operation_members, 

238 }, 

239 'filter': { 

240 'method_description': ( 

241 f'Creates an iterable of all {collection_model.resource.type} ' 

242 f'resources in the collection filtered by kwargs passed to ' 

243 f'method. A {collection_model.resource.type} collection will ' 

244 f'include all resources by default if no filters are provided, ' 

245 f'and extreme caution should be taken when performing actions ' 

246 f'on all resources.' 

247 ), 

248 'example_prefix': '{}_iterator = {}.{}.filter'.format( 

249 xform_name(collection_model.resource.type), 

250 example_resource_name, 

251 collection_model.name, 

252 ), 

253 'exclude_input': get_resource_ignore_params( 

254 collection_model.request.params 

255 ), 

256 }, 

257 'limit': { 

258 'method_description': ( 

259 f'Creates an iterable up to a specified amount of ' 

260 f'{collection_model.resource.type} resources in the collection.' 

261 ), 

262 'example_prefix': '{}_iterator = {}.{}.limit'.format( 

263 xform_name(collection_model.resource.type), 

264 example_resource_name, 

265 collection_model.name, 

266 ), 

267 'include_input': [ 

268 DocumentedShape( 

269 name='count', 

270 type_name='integer', 

271 documentation=( 

272 'The limit to the number of resources ' 

273 'in the iterable.' 

274 ), 

275 ) 

276 ], 

277 'exclude_input': underlying_operation_members, 

278 }, 

279 'page_size': { 

280 'method_description': ( 

281 f'Creates an iterable of all {collection_model.resource.type} ' 

282 f'resources in the collection, but limits the number of ' 

283 f'items returned by each service call by the specified amount.' 

284 ), 

285 'example_prefix': '{}_iterator = {}.{}.page_size'.format( 

286 xform_name(collection_model.resource.type), 

287 example_resource_name, 

288 collection_model.name, 

289 ), 

290 'include_input': [ 

291 DocumentedShape( 

292 name='count', 

293 type_name='integer', 

294 documentation=( 

295 'The number of items returned by each ' 'service call' 

296 ), 

297 ) 

298 ], 

299 'exclude_input': underlying_operation_members, 

300 }, 

301 } 

302 if action_name in custom_action_info_dict: 

303 action_info = custom_action_info_dict[action_name] 

304 document_model_driven_resource_method( 

305 section=section, 

306 method_name=action_name, 

307 operation_model=operation_model, 

308 event_emitter=event_emitter, 

309 resource_action_model=collection_model, 

310 include_signature=include_signature, 

311 **action_info, 

312 )