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 tests import unittest
14from botocore.session import get_session
15from botocore.docs.service import ServiceDocumenter
16
17
18class BaseDocsFunctionalTest(unittest.TestCase):
19    def setUp(self):
20        self._session = get_session()
21
22    def assert_contains_line(self, line, contents):
23        contents = contents.decode('utf-8')
24        self.assertIn(line, contents)
25
26    def assert_contains_lines_in_order(self, lines, contents):
27        contents = contents.decode('utf-8')
28        for line in lines:
29            self.assertIn(line, contents)
30            beginning = contents.find(line)
31            contents = contents[(beginning + len(line)):]
32
33    def assert_not_contains_line(self, line, contents):
34        contents = contents.decode('utf-8')
35        self.assertNotIn(line, contents)
36
37    def assert_not_contains_lines(self, lines, contents):
38        contents = contents.decode('utf-8')
39        for line in lines:
40            self.assertNotIn(line, contents)
41
42    def get_title_section_for(self, service_name):
43        contents = ServiceDocumenter(
44            service_name, self._session).document_service().decode('utf-8')
45        start_of_table_of_contents = 'Table of Contents'
46        start_index = contents.find(start_of_table_of_contents)
47        contents = contents[:start_index]
48        contents = contents.encode('utf-8')
49        return contents
50
51    def get_method_document_block(self, operation_name, contents):
52        contents = contents.decode('utf-8')
53        start_method_document = '  .. py:method:: %s(' % operation_name
54        start_index = contents.find(start_method_document)
55        self.assertNotEqual(start_index, -1, 'Method is not found in contents')
56        contents = contents[start_index:]
57        end_index = contents.find(
58            '  .. py:method::', len(start_method_document))
59        contents = contents[:end_index]
60        return contents.encode('utf-8')
61
62    def get_parameter_document_block(self, param_name, contents):
63        contents = contents.decode('utf-8')
64        start_param_document = '    :type %s:' % param_name
65        start_index = contents.find(start_param_document)
66        self.assertNotEqual(start_index, -1, 'Param is not found in contents')
67        contents = contents[start_index:]
68        end_index = contents.find('    :type', len(start_param_document))
69        contents = contents[:end_index]
70        return contents.encode('utf-8')
71
72    def get_parameter_documentation_from_service(
73            self, service_name, method_name, param_name):
74        contents = ServiceDocumenter(
75            service_name, self._session).document_service()
76        method_contents = self.get_method_document_block(
77            method_name, contents)
78        return self.get_parameter_document_block(
79            param_name, method_contents)
80
81    def get_docstring_for_method(self, service_name, method_name):
82        contents = ServiceDocumenter(
83            service_name, self._session).document_service()
84        method_contents = self.get_method_document_block(
85            method_name, contents)
86        return method_contents
87
88    def assert_is_documented_as_autopopulated_param(
89            self, service_name, method_name, param_name, doc_string=None):
90        contents = ServiceDocumenter(
91            service_name, self._session).document_service()
92        method_contents = self.get_method_document_block(
93            method_name, contents)
94
95        # Ensure it is not in the example.
96        self.assert_not_contains_line('%s=\'string\'' % param_name,
97                                      method_contents)
98
99        # Ensure it is in the params.
100        param_contents = self.get_parameter_document_block(
101            param_name, method_contents)
102
103        # Ensure it is not labeled as required.
104        self.assert_not_contains_line('REQUIRED', param_contents)
105
106        # Ensure the note about autopopulation was added.
107        if doc_string is None:
108            doc_string = 'Please note that this parameter is automatically'
109        self.assert_contains_line(doc_string, param_contents)
110