Debian Codegraph @

tests/functional/docs/test_smoke.py

raw
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.
13 import os
14 import shutil
15 import tempfile
16
17 import botocore.session
18 import pytest
19 from botocore import xform_name
20 from botocore.exceptions import DataNotFoundError
21
22 import boto3
23 from boto3.docs.service import ServiceDocumenter
24
25 DOCS_ROOT_DIR = None
26 ROOT_SERVICES_PATH = None
27
28
29 @pytest.fixture
30 def botocore_session():
31 return botocore.session.get_session()
32
33
34 @pytest.fixture
35 def boto3_session():
36 return boto3.Session(region_name='us-east-1')
37
38
39 def all_services():
40 # Create temporary directory before testing.
41 global DOCS_ROOT_DIR, ROOT_SERVICES_PATH
42 DOCS_ROOT_DIR = tempfile.mkdtemp()
43 ROOT_SERVICES_PATH = os.path.join(
44 tempfile.mkdtemp(), 'reference', 'services'
45 )
46 session = boto3.Session(region_name='us-east-1')
47 yield from session.get_available_services()
48 # Clean up temporary directory after testing.
49 shutil.rmtree(DOCS_ROOT_DIR)
50
51
52 @pytest.fixture
53 def available_resources():
54 session = boto3.Session(region_name='us-east-1')
55 return session.get_available_resources()
56
57
58 @pytest.mark.parametrize('service_name', all_services())
59 def test_documentation(
60 boto3_session, botocore_session, available_resources, service_name
61 ):
62 generated_docs = ServiceDocumenter(
63 service_name, session=boto3_session, root_docs_path=ROOT_SERVICES_PATH
64 ).document_service()
65 generated_docs = generated_docs.decode('utf-8')
66 client = boto3.client(service_name, 'us-east-1')
67
68 # Check that all of the services have the appropriate title
69 _assert_has_title(generated_docs, client)
70
71 # Check that all services have the client documented.
72 _assert_has_client_documentation(generated_docs, service_name, client)
73
74 # If the service has resources, make sure the service resource
75 # is at least documented.
76 if service_name in available_resources:
77 resource = boto3.resource(service_name, 'us-east-1')
78 _assert_has_resource_documentation(
79 generated_docs, service_name, resource
80 )
81
82 # If the client can paginate, make sure the paginators are documented.
83 try:
84 paginator_model = botocore_session.get_paginator_model(service_name)
85 if paginator_model._paginator_config:
86 _assert_has_paginator_documentation(
87 generated_docs,
88 service_name,
89 client,
90 sorted(paginator_model._paginator_config),
91 )
92 except DataNotFoundError:
93 pass
94
95 # If the client has waiters, make sure the waiters are documented.
96 if client.waiter_names:
97 waiter_model = botocore_session.get_waiter_model(service_name)
98 _assert_has_waiter_documentation(
99 generated_docs, service_name, client, waiter_model
100 )
101
102
103 def _assert_contains_lines_in_order(lines, contents):
104 for line in lines:
105 assert line in contents
106 beginning = contents.find(line)
107 contents = contents[(beginning + len(line)) :]
108
109
110 def _assert_has_title(generated_docs, client):
111 title = client.__class__.__name__
112 ref_lines = ['*' * len(title), title, '*' * len(title)]
113 _assert_contains_lines_in_order(ref_lines, generated_docs)
114
115
116 def _assert_has_client_documentation(generated_docs, service_name, client):
117 class_name = client.__class__.__name__
118 ref_lines = [
119 '======',
120 'Client',
121 '======',
122 f'.. py:class:: {class_name}.Client',
123 ' A low-level client representing',
124 ' import boto3',
125 f' client = boto3.client(\'{service_name}\')',
126 'These are the available methods:',
127 f' {service_name}/client/get_paginator',
128 f' {service_name}/client/get_waiter',
129 ]
130 _assert_contains_lines_in_order(ref_lines, generated_docs)
131 for method_name in ['get_paginator', 'get_waiter']:
132 _assert_contains_lines_in_order(
133 [
134 f'{method_name}',
135 f'.. py:method:: {client.__class__.__name__}.Client.{method_name}(',
136 ],
137 get_nested_file_contents(service_name, 'client', method_name),
138 )
139
140
141 def _assert_has_paginator_documentation(
142 generated_docs, service_name, client, paginator_names
143 ):
144 ref_lines = [
145 '==========',
146 'Paginators',
147 '==========',
148 'The available paginators are:',
149 ]
150 for paginator_name in paginator_names:
151 ref_lines.append(f' {service_name}/paginator/{paginator_name}')
152
153 for paginator_name in paginator_names:
154 _assert_contains_lines_in_order(
155 [
156 f'.. py:class:: {client.__class__.__name__}.Paginator.{paginator_name}',
157 ' .. py:method:: paginate(',
158 ],
159 get_nested_file_contents(
160 service_name, 'paginator', paginator_name
161 ),
162 )
163
164 _assert_contains_lines_in_order(ref_lines, generated_docs)
165
166
167 def _assert_has_waiter_documentation(
168 generated_docs, service_name, client, waiter_model
169 ):
170 ref_lines = ['=======', 'Waiters', '=======', 'The available waiters are:']
171 for waiter_name in waiter_model.waiter_names:
172 ref_lines.append(f' {service_name}/waiter/{waiter_name}')
173
174 for waiter_name in waiter_model.waiter_names:
175 _assert_contains_lines_in_order(
176 [
177 f'.. py:class:: {client.__class__.__name__}.Waiter.{waiter_name}',
178 f' waiter = client.get_waiter(\'{xform_name(waiter_name)}\')',
179 ' .. py:method:: wait(',
180 ],
181 get_nested_file_contents(service_name, 'waiter', waiter_name),
182 )
183
184 _assert_contains_lines_in_order(ref_lines, generated_docs)
185
186
187 def _assert_has_resource_documentation(generated_docs, service_name, resource):
188 ref_lines = [
189 '=======',
190 'Resources',
191 '=======',
192 'The available resources are:',
193 ]
194 ref_lines.append(f' {service_name}/service-resource/index')
195 _assert_contains_lines_in_order(ref_lines, generated_docs)
196
197 service_resource_ref_lines = [
198 '================',
199 'Service Resource',
200 '================',
201 f'.. py:class:: {resource.meta.client.__class__.__name__}.ServiceResource',
202 ' A resource representing',
203 ' import boto3',
204 f' {service_name} = boto3.resource(\'{service_name}\')',
205 ]
206 _assert_contains_lines_in_order(
207 service_resource_ref_lines,
208 get_nested_file_contents(service_name, 'service-resource', 'index'),
209 )
210
211
212 def get_nested_file_contents(service_name, sub_folder, file_name):
213 service_file_path = os.path.join(
214 ROOT_SERVICES_PATH,
215 service_name,
216 sub_folder,
217 f'{file_name}.rst',
218 )
219 with open(service_file_path, 'rb') as f:
220 return f.read().decode('utf-8')