2015-11-24 12:34:53 +01:00
|
|
|
# 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
|
|
|
|
#
|
|
|
|
# http://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.
|
2022-05-26 00:10:07 +02:00
|
|
|
from botocore.docs.params import (
|
|
|
|
RequestParamsDocumenter,
|
|
|
|
ResponseParamsDocumenter,
|
|
|
|
)
|
|
|
|
from botocore.docs.utils import DocumentedShape
|
|
|
|
from botocore.hooks import HierarchicalEmitter
|
2021-09-22 22:53:42 +02:00
|
|
|
from tests import mock
|
2015-11-24 12:34:53 +01:00
|
|
|
from tests.unit.docs import BaseDocsTest
|
|
|
|
|
|
|
|
|
|
|
|
class BaseParamsDocumenterTest(BaseDocsTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.event_emitter = HierarchicalEmitter()
|
|
|
|
self.request_params = RequestParamsDocumenter(
|
2022-05-26 00:10:07 +02:00
|
|
|
service_name='myservice',
|
|
|
|
operation_name='SampleOperation',
|
|
|
|
event_emitter=self.event_emitter,
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
self.response_params = ResponseParamsDocumenter(
|
2022-05-26 00:10:07 +02:00
|
|
|
service_name='myservice',
|
|
|
|
operation_name='SampleOperation',
|
|
|
|
event_emitter=self.event_emitter,
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
|
|
|
|
class TestDocumentDefaultValue(BaseParamsDocumenterTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape_to_params('Foo', 'String', 'This describes foo.')
|
|
|
|
|
|
|
|
def test_request_params(self):
|
|
|
|
self.request_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[':type Foo: string', ':param Foo: This describes foo.']
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_response_params(self):
|
|
|
|
self.response_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
['- *(dict) --*', ' - **Foo** *(string) --* This describes foo.']
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
|
|
|
|
class TestTraverseAndDocumentShape(BaseParamsDocumenterTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape_to_params('Foo', 'String', 'This describes foo.')
|
|
|
|
self.event_emitter = mock.Mock()
|
|
|
|
self.request_params = RequestParamsDocumenter(
|
2022-05-26 00:10:07 +02:00
|
|
|
service_name='myservice',
|
|
|
|
operation_name='SampleOperation',
|
|
|
|
event_emitter=self.event_emitter,
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
self.response_params = ResponseParamsDocumenter(
|
2022-05-26 00:10:07 +02:00
|
|
|
service_name='myservice',
|
|
|
|
operation_name='SampleOperation',
|
|
|
|
event_emitter=self.event_emitter,
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_events_emitted_response_params(self):
|
|
|
|
self.response_params.traverse_and_document_shape(
|
|
|
|
section=self.doc_structure,
|
2022-05-26 00:10:07 +02:00
|
|
|
shape=self.operation_model.input_shape,
|
|
|
|
history=[],
|
2015-11-24 12:34:53 +01:00
|
|
|
)
|
|
|
|
self.assertEqual(
|
|
|
|
self.event_emitter.emit.call_args_list,
|
2022-05-26 00:10:07 +02:00
|
|
|
[
|
|
|
|
mock.call(
|
|
|
|
'docs.response-params.myservice.SampleOperation.Foo',
|
|
|
|
section=self.doc_structure.get_section('Foo'),
|
|
|
|
),
|
|
|
|
mock.call(
|
|
|
|
(
|
|
|
|
'docs.response-params.myservice.SampleOperation'
|
|
|
|
'.complete-section'
|
|
|
|
),
|
|
|
|
section=self.doc_structure,
|
|
|
|
),
|
|
|
|
],
|
2015-11-24 12:34:53 +01:00
|
|
|
)
|
|
|
|
|
|
|
|
def test_events_emitted_request_params(self):
|
|
|
|
self.request_params.traverse_and_document_shape(
|
|
|
|
section=self.doc_structure,
|
2022-05-26 00:10:07 +02:00
|
|
|
shape=self.operation_model.input_shape,
|
|
|
|
history=[],
|
2015-11-24 12:34:53 +01:00
|
|
|
)
|
|
|
|
self.assertEqual(
|
|
|
|
self.event_emitter.emit.call_args_list,
|
2022-05-26 00:10:07 +02:00
|
|
|
[
|
|
|
|
mock.call(
|
|
|
|
'docs.request-params.myservice.SampleOperation.Foo',
|
|
|
|
section=self.doc_structure.get_section('Foo'),
|
|
|
|
),
|
|
|
|
mock.call(
|
|
|
|
(
|
|
|
|
'docs.request-params.myservice.SampleOperation'
|
|
|
|
'.complete-section'
|
|
|
|
),
|
|
|
|
section=self.doc_structure,
|
|
|
|
),
|
|
|
|
],
|
2015-11-24 12:34:53 +01:00
|
|
|
)
|
|
|
|
|
|
|
|
|
|
|
|
class TestDocumentMultipleDefaultValues(BaseParamsDocumenterTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape_to_params('Foo', 'String', 'This describes foo.')
|
2022-05-26 00:10:07 +02:00
|
|
|
self.add_shape_to_params(
|
|
|
|
'Bar', 'String', 'This describes bar.', is_required=True
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_request_params(self):
|
|
|
|
self.request_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
':type Foo: string',
|
|
|
|
':param Foo: This describes foo.',
|
|
|
|
':type Bar: string',
|
|
|
|
':param Bar: **[REQUIRED]** This describes bar.',
|
|
|
|
]
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_response_params(self):
|
|
|
|
self.response_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
'- *(dict) --*',
|
|
|
|
' - **Foo** *(string) --* This describes foo.',
|
|
|
|
' - **Bar** *(string) --* This describes bar.',
|
|
|
|
]
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
|
|
|
|
class TestDocumentInclude(BaseParamsDocumenterTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape_to_params('Foo', 'String', 'This describes foo.')
|
|
|
|
self.include_params = [
|
|
|
|
DocumentedShape(
|
2022-05-26 00:10:07 +02:00
|
|
|
name='Baz',
|
|
|
|
type_name='integer',
|
|
|
|
documentation='This describes baz.',
|
2015-11-24 12:34:53 +01:00
|
|
|
)
|
|
|
|
]
|
|
|
|
|
|
|
|
def test_request_params(self):
|
|
|
|
self.request_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure,
|
|
|
|
self.operation_model.input_shape,
|
|
|
|
include=self.include_params,
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
':type Foo: string',
|
|
|
|
':param Foo: This describes foo.',
|
|
|
|
':type Baz: int',
|
|
|
|
':param Baz: This describes baz.',
|
|
|
|
]
|
2015-11-24 12:34:53 +01:00
|
|
|
)
|
|
|
|
|
|
|
|
def test_response_params(self):
|
|
|
|
self.response_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure,
|
|
|
|
self.operation_model.input_shape,
|
|
|
|
include=self.include_params,
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
'- *(dict) --*',
|
|
|
|
' - **Foo** *(string) --* This describes foo.',
|
|
|
|
' - **Baz** *(integer) --* This describes baz.',
|
|
|
|
]
|
2015-11-24 12:34:53 +01:00
|
|
|
)
|
|
|
|
|
|
|
|
|
|
|
|
class TestDocumentExclude(BaseParamsDocumenterTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape_to_params('Foo', 'String', 'This describes foo.')
|
2022-05-26 00:10:07 +02:00
|
|
|
self.add_shape_to_params(
|
|
|
|
'Bar', 'String', 'This describes bar.', is_required=True
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
self.exclude_params = ['Foo']
|
|
|
|
|
|
|
|
def test_request_params(self):
|
|
|
|
self.request_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure,
|
|
|
|
self.operation_model.input_shape,
|
|
|
|
exclude=self.exclude_params,
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
':type Bar: string',
|
|
|
|
':param Bar: **[REQUIRED]** This describes bar.',
|
|
|
|
]
|
|
|
|
)
|
|
|
|
self.assert_not_contains_lines(
|
|
|
|
[':type Foo: string', ':param Foo: This describes foo.']
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_response_params(self):
|
|
|
|
self.response_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure,
|
|
|
|
self.operation_model.input_shape,
|
|
|
|
exclude=self.exclude_params,
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
['- *(dict) --*', ' - **Bar** *(string) --* This describes bar.']
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
self.assert_not_contains_line(
|
2022-05-26 00:10:07 +02:00
|
|
|
' - **Foo** *(string) --* This describes foo.'
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
|
|
|
|
class TestDocumentList(BaseParamsDocumenterTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape(
|
2022-05-26 00:10:07 +02:00
|
|
|
{
|
|
|
|
'List': {
|
|
|
|
'type': 'list',
|
|
|
|
'member': {
|
|
|
|
'shape': 'String',
|
|
|
|
'documentation': 'A string element',
|
|
|
|
},
|
|
|
|
}
|
|
|
|
}
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape_to_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
'Foo',
|
|
|
|
'List',
|
|
|
|
'This describes the list. Each element of this list is a string.',
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_request_params(self):
|
|
|
|
self.request_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
':type Foo: list',
|
|
|
|
':param Foo: This describes the list.',
|
|
|
|
' - *(string) --* A string element',
|
|
|
|
]
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_response_params(self):
|
|
|
|
self.response_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
'- *(dict) --*',
|
|
|
|
(
|
|
|
|
' - **Foo** *(list) --* This describes the list. '
|
|
|
|
'Each element of this list is a string.'
|
|
|
|
),
|
|
|
|
' - *(string) --* A string element',
|
|
|
|
]
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
|
|
|
|
class TestDocumentMap(BaseParamsDocumenterTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape(
|
2022-05-26 00:10:07 +02:00
|
|
|
{
|
|
|
|
'Map': {
|
|
|
|
'type': 'map',
|
|
|
|
'key': {'shape': 'String'},
|
|
|
|
'value': {'shape': 'String'},
|
|
|
|
}
|
|
|
|
}
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape_to_params('Foo', 'Map', 'This describes the map.')
|
|
|
|
|
|
|
|
def test_request_params(self):
|
|
|
|
self.request_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
':type Foo: dict',
|
|
|
|
':param Foo: This describes the map.',
|
|
|
|
' - *(string) --*',
|
|
|
|
' - *(string) --*',
|
|
|
|
]
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_response_params(self):
|
|
|
|
self.response_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
'- *(dict) --*',
|
|
|
|
' - **Foo** *(dict) --* This describes the map.',
|
|
|
|
' - *(string) --*',
|
|
|
|
' - *(string) --*',
|
|
|
|
]
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
|
|
|
|
class TestDocumentStructure(BaseParamsDocumenterTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape(
|
2022-05-26 00:10:07 +02:00
|
|
|
{
|
|
|
|
'Structure': {
|
|
|
|
'type': 'structure',
|
|
|
|
'members': {
|
|
|
|
'Member': {
|
|
|
|
'shape': 'String',
|
|
|
|
'documentation': 'This is its member.',
|
|
|
|
}
|
|
|
|
},
|
|
|
|
}
|
|
|
|
}
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape_to_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
'Foo', 'Structure', 'This describes the structure.'
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_request_params(self):
|
|
|
|
self.request_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
':type Foo: dict',
|
|
|
|
':param Foo: This describes the structure.',
|
|
|
|
' - **Member** *(string) --* This is its member.',
|
|
|
|
]
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_response_params(self):
|
|
|
|
self.response_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
'- *(dict) --*',
|
|
|
|
' - **Foo** *(dict) --* This describes the structure.',
|
|
|
|
' - **Member** *(string) --* This is its member.',
|
|
|
|
]
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
|
|
|
|
class TestDocumentRecursiveShape(BaseParamsDocumenterTest):
|
|
|
|
def setUp(self):
|
2022-05-26 00:10:07 +02:00
|
|
|
super().setUp()
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape(
|
2022-05-26 00:10:07 +02:00
|
|
|
{
|
|
|
|
'Structure': {
|
|
|
|
'type': 'structure',
|
|
|
|
'members': {
|
|
|
|
'Foo': {
|
|
|
|
'shape': 'Structure',
|
|
|
|
'documentation': 'This is a recursive structure.',
|
|
|
|
}
|
|
|
|
},
|
|
|
|
}
|
|
|
|
}
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
self.add_shape_to_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
'Foo', 'Structure', 'This describes the structure.'
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_request_params(self):
|
|
|
|
self.request_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
':type Foo: dict',
|
|
|
|
':param Foo: This describes the structure.',
|
|
|
|
' - **Foo** *(dict) --* This is a recursive structure.',
|
|
|
|
]
|
|
|
|
)
|
2015-11-24 12:34:53 +01:00
|
|
|
|
|
|
|
def test_response_params(self):
|
|
|
|
self.response_params.document_params(
|
2022-05-26 00:10:07 +02:00
|
|
|
self.doc_structure, self.operation_model.input_shape
|
|
|
|
)
|
|
|
|
self.assert_contains_lines_in_order(
|
|
|
|
[
|
|
|
|
'- *(dict) --*',
|
|
|
|
' - **Foo** *(dict) --* This is a recursive structure.',
|
|
|
|
]
|
|
|
|
)
|