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

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. 

13from botocore.docs.bcdoc.restdoc import DocumentStructure 

14from botocore.docs.client import ( 

15 ClientContextParamsDocumenter, 

16 ClientDocumenter, 

17 ClientExceptionsDocumenter, 

18) 

19from botocore.docs.paginator import PaginatorDocumenter 

20from botocore.docs.waiter import WaiterDocumenter 

21from botocore.exceptions import DataNotFoundError 

22 

23 

24class ServiceDocumenter: 

25 def __init__(self, service_name, session, root_docs_path): 

26 self._session = session 

27 self._service_name = service_name 

28 self._root_docs_path = root_docs_path 

29 

30 self._client = self._session.create_client( 

31 service_name, 

32 region_name='us-east-1', 

33 aws_access_key_id='foo', 

34 aws_secret_access_key='bar', 

35 ) 

36 self._event_emitter = self._client.meta.events 

37 

38 self.sections = [ 

39 'title', 

40 'client-api', 

41 'client-exceptions', 

42 'paginator-api', 

43 'waiter-api', 

44 'client-context-params', 

45 ] 

46 

47 def document_service(self): 

48 """Documents an entire service. 

49 

50 :returns: The reStructured text of the documented service. 

51 """ 

52 doc_structure = DocumentStructure( 

53 self._service_name, section_names=self.sections, target='html' 

54 ) 

55 self.title(doc_structure.get_section('title')) 

56 self.client_api(doc_structure.get_section('client-api')) 

57 self.client_exceptions(doc_structure.get_section('client-exceptions')) 

58 self.paginator_api(doc_structure.get_section('paginator-api')) 

59 self.waiter_api(doc_structure.get_section('waiter-api')) 

60 context_params_section = doc_structure.get_section( 

61 'client-context-params' 

62 ) 

63 self.client_context_params(context_params_section) 

64 return doc_structure.flush_structure() 

65 

66 def title(self, section): 

67 section.style.h1(self._client.__class__.__name__) 

68 self._event_emitter.emit( 

69 f"docs.title.{self._service_name}", section=section 

70 ) 

71 

72 def table_of_contents(self, section): 

73 section.style.table_of_contents(title='Table of Contents', depth=2) 

74 

75 def client_api(self, section): 

76 examples = None 

77 try: 

78 examples = self.get_examples(self._service_name) 

79 except DataNotFoundError: 

80 pass 

81 

82 ClientDocumenter( 

83 self._client, self._root_docs_path, examples 

84 ).document_client(section) 

85 

86 def client_exceptions(self, section): 

87 ClientExceptionsDocumenter( 

88 self._client, self._root_docs_path 

89 ).document_exceptions(section) 

90 

91 def paginator_api(self, section): 

92 try: 

93 service_paginator_model = self._session.get_paginator_model( 

94 self._service_name 

95 ) 

96 except DataNotFoundError: 

97 return 

98 if service_paginator_model._paginator_config: 

99 paginator_documenter = PaginatorDocumenter( 

100 self._client, service_paginator_model, self._root_docs_path 

101 ) 

102 paginator_documenter.document_paginators(section) 

103 

104 def waiter_api(self, section): 

105 if self._client.waiter_names: 

106 service_waiter_model = self._session.get_waiter_model( 

107 self._service_name 

108 ) 

109 waiter_documenter = WaiterDocumenter( 

110 self._client, service_waiter_model, self._root_docs_path 

111 ) 

112 waiter_documenter.document_waiters(section) 

113 

114 def get_examples(self, service_name, api_version=None): 

115 loader = self._session.get_component('data_loader') 

116 examples = loader.load_service_model( 

117 service_name, 'examples-1', api_version 

118 ) 

119 return examples['examples'] 

120 

121 def client_context_params(self, section): 

122 omitted_params = ClientContextParamsDocumenter.OMITTED_CONTEXT_PARAMS 

123 params_to_omit = omitted_params.get(self._service_name, []) 

124 service_model = self._client.meta.service_model 

125 raw_context_params = service_model.client_context_parameters 

126 context_params = [ 

127 p for p in raw_context_params if p.name not in params_to_omit 

128 ] 

129 if context_params: 

130 context_param_documenter = ClientContextParamsDocumenter( 

131 self._service_name, context_params 

132 ) 

133 context_param_documenter.document_context_params(section)