def _create_client_class(self, service_name, service_model):
class_attributes = self._create_methods(service_model)
py_name_to_operation_name = self._create_name_mapping(service_model)
class_attributes['_PY_TO_OP_NAME'] = py_name_to_operation_name
bases = [BaseClient]
self._event_emitter.emit('creating-client-class.%s' % service_name,
class_attributes=class_attributes,
base_classes=bases)
class_name = get_service_module_name(service_model)
cls = type(str(class_name), tuple(bases), class_attributes)
return cls
def _create_client_class(self, service_name, service_model):
class_attributes = self._create_methods(service_model)
py_name_to_operation_name = self._create_name_mapping(service_model)
class_attributes['_PY_TO_OP_NAME'] = py_name_to_operation_name
bases = [BaseClient]
self._event_emitter.emit('creating-client-class.%s' % service_name,
class_attributes=class_attributes,
base_classes=bases)
class_name = get_service_module_name(service_model)
cls = type(str(class_name), tuple(bases), class_attributes)
return cls
def get_paginator(self, operation_name):
"""Create a paginator for an operation.
:type operation_name: string
:param operation_name: The operation name. This is the same name
as the method name on the client. For example, if the
method name is ``create_foo``, and you'd normally invoke the
operation as ``client.create_foo(**kwargs)``, if the
``create_foo`` operation can be paginated, you can use the
call ``client.get_paginator("create_foo")``.
:raise OperationNotPageableError: Raised if the operation is not
pageable. You can use the ``client.can_paginate`` method to
check if an operation is pageable.
:rtype: L{kscore.paginate.Paginator}
:return: A paginator object.
"""
if not self.can_paginate(operation_name):
raise OperationNotPageableError(operation_name=operation_name)
else:
actual_operation_name = self._PY_TO_OP_NAME[operation_name]
# Create a new paginate method that will serve as a proxy to
# the underlying Paginator.paginate method. This is needed to
# attach a docstring to the method.
def paginate(self, **kwargs):
return Paginator.paginate(self, **kwargs)
paginator_config = self._cache['page_config'][
actual_operation_name]
# Add the docstring for the paginate method.
paginate.__doc__ = PaginatorDocstring(
paginator_name=actual_operation_name,
event_emitter=self.meta.events,
service_model=self.meta.service_model,
paginator_config=paginator_config,
include_signature=False
)
# Rename the paginator class based on the type of paginator.
paginator_class_name = str('%s.Paginator.%s' % (
get_service_module_name(self.meta.service_model),
actual_operation_name))
# Create the new paginator class
documented_paginator_cls = type(
paginator_class_name, (Paginator,), {'paginate': paginate})
paginator = documented_paginator_cls(
getattr(self, operation_name),
paginator_config)
return paginator
def create_waiter_with_client(waiter_name, waiter_model, client):
"""
:type waiter_name: str
:param waiter_name: The name of the waiter. The name should match
the name (including the casing) of the key name in the waiter
model file (typically this is CamelCasing).
:type waiter_model: kscore.waiter.WaiterModel
:param waiter_model: The model for the waiter configuration.
:type client: kscore.client.BaseClient
:param client: The kscore client associated with the service.
:rtype: kscore.waiter.Waiter
:return: The waiter object.
"""
single_waiter_config = waiter_model.get_waiter(waiter_name)
operation_name = xform_name(single_waiter_config.operation)
operation_method = NormalizedOperationMethod(
getattr(client, operation_name))
# Create a new wait method that will serve as a proxy to the underlying
# Waiter.wait method. This is needed to attach a docstring to the
# method.
def wait(self, **kwargs):
Waiter.wait(self, **kwargs)
wait.__doc__ = WaiterDocstring(
waiter_name=waiter_name,
event_emitter=client.meta.events,
service_model=client.meta.service_model,
service_waiter_model=waiter_model,
include_signature=False
)
# Rename the waiter class based on the type of waiter.
waiter_class_name = str('%s.Waiter.%s' % (
get_service_module_name(client.meta.service_model),
waiter_name))
# Create the new waiter class
documented_waiter_cls = type(
waiter_class_name, (Waiter,), {'wait': wait})
# Return an instance of the new waiter class.
return documented_waiter_cls(
waiter_name, single_waiter_config, operation_method
)
def document_wait_method(section,
waiter_name,
event_emitter,
service_model,
service_waiter_model,
include_signature=True):
"""Documents a the wait method of a waiter
:param section: The section to write to
:param waiter_name: The name of the waiter
:param event_emitter: The event emitter to use to emit events
:param service_model: The service model
:param service_waiter_model: The waiter model associated to the service
:param include_signature: Whether or not to include the signature.
It is useful for generating docstrings.
"""
waiter_model = service_waiter_model.get_waiter(waiter_name)
operation_model = service_model.operation_model(waiter_model.operation)
wait_description = (
'Polls :py:meth:`{0}.Client.{1}` every {2} '
'seconds until a successful state is reached. An error is '
'returned after {3} failed checks.'.format(
get_service_module_name(service_model),
xform_name(waiter_model.operation), waiter_model.delay,
waiter_model.max_attempts))
document_model_driven_method(section,
'wait',
operation_model,
event_emitter=event_emitter,
method_description=wait_description,
example_prefix='waiter.wait',
document_output=False,
include_signature=include_signature)
def document_paginate_method(section,
paginator_name,
event_emitter,
service_model,
paginator_config,
include_signature=True):
"""Documents the paginate method of a paginator
:param section: The section to write to
:param paginator_name: The name of the paginator. It is snake cased.
:param event_emitter: The event emitter to use to emit events
:param service_model: The service model
:param paginator_config: The paginator config associated to a particular
paginator.
:param include_signature: Whether or not to include the signature.
It is useful for generating docstrings.
"""
# Retrieve the operation model of the underlying operation.
operation_model = service_model.operation_model(paginator_name)
# Add representations of the request and response parameters
# we want to include in the description of the paginate method.
# These are parameters we expose via the kscore interface.
pagination_config_members = OrderedDict()
pagination_config_members['MaxItems'] = DocumentedShape(
name='MaxItems',
type_name='integer',
documentation=('<p>The total number of items to return. If the total '
'number of items available is more than the value '
'specified in max-items then a <code>NextToken</code> '
'will be provided in the output that you can use to '
'resume pagination.</p>'))
pagination_config_members['PageSize'] = DocumentedShape(
name='PageSize',
type_name='integer',
documentation='<p>The size of each page.<p>')
pagination_config_members['StartingToken'] = DocumentedShape(
name='StartingToken',
type_name='string',
documentation=('<p>A token to specify where to start paginating. '
'This is the <code>NextToken</code> from a previous '
'response.</p>'))
kscore_pagination_params = [
DocumentedShape(
name='PaginationConfig',
type_name='structure',
documentation=(
'<p>A dictionary that provides parameters to control '
'pagination.</p>'),
members=pagination_config_members)
]
kscore_pagination_response_params = [
DocumentedShape(name='NextToken',
type_name='string',
documentation=('<p>A token to resume pagination.</p>'))
]
service_pagination_params = []
# Add the normal input token of the method to a list
# of input paramters that we wish to hide since we expose our own.
if isinstance(paginator_config['input_token'], list):
service_pagination_params += paginator_config['input_token']
else:
service_pagination_params.append(paginator_config['input_token'])
# Hide the limit key in the documentation.
if paginator_config.get('limit_key', None):
service_pagination_params.append(paginator_config['limit_key'])
# Hide the output tokens in the documentation.
service_pagination_response_params = []
if isinstance(paginator_config['output_token'], list):
service_pagination_response_params += paginator_config['output_token']
else:
service_pagination_response_params.append(
paginator_config['output_token'])
paginate_description = (
'Creates an iterator that will paginate through responses '
'from :py:meth:`{0}.Client.{1}`.'.format(
get_service_module_name(service_model),
xform_name(paginator_name)))
document_model_driven_method(
section,
'paginate',
operation_model,
event_emitter=event_emitter,
method_description=paginate_description,
example_prefix='response_iterator = paginator.paginate',
include_input=kscore_pagination_params,
include_output=kscore_pagination_response_params,
exclude_input=service_pagination_params,
exclude_output=service_pagination_response_params,
include_signature=include_signature)
def document_paginate_method(section, paginator_name, event_emitter,
service_model, paginator_config,
include_signature=True):
"""Documents the paginate method of a paginator
:param section: The section to write to
:param paginator_name: The name of the paginator. It is snake cased.
:param event_emitter: The event emitter to use to emit events
:param service_model: The service model
:param paginator_config: The paginator config associated to a particular
paginator.
:param include_signature: Whether or not to include the signature.
It is useful for generating docstrings.
"""
# Retrieve the operation model of the underlying operation.
operation_model = service_model.operation_model(
paginator_name)
# Add representations of the request and response parameters
# we want to include in the description of the paginate method.
# These are parameters we expose via the kscore interface.
pagination_config_members = OrderedDict()
pagination_config_members['MaxItems'] = DocumentedShape(
name='MaxItems', type_name='integer',
documentation=(
'<p>The total number of items to return. If the total '
'number of items available is more than the value '
'specified in max-items then a <code>NextToken</code> '
'will be provided in the output that you can use to '
'resume pagination.</p>'))
pagination_config_members['PageSize'] = DocumentedShape(
name='PageSize', type_name='integer',
documentation='<p>The size of each page.<p>')
pagination_config_members['StartingToken'] = DocumentedShape(
name='StartingToken', type_name='string',
documentation=(
'<p>A token to specify where to start paginating. '
'This is the <code>NextToken</code> from a previous '
'response.</p>'))
kscore_pagination_params = [
DocumentedShape(
name='PaginationConfig', type_name='structure',
documentation=(
'<p>A dictionary that provides parameters to control '
'pagination.</p>'),
members=pagination_config_members)
]
kscore_pagination_response_params = [
DocumentedShape(
name='NextToken', type_name='string',
documentation=(
'<p>A token to resume pagination.</p>'))
]
service_pagination_params = []
# Add the normal input token of the method to a list
# of input paramters that we wish to hide since we expose our own.
if isinstance(paginator_config['input_token'], list):
service_pagination_params += paginator_config['input_token']
else:
service_pagination_params.append(paginator_config['input_token'])
# Hide the limit key in the documentation.
if paginator_config.get('limit_key', None):
service_pagination_params.append(paginator_config['limit_key'])
# Hide the output tokens in the documentation.
service_pagination_response_params = []
if isinstance(paginator_config['output_token'], list):
service_pagination_response_params += paginator_config[
'output_token']
else:
service_pagination_response_params.append(paginator_config[
'output_token'])
paginate_description = (
'Creates an iterator that will paginate through responses '
'from :py:meth:`{0}.Client.{1}`.'.format(
get_service_module_name(service_model), xform_name(paginator_name))
)
document_model_driven_method(
section, 'paginate', operation_model,
event_emitter=event_emitter,
method_description=paginate_description,
example_prefix='response_iterator = paginator.paginate',
include_input=kscore_pagination_params,
include_output=kscore_pagination_response_params,
exclude_input=service_pagination_params,
exclude_output=service_pagination_response_params,
include_signature=include_signature
)
