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

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.utils import get_service_module_name 

18 

19from boto3.docs.base import NestedDocumenter 

20from boto3.docs.utils import ( 

21 add_resource_type_overview, 

22 get_identifier_args_for_signature, 

23 get_identifier_description, 

24 get_identifier_values_for_example, 

25) 

26 

27 

28class SubResourceDocumenter(NestedDocumenter): 

29 def document_sub_resources(self, section): 

30 add_resource_type_overview( 

31 section=section, 

32 resource_type='Sub-resources', 

33 description=( 

34 'Sub-resources are methods that create a new instance of a' 

35 ' child resource. This resource\'s identifiers get passed' 

36 ' along to the child.' 

37 ), 

38 intro_link='subresources_intro', 

39 ) 

40 sub_resources = sorted( 

41 self._resource.meta.resource_model.subresources, 

42 key=lambda sub_resource: sub_resource.name, 

43 ) 

44 sub_resources_list = [] 

45 self.member_map['sub-resources'] = sub_resources_list 

46 for sub_resource in sub_resources: 

47 sub_resources_list.append(sub_resource.name) 

48 # Create a new DocumentStructure for each sub_resource and add contents. 

49 sub_resource_doc = DocumentStructure( 

50 sub_resource.name, target='html' 

51 ) 

52 breadcrumb_section = sub_resource_doc.add_new_section('breadcrumb') 

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

54 breadcrumb_section.write(f' / Sub-Resource / {sub_resource.name}') 

55 sub_resource_doc.add_title_section(sub_resource.name) 

56 sub_resource_section = sub_resource_doc.add_new_section( 

57 sub_resource.name, 

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

59 ) 

60 document_sub_resource( 

61 section=sub_resource_section, 

62 resource_name=self._resource_name, 

63 sub_resource_model=sub_resource, 

64 service_model=self._service_model, 

65 ) 

66 

67 # Write sub_resources in individual/nested files. 

68 # Path: <root>/reference/services/<service>/<resource_name>/<sub_resource_name>.rst 

69 sub_resources_dir_path = os.path.join( 

70 self._root_docs_path, 

71 f'{self._service_name}', 

72 f'{self._resource_sub_path}', 

73 ) 

74 sub_resource_doc.write_to_file( 

75 sub_resources_dir_path, sub_resource.name 

76 ) 

77 

78 

79def document_sub_resource( 

80 section, 

81 resource_name, 

82 sub_resource_model, 

83 service_model, 

84 include_signature=True, 

85): 

86 """Documents a resource action 

87 

88 :param section: The section to write to 

89 

90 :param resource_name: The name of the resource 

91 

92 :param sub_resource_model: The model of the subresource 

93 

94 :param service_model: The model of the service 

95 

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

97 It is useful for generating docstrings. 

98 """ 

99 identifiers_needed = [] 

100 for identifier in sub_resource_model.resource.identifiers: 

101 if identifier.source == 'input': 

102 identifiers_needed.append(xform_name(identifier.target)) 

103 

104 if include_signature: 

105 signature_args = get_identifier_args_for_signature(identifiers_needed) 

106 full_sub_resource_name = ( 

107 f"{section.context.get('qualifier', '')}{sub_resource_model.name}" 

108 ) 

109 section.style.start_sphinx_py_method( 

110 full_sub_resource_name, signature_args 

111 ) 

112 

113 method_intro_section = section.add_new_section('method-intro') 

114 description = f'Creates a {sub_resource_model.resource.type} resource.' 

115 method_intro_section.include_doc_string(description) 

116 example_section = section.add_new_section('example') 

117 example_values = get_identifier_values_for_example(identifiers_needed) 

118 example_resource_name = xform_name(resource_name) 

119 if service_model.service_name == resource_name: 

120 example_resource_name = resource_name 

121 example = '{} = {}.{}({})'.format( 

122 xform_name(sub_resource_model.resource.type), 

123 example_resource_name, 

124 sub_resource_model.name, 

125 example_values, 

126 ) 

127 example_section.style.start_codeblock() 

128 example_section.write(example) 

129 example_section.style.end_codeblock() 

130 

131 param_section = section.add_new_section('params') 

132 for identifier in identifiers_needed: 

133 description = get_identifier_description( 

134 sub_resource_model.name, identifier 

135 ) 

136 param_section.write(f':type {identifier}: string') 

137 param_section.style.new_line() 

138 param_section.write(f':param {identifier}: {description}') 

139 param_section.style.new_line() 

140 

141 return_section = section.add_new_section('return') 

142 return_section.style.new_line() 

143 return_section.write( 

144 ':rtype: :py:class:`{}.{}`'.format( 

145 get_service_module_name(service_model), 

146 sub_resource_model.resource.type, 

147 ) 

148 ) 

149 return_section.style.new_line() 

150 return_section.write( 

151 f':returns: A {sub_resource_model.resource.type} resource' 

152 ) 

153 return_section.style.new_line()