1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
# Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License"). You
# may not use this file except in compliance with the License. A copy of
# the License is located at
#
# https://aws.amazon.com/apache2.0/
#
# or in the "license" file accompanying this file. This file is
# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
# ANY KIND, either express or implied. See the License for the specific
# language governing permissions and limitations under the License.
import os
import boto3
from boto3.docs.service import ServiceDocumenter
from tests import mock
from tests.unit.docs import BaseDocsTest
class TestServiceDocumenter(BaseDocsTest):
def test_document_service(self):
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
lines = [
'*********',
'MyService',
'*********',
'.. contents:: Table of Contents',
' :depth: 2',
'======',
'Client',
'======',
'.. py:class:: MyService.Client',
' These are the available methods:',
' * :py:meth:`~MyService.Client.sample_operation`',
' **Examples** ',
' Sample Description.',
' ::',
' response = client.sample_operation(',
'==========',
'Paginators',
'==========',
'The available paginators are:',
'* :py:class:`MyService.Paginator.SampleOperation`',
'.. py:class:: MyService.Paginator.SampleOperation',
' .. py:method:: paginate(**kwargs)',
'=======',
'Waiters',
'=======',
'The available waiters are:',
'* :py:class:`MyService.Waiter.SampleOperationComplete`',
'.. py:class:: MyService.Waiter.SampleOperationComplete',
' .. py:method:: wait(**kwargs)',
'================',
'Service Resource',
'================',
'.. py:class:: MyService.ServiceResource()',
" These are the resource's available actions:",
' * :py:meth:`sample_operation()`',
" These are the resource's available sub-resources:",
' * :py:meth:`Sample()`',
" These are the resource's available collections:",
' * :py:attr:`samples`',
' .. py:method:: sample_operation(**kwargs)',
' .. py:method:: Sample(name)',
' .. py:attribute:: samples',
' .. py:method:: all()',
' .. py:method:: filter(**kwargs)',
' .. py:method:: limit(**kwargs)',
' .. py:method:: page_size(**kwargs)',
'======',
'Sample',
'======',
'.. py:class:: MyService.Sample(name)',
" These are the resource's available identifiers:",
' * :py:attr:`name`',
" These are the resource's available attributes:",
' * :py:attr:`bar`',
' * :py:attr:`foo`',
" These are the resource's available actions:",
' * :py:meth:`load()`',
' * :py:meth:`operate()`',
' * :py:meth:`reload()`',
" These are the resource's available waiters:",
' * :py:meth:`wait_until_complete()`',
' .. py:attribute:: name',
' .. py:attribute:: bar',
' .. py:attribute:: foo',
' .. py:method:: load()',
' .. py:method:: operate(**kwargs)',
' .. py:method:: reload()',
' .. py:method:: wait_until_complete(**kwargs)',
]
self.assert_contains_lines_in_order(lines, contents)
def test_document_service_no_resource(self):
os.remove(self.resource_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
assert 'Service Resource' not in contents
def test_document_service_no_paginators(self):
# Delete the resource model so that the resource is not documented
# as it may try to look at the paginator model during documentation.
os.remove(self.resource_model_file)
os.remove(self.paginator_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
assert 'Paginators' not in contents
def test_document_service_no_waiter(self):
# Delete the resource model so that the resource is not documented
# as it may try to look at the waiter model during documentation.
os.remove(self.resource_model_file)
os.remove(self.waiter_model_file)
service_documenter = ServiceDocumenter('myservice', self.session)
contents = service_documenter.document_service().decode('utf-8')
assert 'Waiters' not in contents
def test_creates_correct_path_to_examples_based_on_service_name(self):
path = os.sep.join(
[os.path.dirname(boto3.__file__), 'examples', 'myservice.rst']
)
path = os.path.realpath(path)
with mock.patch('os.path.isfile') as isfile:
isfile.return_value = False
s = ServiceDocumenter('myservice', self.session)
s.document_service()
assert isfile.call_args_list[-1] == mock.call(path)
def test_injects_examples_when_found(self):
examples_path = os.sep.join(
[os.path.dirname(__file__), '..', 'data', 'examples']
)
service_documenter = ServiceDocumenter('myservice', self.session)
service_documenter.EXAMPLE_PATH = examples_path
contents = service_documenter.document_service().decode('utf-8')
assert 'This is an example' in contents
assert 'This is for another service' not in contents
|
