def test_returns_resource(self): resource_action = self.service_resource_model.actions[0] # Override the return type of the action to be a resource # instead of the regular dictionary. resource_action.resource = ResponseResource( { 'type': 'Sample', 'identifiers': [{ 'target': 'Name', 'source': 'requestParameter', 'path': 'Foo' }] }, self.resource_json_model) document_model_driven_resource_method( self.doc_structure, 'foo', self.operation_model, event_emitter=self.event_emitter, method_description='This describes the foo method.', example_prefix='sample = myservice.foo', resource_action_model=resource_action) self.assert_contains_lines_in_order([ '.. py:method:: foo(**kwargs)', ' This describes the foo method.', ' **Request Syntax** ', ' ::', ' sample = myservice.foo(', " Foo='string',", " Bar='string'", ' )', ' :type Foo: string', ' :param Foo: Documents Foo', ' :type Bar: string', ' :param Bar: Documents Bar', ' :rtype: :py:class:`myservice.Sample`', ' :returns: Sample resource' ])
def test_include_output(self): include_params = [ DocumentedShape(name='Biz', type_name='string', documentation='biz docs') ] document_model_driven_resource_method( self.doc_structure, 'foo', self.operation_model, event_emitter=self.event_emitter, method_description='This describes the foo method.', example_prefix='response = myservice.foo', include_output=include_params, resource_action_model=self.service_resource_model.actions[0]) self.assert_contains_lines_in_order([ '.. py:method:: foo(**kwargs)', ' This describes the foo method.', ' **Request Syntax** ', ' ::', ' response = myservice.foo(', " Foo='string',", " Bar='string'", ' )', ' :type Foo: string', ' :param Foo: Documents Foo', ' :type Bar: string', ' :param Bar: Documents Bar', ' :rtype: dict', ' :returns: ', ' **Response Syntax** ', ' ::', ' {', " 'Foo': 'string',", " 'Bar': 'string',", " 'Biz': 'string'", ' }', ' **Response Structure** ', ' - *(dict) --* ', ' - **Foo** *(string) --* Documents Foo', ' - **Bar** *(string) --* Documents Bar', ' - **Biz** *(string) --* biz docs' ])
def document_batch_action(section, resource_name, event_emitter, batch_action_model, service_model, collection_model, include_signature=True): """Documents a collection's batch action :param section: The section to write to :param resource_name: The name of the resource :param action_name: The name of collection action. Currently only can be all, filter, limit, or page_size :param event_emitter: The event emitter to use to emit events :param batch_action_model: The model of the batch action :param collection_model: The model of the collection :param service_model: The model of the service :param include_signature: Whether or not to include the signature. It is useful for generating docstrings. """ operation_model = service_model.operation_model( batch_action_model.request.operation) ignore_params = get_resource_ignore_params( batch_action_model.request.params) example_return_value = 'response' if batch_action_model.resource: example_return_value = xform_name(batch_action_model.resource.type) example_resource_name = xform_name(resource_name) if service_model.service_name == resource_name: example_resource_name = resource_name example_prefix = '%s = %s.%s.%s' % ( example_return_value, example_resource_name, collection_model.name, batch_action_model.name) document_model_driven_resource_method( section=section, method_name=batch_action_model.name, operation_model=operation_model, event_emitter=event_emitter, method_description=operation_model.documentation, example_prefix=example_prefix, exclude_input=ignore_params, resource_action_model=batch_action_model, include_signature=include_signature)
def document_action(section, resource_name, event_emitter, action_model, service_model, include_signature=True): """Documents a resource action :param section: The section to write to :param resource_name: The name of the resource :param event_emitter: The event emitter to use to emit events :param action_model: The model of the action :param service_model: The model of the service :param include_signature: Whether or not to include the signature. It is useful for generating docstrings. """ operation_model = service_model.operation_model( action_model.request.operation) ignore_params = get_resource_ignore_params(action_model.request.params) example_return_value = 'response' if action_model.resource: example_return_value = xform_name(action_model.resource.type) example_resource_name = xform_name(resource_name) if service_model.service_name == resource_name: example_resource_name = resource_name example_prefix = '%s = %s.%s' % (example_return_value, example_resource_name, action_model.name) document_model_driven_resource_method( section=section, method_name=action_model.name, operation_model=operation_model, event_emitter=event_emitter, method_description=operation_model.documentation, example_prefix=example_prefix, exclude_input=ignore_params, resource_action_model=action_model, include_signature=include_signature)
def test_returns_list_of_resource(self): resource_action = self.service_resource_model.actions[1] document_model_driven_resource_method( self.doc_structure, 'foo', self.operation_model, event_emitter=self.event_emitter, method_description='This describes the foo method.', example_prefix='samples = myservice.foo', resource_action_model=resource_action) self.assert_contains_lines_in_order([ '.. py:method:: foo(**kwargs)', ' This describes the foo method.', ' **Request Syntax** ', ' ::', ' samples = myservice.foo(', " Foo='string',", " Bar='string'", ' )', ' :type Foo: string', ' :param Foo: Documents Foo', ' :type Bar: string', ' :param Bar: Documents Bar', ' :rtype: list(:py:class:`myservice.Sample`)', ' :returns: A list of Sample resource' ])
def test_exclude_input(self): document_model_driven_resource_method( self.doc_structure, 'foo', self.operation_model, event_emitter=self.event_emitter, method_description='This describes the foo method.', example_prefix='response = myservice.foo', exclude_input=['Bar'], resource_action_model=self.service_resource_model.actions[0]) self.assert_contains_lines_in_order([ '.. py:method:: foo(**kwargs)', ' This describes the foo method.', ' **Request Syntax** ', ' ::', ' response = myservice.foo(', " Foo='string',", ' )', ' :type Foo: string', ' :param Foo: Documents Foo', ' :rtype: dict', ' :returns: ', ' **Response Syntax** ', ' ::', ' {', " 'Foo': 'string',", " 'Bar': 'string'", ' }', ' **Response Structure** ', ' - *(dict) --* ', ' - **Foo** *(string) --* Documents Foo', ' - **Bar** *(string) --* Documents Bar' ]) self.assert_not_contains_lines( [':param Bar: string', 'Bar=\'string\''])
def document_collection_method(section, resource_name, action_name, event_emitter, collection_model, service_model, include_signature=True): """Documents a collection method :param section: The section to write to :param resource_name: The name of the resource :param action_name: The name of collection action. Currently only can be all, filter, limit, or page_size :param event_emitter: The event emitter to use to emit events :param collection_model: The model of the collection :param service_model: The model of the service :param include_signature: Whether or not to include the signature. It is useful for generating docstrings. """ operation_model = service_model.operation_model( collection_model.request.operation) underlying_operation_members = [] if operation_model.input_shape: underlying_operation_members = operation_model.input_shape.members example_resource_name = xform_name(resource_name) if service_model.service_name == resource_name: example_resource_name = resource_name custom_action_info_dict = { 'all': { 'method_description': ('Creates an iterable of all %s resources ' 'in the collection.' % collection_model.resource.type), 'example_prefix': '%s_iterator = %s.%s.all' % (xform_name(collection_model.resource.type), example_resource_name, collection_model.name), 'exclude_input': underlying_operation_members }, 'filter': { 'method_description': ('Creates an iterable of all %s resources ' 'in the collection filtered by kwargs passed to ' 'method.' % collection_model.resource.type), 'example_prefix': '%s_iterator = %s.%s.filter' % (xform_name(collection_model.resource.type), example_resource_name, collection_model.name), 'exclude_input': get_resource_ignore_params(collection_model.request.params) }, 'limit': { 'method_description': ('Creates an iterable up to a specified amount of ' '%s resources in the collection.' % collection_model.resource.type), 'example_prefix': '%s_iterator = %s.%s.limit' % (xform_name(collection_model.resource.type), example_resource_name, collection_model.name), 'include_input': [ DocumentedShape( name='count', type_name='integer', documentation=('The limit to the number of resources ' 'in the iterable.')) ], 'exclude_input': underlying_operation_members }, 'page_size': { 'method_description': ('Creates an iterable of all %s resources ' 'in the collection, but limits the number of ' 'items returned by each service call by the specified ' 'amount.' % collection_model.resource.type), 'example_prefix': '%s_iterator = %s.%s.page_size' % (xform_name(collection_model.resource.type), example_resource_name, collection_model.name), 'include_input': [ DocumentedShape( name='count', type_name='integer', documentation=('The number of items returned by each ' 'service call')) ], 'exclude_input': underlying_operation_members } } if action_name in custom_action_info_dict: action_info = custom_action_info_dict[action_name] document_model_driven_resource_method( section=section, method_name=action_name, operation_model=operation_model, event_emitter=event_emitter, resource_action_model=collection_model, include_signature=include_signature, **action_info)