Пример #1
0
 def setUp(self):
     super(TestTraverseAndDocumentShape, self).setUp()
     self.add_shape_to_params('Foo', 'String', 'This describes foo.')
     self.event_emitter = mock.Mock()
     self.request_example = RequestExampleDocumenter(
         service_name='myservice',
         operation_name='SampleOperation',
         event_emitter=self.event_emitter)
     self.response_example = ResponseExampleDocumenter(
         service_name='myservice',
         operation_name='SampleOperation',
         event_emitter=self.event_emitter)
Пример #2
0
class TestTraverseAndDocumentShape(BaseExampleDocumenterTest):
    def setUp(self):
        super(TestTraverseAndDocumentShape, self).setUp()
        self.add_shape_to_params('Foo', 'String', 'This describes foo.')
        self.event_emitter = mock.Mock()
        self.request_example = RequestExampleDocumenter(
            service_name='myservice',
            operation_name='SampleOperation',
            event_emitter=self.event_emitter)
        self.response_example = ResponseExampleDocumenter(
            service_name='myservice',
            operation_name='SampleOperation',
            event_emitter=self.event_emitter)

    def test_events_emitted_response_example(self):
        self.response_example.traverse_and_document_shape(
            section=self.doc_structure,
            shape=self.operation_model.input_shape,
            history=[])
        structure_section = self.doc_structure.get_section('structure-value')
        print(self.event_emitter.emit.call_args_list[0][1]['section'].name)
        self.assertEqual(self.event_emitter.emit.call_args_list, [
            mock.call('docs.response-example.myservice.SampleOperation.Foo',
                      section=structure_section.get_section('Foo').get_section(
                          'member-value')),
            mock.call(('docs.response-example.myservice.SampleOperation'
                       '.complete-section'),
                      section=self.doc_structure)
        ])

    def test_events_emitted_request_example(self):
        self.request_example.traverse_and_document_shape(
            section=self.doc_structure,
            shape=self.operation_model.input_shape,
            history=[])
        structure_section = self.doc_structure.get_section('structure-value')
        self.assertEqual(self.event_emitter.emit.call_args_list, [
            mock.call('docs.request-example.myservice.SampleOperation.Foo',
                      section=structure_section.get_section('Foo').get_section(
                          'member-value')),
            mock.call(('docs.request-example.myservice.SampleOperation'
                       '.complete-section'),
                      section=self.doc_structure)
        ])
Пример #3
0
 def setUp(self):
     super(TestTraverseAndDocumentShape, self).setUp()
     self.add_shape_to_params('Foo', 'String', 'This describes foo.')
     self.event_emitter = mock.Mock()
     self.request_example = RequestExampleDocumenter(
         service_name='myservice', operation_name='SampleOperation',
         event_emitter=self.event_emitter)
     self.response_example = ResponseExampleDocumenter(
         service_name='myservice', operation_name='SampleOperation',
         event_emitter=self.event_emitter)
Пример #4
0
class TestTraverseAndDocumentShape(BaseExampleDocumenterTest):
    def setUp(self):
        super(TestTraverseAndDocumentShape, self).setUp()
        self.add_shape_to_params('Foo', 'String', 'This describes foo.')
        self.event_emitter = mock.Mock()
        self.request_example = RequestExampleDocumenter(
            service_name='myservice', operation_name='SampleOperation',
            event_emitter=self.event_emitter)
        self.response_example = ResponseExampleDocumenter(
            service_name='myservice', operation_name='SampleOperation',
            event_emitter=self.event_emitter)

    def test_events_emitted_response_example(self):
        self.response_example.traverse_and_document_shape(
            section=self.doc_structure,
            shape=self.operation_model.input_shape, history=[]
        )
        structure_section = self.doc_structure.get_section('structure-value')
        print(self.event_emitter.emit.call_args_list[0][1]['section'].name)
        self.assertEqual(
            self.event_emitter.emit.call_args_list,
            [mock.call('docs.response-example.myservice.SampleOperation.Foo',
                       section=structure_section.get_section(
                           'Foo').get_section('member-value')),
             mock.call(('docs.response-example.myservice.SampleOperation'
                        '.complete-section'), section=self.doc_structure)]
        )

    def test_events_emitted_request_example(self):
        self.request_example.traverse_and_document_shape(
            section=self.doc_structure,
            shape=self.operation_model.input_shape, history=[]
        )
        structure_section = self.doc_structure.get_section('structure-value')
        self.assertEqual(
            self.event_emitter.emit.call_args_list,
            [mock.call('docs.request-example.myservice.SampleOperation.Foo',
                       section=structure_section.get_section(
                           'Foo').get_section('member-value')),
             mock.call(('docs.request-example.myservice.SampleOperation'
                        '.complete-section'), section=self.doc_structure)]
        )
Пример #5
0
 def test_alias_parameter_in_documentation_request_example(self):
     RequestExampleDocumenter('myservice', 'myoperation',
                              self.event_emitter).document_example(
                                  self.sample_section,
                                  self.operation_model.input_shape)
     self.parameter_alias.alias_parameter_in_documentation(
         'docs.request-example.myservice.myoperation.complete-section',
         self.sample_section)
     contents = self.sample_section.flush_structure().decode('utf-8')
     self.assertIn(self.alias_name + '=', contents)
     self.assertNotIn(self.original_name + '=', contents)
Пример #6
0
 def setUp(self):
     super(BaseExampleDocumenterTest, self).setUp()
     self.event_emitter = HierarchicalEmitter()
     self.request_example = RequestExampleDocumenter(
         service_name='myservice',
         operation_name='SampleOperation',
         event_emitter=self.event_emitter)
     self.response_example = ResponseExampleDocumenter(
         service_name='myservice',
         operation_name='SampleOperation',
         event_emitter=self.event_emitter)
Пример #7
0
def document_model_driven_method(section,
                                 method_name,
                                 operation_model,
                                 event_emitter,
                                 method_description=None,
                                 example_prefix=None,
                                 include_input=None,
                                 include_output=None,
                                 exclude_input=None,
                                 exclude_output=None,
                                 document_output=True,
                                 include_signature=True):
    """Documents an individual method

    :param section: The section to write to

    :param method_name: The name of the method

    :param operation_model: The model of the operation

    :param event_emitter: The event emitter to use to emit events

    :param example_prefix: The prefix to use in the method example.

    :type include_input: Dictionary where keys are parameter names and
        values are the shapes of the parameter names.
    :param include_input: The parameter shapes to include in the
        input documentation.

    :type include_output: Dictionary where keys are parameter names and
        values are the shapes of the parameter names.
    :param include_input: The parameter shapes to include in the
        output documentation.

    :type exclude_input: List of the names of the parameters to exclude.
    :param exclude_input: The names of the parameters to exclude from
        input documentation.

    :type exclude_output: List of the names of the parameters to exclude.
    :param exclude_input: The names of the parameters to exclude from
        output documentation.

    :param document_output: A boolean flag to indicate whether to
        document the output.

    :param include_signature: Whether or not to include the signature.
        It is useful for generating docstrings.
    """
    # Add the signature if specified.
    if include_signature:
        document_model_driven_signature(section,
                                        method_name,
                                        operation_model,
                                        include=include_input,
                                        exclude=exclude_input)

    # Add the description for the method.
    method_intro_section = section.add_new_section('method-intro')
    method_intro_section.include_doc_string(method_description)

    # Add the example section.
    example_section = section.add_new_section('example')
    example_section.style.new_paragraph()
    example_section.style.bold('Request Syntax')

    context = {
        'special_shape_types': {
            'streaming_input_shape': operation_model.get_streaming_input(),
            'streaming_output_shape': operation_model.get_streaming_output()
        }
    }

    if operation_model.input_shape:
        RequestExampleDocumenter(
            service_name=operation_model.service_model.service_name,
            operation_name=operation_model.name,
            event_emitter=event_emitter,
            context=context).document_example(example_section,
                                              operation_model.input_shape,
                                              prefix=example_prefix,
                                              include=include_input,
                                              exclude=exclude_input)
    else:
        example_section.style.new_paragraph()
        example_section.style.start_codeblock()
        example_section.write(example_prefix + '()')

    # Add the request parameter documentation.
    request_params_section = section.add_new_section('request-params')
    if operation_model.input_shape:
        RequestParamsDocumenter(
            service_name=operation_model.service_model.service_name,
            operation_name=operation_model.name,
            event_emitter=event_emitter,
            context=context).document_params(request_params_section,
                                             operation_model.input_shape,
                                             include=include_input,
                                             exclude=exclude_input)

    # Add the return value documentation
    return_section = section.add_new_section('return')
    return_section.style.new_line()
    if operation_model.output_shape is not None and document_output:
        return_section.write(':rtype: dict')
        return_section.style.new_line()
        return_section.write(':returns: ')
        return_section.style.indent()
        return_section.style.new_line()

        # Add an example return value
        return_example_section = return_section.add_new_section('example')
        return_example_section.style.new_line()
        return_example_section.style.bold('Response Syntax')
        return_example_section.style.new_paragraph()
        ResponseExampleDocumenter(
            service_name=operation_model.service_model.service_name,
            operation_name=operation_model.name,
            event_emitter=event_emitter,
            context=context).document_example(return_example_section,
                                              operation_model.output_shape,
                                              include=include_output,
                                              exclude=exclude_output)

        # Add a description for the return value
        return_description_section = return_section.add_new_section(
            'description')
        return_description_section.style.new_line()
        return_description_section.style.bold('Response Structure')
        return_description_section.style.new_paragraph()
        ResponseParamsDocumenter(
            service_name=operation_model.service_model.service_name,
            operation_name=operation_model.name,
            event_emitter=event_emitter,
            context=context).document_params(return_description_section,
                                             operation_model.output_shape,
                                             include=include_output,
                                             exclude=exclude_output)
    else:
        return_section.write(':returns: None')
Пример #8
0
def document_model_driven_method(section,
                                 method_name,
                                 operation_model,
                                 event_emitter,
                                 method_description=None,
                                 example_prefix=None,
                                 include_input=None,
                                 include_output=None,
                                 exclude_input=None,
                                 exclude_output=None,
                                 document_output=True,
                                 include_signature=True):
    """Documents an individual method

    :param section: The section to write to

    :param method_name: The name of the method

    :param operation_model: The model of the operation

    :param event_emitter: The event emitter to use to emit events

    :param example_prefix: The prefix to use in the method example.

    :type include_input: Dictionary where keys are parameter names and
        values are the shapes of the parameter names.
    :param include_input: The parameter shapes to include in the
        input documentation.

    :type include_output: Dictionary where keys are parameter names and
        values are the shapes of the parameter names.
    :param include_input: The parameter shapes to include in the
        output documentation.

    :type exclude_input: List of the names of the parameters to exclude.
    :param exclude_input: The names of the parameters to exclude from
        input documentation.

    :type exclude_output: List of the names of the parameters to exclude.
    :param exclude_input: The names of the parameters to exclude from
        output documentation.

    :param document_output: A boolean flag to indicate whether to
        document the output.

    :param include_signature: Whether or not to include the signature.
        It is useful for generating docstrings.
    """
    # Add the signature if specified.
    if include_signature:
        document_model_driven_signature(section,
                                        method_name,
                                        operation_model,
                                        include=include_input,
                                        exclude=exclude_input)

    # Add the description for the method.
    method_intro_section = section.add_new_section('method-intro')
    method_intro_section.include_doc_string(method_description)
    if operation_model.deprecated:
        method_intro_section.style.start_danger()
        method_intro_section.writeln(
            'This operation is deprecated and may not function as '
            'expected. This operation should not be used going forward '
            'and is only kept for the purpose of backwards compatiblity.')
        method_intro_section.style.end_danger()
    service_uid = operation_model.service_model.metadata.get('uid')
    if service_uid is not None:
        method_intro_section.style.new_paragraph()
        method_intro_section.write("See also: ")
        link = '%s/%s/%s' % (AWS_DOC_BASE, service_uid, operation_model.name)
        method_intro_section.style.external_link(title="AWS API Documentation",
                                                 link=link)
        method_intro_section.writeln('')

    # Add the example section.
    example_section = section.add_new_section('example')
    example_section.style.new_paragraph()
    example_section.style.bold('Request Syntax')

    context = {
        'special_shape_types': {
            'streaming_input_shape': operation_model.get_streaming_input(),
            'streaming_output_shape': operation_model.get_streaming_output(),
            'eventstream_output_shape':
            operation_model.get_event_stream_output(),
        },
    }

    if operation_model.input_shape:
        RequestExampleDocumenter(
            service_name=operation_model.service_model.service_name,
            operation_name=operation_model.name,
            event_emitter=event_emitter,
            context=context).document_example(example_section,
                                              operation_model.input_shape,
                                              prefix=example_prefix,
                                              include=include_input,
                                              exclude=exclude_input)
    else:
        example_section.style.new_paragraph()
        example_section.style.start_codeblock()
        example_section.write(example_prefix + '()')

    # Add the request parameter documentation.
    request_params_section = section.add_new_section('request-params')
    if operation_model.input_shape:
        RequestParamsDocumenter(
            service_name=operation_model.service_model.service_name,
            operation_name=operation_model.name,
            event_emitter=event_emitter,
            context=context).document_params(request_params_section,
                                             operation_model.input_shape,
                                             include=include_input,
                                             exclude=exclude_input)

    # Add the return value documentation
    return_section = section.add_new_section('return')
    return_section.style.new_line()
    if operation_model.output_shape is not None and document_output:
        return_section.write(':rtype: dict')
        return_section.style.new_line()
        return_section.write(':returns: ')
        return_section.style.indent()
        return_section.style.new_line()

        # If the operation is an event stream, describe the tagged union
        event_stream_output = operation_model.get_event_stream_output()
        if event_stream_output:
            event_section = return_section.add_new_section('event-stream')
            event_section.style.new_paragraph()
            event_section.write(
                'The response of this operation contains an '
                ':class:`.EventStream` member. When iterated the '
                ':class:`.EventStream` will yield events based on the '
                'structure below, where only one of the top level keys '
                'will be present for any given event.')
            event_section.style.new_line()

        # Add an example return value
        return_example_section = return_section.add_new_section('example')
        return_example_section.style.new_line()
        return_example_section.style.bold('Response Syntax')
        return_example_section.style.new_paragraph()
        ResponseExampleDocumenter(
            service_name=operation_model.service_model.service_name,
            operation_name=operation_model.name,
            event_emitter=event_emitter,
            context=context).document_example(return_example_section,
                                              operation_model.output_shape,
                                              include=include_output,
                                              exclude=exclude_output)

        # Add a description for the return value
        return_description_section = return_section.add_new_section(
            'description')
        return_description_section.style.new_line()
        return_description_section.style.bold('Response Structure')
        return_description_section.style.new_paragraph()
        ResponseParamsDocumenter(
            service_name=operation_model.service_model.service_name,
            operation_name=operation_model.name,
            event_emitter=event_emitter,
            context=context).document_params(return_description_section,
                                             operation_model.output_shape,
                                             include=include_output,
                                             exclude=exclude_output)
    else:
        return_section.write(':returns: None')