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_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_default(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', 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'", ' }', ' **Response Structure** ', ' - *(dict) --* ', ' - **Foo** *(string) --* Documents Foo', ' - **Bar** *(string) --* Documents Bar' ])
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 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 = '{} = {}.{}.{}'.format( 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_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 = '{} = {}.{}'.format(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 _document_batch_action(self, section, action, collection): operation_model = self._service_model.operation_model(action.request.operation) ignore_params = get_resource_ignore_params(action.request.params) example_return_value = "response" if action.resource: example_return_value = xform_name(action.resource.type) resource_name = xform_name(self._resource_name) if self.represents_service_resource: resource_name = self._resource_name example_prefix = "%s = %s.%s.%s" % (example_return_value, resource_name, collection.name, action.name) document_model_driven_resource_method( section=section, method_name=action.name, operation_model=operation_model, event_emitter=self._resource.meta.client.meta.events, method_description=operation_model.documentation, example_prefix=example_prefix, exclude_input=ignore_params, resource_action_model=action, )
def _document_batch_action(self, section, action, collection): operation_model = self._service_model.operation_model( action.request.operation) ignore_params = get_resource_ignore_params(action.request.params) example_return_value = 'response' if action.resource: example_return_value = xform_name(action.resource.type) resource_name = xform_name(self._resource_name) if self.represents_service_resource: resource_name = self._resource_name example_prefix = '%s = %s.%s.%s' % ( example_return_value, resource_name, collection.name, action.name) document_model_driven_resource_method( section=section, method_name=action.name, operation_model=operation_model, event_emitter=self._resource.meta.client.meta.events, method_description=operation_model.documentation, example_prefix=example_prefix, exclude_input=ignore_params, resource_action_model=action)
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 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': (f'Creates an iterable of all {collection_model.resource.type} ' f'resources in the collection.'), 'example_prefix': '{}_iterator = {}.{}.all'.format( xform_name(collection_model.resource.type), example_resource_name, collection_model.name, ), 'exclude_input': underlying_operation_members, }, 'filter': { 'method_description': (f'Creates an iterable of all {collection_model.resource.type} ' f'resources in the collection filtered by kwargs passed to ' f'method. A {collection_model.resource.type} collection will ' f'include all resources by default if no filters are provided, ' f'and extreme caution should be taken when performing actions ' f'on all resources.'), 'example_prefix': '{}_iterator = {}.{}.filter'.format( 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': (f'Creates an iterable up to a specified amount of ' f'{collection_model.resource.type} resources in the collection.'), 'example_prefix': '{}_iterator = {}.{}.limit'.format( 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': (f'Creates an iterable of all {collection_model.resource.type} ' f'resources in the collection, but limits the number of ' f'items returned by each service call by the specified amount.'), 'example_prefix': '{}_iterator = {}.{}.page_size'.format( 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, )
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)
def _document_custom_action(self, section, action_name, collection): operation_model = self._service_model.operation_model( collection.request.operation) underlying_operation_members = [] if operation_model.input_shape: underlying_operation_members = operation_model.input_shape.members resource_name = xform_name(self._resource_name) if self.represents_service_resource: resource_name = self._resource_name custom_action_info_dict = { 'all': { 'method_description': ('Creates an iterable of all %s resources ' 'in the collection.' % collection.resource.type), 'example_prefix': '%s_iterator = %s.%s.all' % (xform_name( collection.resource.type), resource_name, collection.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.resource.type), 'example_prefix': '%s_iterator = %s.%s.filter' % (xform_name( collection.resource.type), resource_name, collection.name), 'exclude_input': get_resource_ignore_params(collection.request.params) }, 'limit': { 'method_description': ('Creates an iterable up to a specified amount of ' '%s resources in the collection.' % collection.resource.type), 'example_prefix': '%s_iterator = %s.%s.limit' % (xform_name( collection.resource.type), resource_name, collection.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.resource.type), 'example_prefix': '%s_iterator = %s.%s.page_size' % (xform_name( collection.resource.type), resource_name, collection.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=self._resource.meta.client.meta.events, resource_action_model=collection, **action_info)
def _document_custom_action(self, section, action_name, collection): operation_model = self._service_model.operation_model(collection.request.operation) underlying_operation_members = [] if operation_model.input_shape: underlying_operation_members = operation_model.input_shape.members resource_name = xform_name(self._resource_name) if self.represents_service_resource: resource_name = self._resource_name custom_action_info_dict = { "all": { "method_description": ( "Creates an iterable of all %s resources " "in the collection." % collection.resource.type ), "example_prefix": "%s_iterator = %s.%s.all" % (xform_name(collection.resource.type), resource_name, collection.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.resource.type ), "example_prefix": "%s_iterator = %s.%s.filter" % (xform_name(collection.resource.type), resource_name, collection.name), "exclude_input": get_resource_ignore_params(collection.request.params), }, "limit": { "method_description": ( "Creates an iterable up to a specified amount of " "%s resources in the collection." % collection.resource.type ), "example_prefix": "%s_iterator = %s.%s.limit" % (xform_name(collection.resource.type), resource_name, collection.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.resource.type ), "example_prefix": "%s_iterator = %s.%s.page_size" % (xform_name(collection.resource.type), resource_name, collection.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=self._resource.meta.client.meta.events, resource_action_model=collection, **action_info )
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 )