def test_target_is_nested_param(self): param = Parameter('Filters[0].Name', 'response') ignore_params = get_resource_ignore_params([param]) assert ignore_params == ['Filters'] param = Parameter('Filters[0].Values[0]', 'response') ignore_params = get_resource_ignore_params([param]) assert ignore_params == ['Filters']
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_resource_waiter( section, resource_name, event_emitter, service_model, resource_waiter_model, service_waiter_model, include_signature=True, ): waiter_model = service_waiter_model.get_waiter( resource_waiter_model.waiter_name ) operation_model = service_model.operation_model(waiter_model.operation) ignore_params = get_resource_ignore_params(resource_waiter_model.params) service_module_name = get_service_module_name(service_model) description = ( 'Waits until this {} is {}. This method calls ' ':py:meth:`{}.Waiter.{}.wait` which polls. ' ':py:meth:`{}.Client.{}` every {} seconds until ' 'a successful state is reached. An error is returned ' 'after {} failed checks.'.format( resource_name, ' '.join(resource_waiter_model.name.split('_')[2:]), service_module_name, xform_name(resource_waiter_model.waiter_name), service_module_name, xform_name(waiter_model.operation), waiter_model.delay, waiter_model.max_attempts, ) ) example_prefix = '{}.{}'.format( xform_name(resource_name), resource_waiter_model.name ) document_model_driven_method( section=section, method_name=resource_waiter_model.name, operation_model=operation_model, event_emitter=event_emitter, example_prefix=example_prefix, method_description=description, exclude_input=ignore_params, include_signature=include_signature, ) if 'return' in section.available_sections: # Waiters do not return anything so we should remove # any sections that may document the underlying return # value of the client method. return_section = section.get_section('return') return_section.clear_text() return_section.remove_all_sections() return_section.write(':returns: None')
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_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 test_target_is_element_of_multiple_resources(self): param = Parameter('InstanceIds[0]', 'response') ignore_params = get_resource_ignore_params([param]) assert ignore_params == ['InstanceIds']
def test_target_is_single_resource(self): param = Parameter('InstanceId', 'response') ignore_params = get_resource_ignore_params([param]) assert ignore_params == ['InstanceId']
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 test_target_is_multiple_resources(self): param = Parameter('InstanceIds[]', 'response') ignore_params = get_resource_ignore_params([param]) self.assertEqual(ignore_params, ['InstanceIds'])