Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/boto3/docs/waiter.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 document_model_driven_method 

18from botocore.utils import get_service_module_name 

19 

20from boto3.docs.base import NestedDocumenter 

21from boto3.docs.utils import ( 

22 add_resource_type_overview, 

23 get_resource_ignore_params, 

24) 

25 

26 

27class WaiterResourceDocumenter(NestedDocumenter): 

28 def __init__(self, resource, service_waiter_model, root_docs_path): 

29 super().__init__(resource, root_docs_path) 

30 self._service_waiter_model = service_waiter_model 

31 

32 def document_resource_waiters(self, section): 

33 waiters = self._resource.meta.resource_model.waiters 

34 add_resource_type_overview( 

35 section=section, 

36 resource_type='Waiters', 

37 description=( 

38 'Waiters provide an interface to wait for a resource' 

39 ' to reach a specific state.' 

40 ), 

41 intro_link='waiters_intro', 

42 ) 

43 waiter_list = [] 

44 self.member_map['waiters'] = waiter_list 

45 for waiter in waiters: 

46 waiter_list.append(waiter.name) 

47 # Create a new DocumentStructure for each waiter and add contents. 

48 waiter_doc = DocumentStructure(waiter.name, target='html') 

49 breadcrumb_section = waiter_doc.add_new_section('breadcrumb') 

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

51 breadcrumb_section.write(f' / Waiter / {waiter.name}') 

52 waiter_doc.add_title_section(waiter.name) 

53 waiter_section = waiter_doc.add_new_section( 

54 waiter.name, 

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

56 ) 

57 document_resource_waiter( 

58 section=waiter_section, 

59 resource_name=self._resource_name, 

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

61 service_model=self._service_model, 

62 resource_waiter_model=waiter, 

63 service_waiter_model=self._service_waiter_model, 

64 ) 

65 # Write waiters in individual/nested files. 

66 # Path: <root>/reference/services/<service>/<resource_name>/<waiter_name>.rst 

67 waiters_dir_path = os.path.join( 

68 self._root_docs_path, 

69 f'{self._service_name}', 

70 f'{self._resource_sub_path}', 

71 ) 

72 waiter_doc.write_to_file(waiters_dir_path, waiter.name) 

73 

74 

75def document_resource_waiter( 

76 section, 

77 resource_name, 

78 event_emitter, 

79 service_model, 

80 resource_waiter_model, 

81 service_waiter_model, 

82 include_signature=True, 

83): 

84 waiter_model = service_waiter_model.get_waiter( 

85 resource_waiter_model.waiter_name 

86 ) 

87 operation_model = service_model.operation_model(waiter_model.operation) 

88 

89 ignore_params = get_resource_ignore_params(resource_waiter_model.params) 

90 service_module_name = get_service_module_name(service_model) 

91 description = ( 

92 'Waits until this {} is {}. This method calls ' 

93 ':py:meth:`{}.Waiter.{}.wait` which polls ' 

94 ':py:meth:`{}.Client.{}` every {} seconds until ' 

95 'a successful state is reached. An error is returned ' 

96 'after {} failed checks.'.format( 

97 resource_name, 

98 ' '.join(resource_waiter_model.name.split('_')[2:]), 

99 service_module_name, 

100 xform_name(resource_waiter_model.waiter_name), 

101 service_module_name, 

102 xform_name(waiter_model.operation), 

103 waiter_model.delay, 

104 waiter_model.max_attempts, 

105 ) 

106 ) 

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

108 xform_name(resource_name), resource_waiter_model.name 

109 ) 

110 full_waiter_name = ( 

111 f"{section.context.get('qualifier', '')}{resource_waiter_model.name}" 

112 ) 

113 document_model_driven_method( 

114 section=section, 

115 method_name=full_waiter_name, 

116 operation_model=operation_model, 

117 event_emitter=event_emitter, 

118 example_prefix=example_prefix, 

119 method_description=description, 

120 exclude_input=ignore_params, 

121 include_signature=include_signature, 

122 ) 

123 if 'return' in section.available_sections: 

124 # Waiters do not return anything so we should remove 

125 # any sections that may document the underlying return 

126 # value of the client method. 

127 return_section = section.get_section('return') 

128 return_section.clear_text() 

129 return_section.remove_all_sections() 

130 return_section.write(':returns: None')