def document_client_waiter(session, official_name, service_name, service_model,
client):
waiter_spec_doc = ''
if client.waiter_names:
waiter_spec_doc = 'Waiter\n------\n\n'
service_waiter_model = session.get_waiter_model(service_name)
for waiter in service_waiter_model.waiter_names:
snake_cased = xform_name(waiter)
waiter_spec_doc += '{0}\n{1}\n\n'.format(snake_cased,
'~' * len(snake_cased))
waiter_model = service_waiter_model.get_waiter(waiter)
operation_model = service_model.operation_model(
waiter_model.operation)
description = (
' This polls :py:meth:`{0}.Client.{1}` every {2} '
'seconds until a successful state is reached. An error is '
'returned after {3} failed checks.'.format(
service_name, xform_name(waiter_model.operation),
waiter_model.delay, waiter_model.max_attempts))
waiter_spec_doc += document_operation(
operation_model=operation_model,
service_name=service_name,
operation_name='wait',
rtype=None,
description=description,
example_instance='client.get_waiter(\'{0}\')'.format(
snake_cased))
waiter_spec_doc += '\n'
return waiter_spec_doc
def document_client_waiter(session, official_name, service_name,
service_model, client):
waiter_spec_doc = ''
if client.waiter_names:
waiter_spec_doc = 'Waiter\n------\n\n'
service_waiter_model = session.get_waiter_model(service_name)
for waiter in service_waiter_model.waiter_names:
snake_cased = xform_name(waiter)
waiter_spec_doc += '{0}\n{1}\n\n'.format(snake_cased,
'~' * len(snake_cased))
waiter_model = service_waiter_model.get_waiter(waiter)
operation_model = service_model.operation_model(
waiter_model.operation)
description = (
' This polls :py:meth:`{0}.Client.{1}` every {2} '
'seconds until a successful state is reached. An error is '
'returned after {3} failed checks.'.format(
service_name, xform_name(waiter_model.operation),
waiter_model.delay, waiter_model.max_attempts)
)
waiter_spec_doc += document_operation(
operation_model=operation_model, service_name=service_name,
operation_name='wait', rtype=None, description=description,
example_instance='client.get_waiter(\'{0}\')'.format(
snake_cased))
waiter_spec_doc += '\n'
return waiter_spec_doc
def document_resource(service_name, official_name, resource_model,
service_model, session):
"""
Generate reference documentation from a resource model.
"""
model_name = resource_model.name
title = model_name
is_service_resource = False
if model_name == service_name:
model_name = 'Service'
title = 'Service Resource'
is_service_resource = True
docs = '{0}\n{1}\n\n'.format(title, '-' * len(title))
docs += '.. py:class:: {0}.{1}({2})\n\n'.format(
service_name, model_name,
', '.join([xform_name(i.name) for i in resource_model.identifiers]))
if is_service_resource:
docs += (' A resource representing {0}::\n\n').format(official_name)
docs += ' import boto3\n\n'
docs += ' {service} = boto3.resource(\'{service}\')\n\n'.format(
service=service_name)
else:
identifiers = ', '.join([
"'{0}'".format(xform_name(i.name))
for i in resource_model.identifiers
])
docs += (' A resource representing an {0} {1}::\n\n').format(
official_name, model_name)
docs += ' import boto3\n\n'
docs += (' {service} = boto3.resource(\'{service}\')\n'
' {var} = {service}.{model}({identifiers})\n\n').format(
var=xform_name(model_name),
service=service_name,
model=model_name,
identifiers=identifiers)
if not is_service_resource:
docs += (' .. rst-class:: admonition-title\n\n Attributes &'
'Identifiers\n\n Attributes & identifiers provide access'
' to the properties of a resource. Attributes are lazy-'
'loaded the first time one is accessed via the'
' :py:meth:`load` method, if it exists.\n\n'
' Identifiers:\n\n')
for identifier in sorted(resource_model.identifiers,
key=lambda i: i.name):
docs += (' .. py:attribute:: {0}\n\n (``string``,'
' **identifier**) The {1}\'s {2} identifier. This'
' attribute **must** be set for the actions below to'
' work.\n\n'.format(xform_name(identifier.name),
resource_model.name, identifier.name))
docs += '\n\n'
if resource_model.shape:
docs += ' Attributes:\n\n'
shape = service_model.shape_for(resource_model.shape)
attributes = resource_model.get_attributes(shape)
for name, (orig_name, member) in sorted(attributes.items()):
docs += (' .. py:attribute:: {0}\n\n (``{1}``)'
' {2}\n\n').format(
xform_name(name), py_type_name(member.type_name),
html_to_rst(member.documentation, indent=6))
docs += (' .. rst-class:: admonition-title\n\n Actions\n\n Actions'
' call operations on resources, automatically handling the'
' passing in of arguments set from identifiers and some'
' attributes.\n\n')
for action in sorted(resource_model.actions, key=lambda i: i.name):
docs += document_action(action, service_name, resource_model,
service_model)
if resource_model.subresources:
docs += (' .. rst-class:: admonition-title\n\n Sub-resources\n\n'
' Sub-resources are methods that create a new instance of a'
' child resource. This resource\'s identifiers get passed'
' along to the child.\n\n')
preset = len(resource_model.identifiers)
if resource_model.subresources:
for subresource in sorted(resource_model.subresources,
key=lambda i: i.name):
identifiers = [
xform_name(i.target) for i in \
subresource.resource.identifiers if i.source == 'input']
docs += ' .. py:method:: {0}({1})\n\n'.format(
subresource.name, ', '.join(identifiers))
docs += (' Create a :py:class:`{0}.{1}`'
' instance.\n\n').format(service_name,
subresource.resource.type)
docs += '\n\n'
if resource_model.references:
docs += (' .. rst-class:: admonition-title\n\n References\n\n'
' References are related resource instances that have'
' a belongs-to relationship.\n\n')
for ref in sorted(resource_model.references, key=lambda i: i.name):
docs += (' .. py:attribute:: {0}\n\n '
'(:py:class:`{1}.{2}`) The related {3} if set,'
' otherwise ``None``.\n\n').format(
xform_name(ref.name), service_name, ref.resource.type,
ref.resource.type)
if resource_model.collections:
docs += (' .. rst-class:: admonition-title\n\n Collections\n\n'
' Collections provide an interface to iterate and'
' manipulate groups of resources.\n\n')
for collection in sorted(resource_model.collections,
key=lambda i: i.name):
docs += (' .. py:attribute:: {0}\n\n '
'(:py:class:`{1}.{2}CollectionManager`)'
' A collection of :py:class:`{3}.{4}` instances. This'
' collection uses the :py:meth:`{5}.Client.{6}` operation'
' to get items.\n\n').format(
xform_name(collection.name), service_name,
collection.name, service_name,
collection.resource.type, service_name,
xform_name(collection.request.operation))
if resource_model.waiters:
docs += (' .. rst-class:: admonition-title\n\n Waiters\n\n'
' Waiters provide an interface to wait for a resource'
' to reach a specific state.\n\n')
service_waiter_model = session.get_waiter_model(service_name)
for waiter in sorted(resource_model.waiters, key=lambda i: i.name):
docs += document_waiter(waiter, service_name, resource_model,
service_model, service_waiter_model)
return docs
def document_resource(service_name, official_name, resource_model,
service_model, session):
"""
Generate reference documentation from a resource model.
"""
model_name = resource_model.name
title = model_name
is_service_resource = False
if model_name == service_name:
model_name = 'Service'
title = 'Service Resource'
is_service_resource = True
docs = '{0}\n{1}\n\n'.format(title, '-' * len(title))
docs += '.. py:class:: {0}.{1}({2})\n\n'.format(
service_name, model_name, ', '.join(
[xform_name(i.name) for i in resource_model.identifiers]))
if is_service_resource:
docs += (' A resource representing {0}::\n\n').format(official_name)
docs += ' import boto3\n\n'
docs += ' {service} = boto3.resource(\'{service}\')\n\n'.format(
service=service_name)
else:
identifiers = ', '.join(
["'{0}'".format(xform_name(i.name)) for i in
resource_model.identifiers])
docs += (' A resource representing an {0} {1}::\n\n').format(
official_name, model_name)
docs += ' import boto3\n\n'
docs += (' {service} = boto3.resource(\'{service}\')\n'
' {var} = {service}.{model}({identifiers})\n\n').format(
var=xform_name(model_name), service=service_name,
model=model_name, identifiers=identifiers)
if not is_service_resource:
docs += (' .. rst-class:: admonition-title\n\n Attributes &'
'Identifiers\n\n Attributes & identifiers provide access'
' to the properties of a resource. Attributes are lazy-'
'loaded the first time one is accessed via the'
' :py:meth:`load` method, if it exists.\n\n'
' Identifiers:\n\n')
for identifier in sorted(resource_model.identifiers,
key=lambda i:i.name):
docs += (' .. py:attribute:: {0}\n\n (``string``,'
' **identifier**) The {1}\'s {2} identifier. This'
' attribute **must** be set for the actions below to'
' work.\n\n'.format(
xform_name(identifier.name), resource_model.name,
identifier.name))
docs += '\n\n'
if resource_model.shape:
docs += ' Attributes:\n\n'
shape = service_model.shape_for(resource_model.shape)
attributes = resource_model.get_attributes(shape)
for name, (orig_name, member) in sorted(attributes.items()):
docs += (' .. py:attribute:: {0}\n\n (``{1}``)'
' {2}\n\n').format(
xform_name(name), py_type_name(member.type_name),
html_to_rst(member.documentation, indent=6))
docs += (' .. rst-class:: admonition-title\n\n Actions\n\n Actions'
' call operations on resources, automatically handling the'
' passing in of arguments set from identifiers and some'
' attributes.\n\n')
for action in sorted(resource_model.actions, key=lambda i:i.name):
docs += document_action(action, service_name, resource_model,
service_model)
if resource_model.subresources:
docs += (' .. rst-class:: admonition-title\n\n Sub-resources\n\n'
' Sub-resources are methods that create a new instance of a'
' child resource. This resource\'s identifiers get passed'
' along to the child.\n\n')
preset = len(resource_model.identifiers)
if resource_model.subresources:
for subresource in sorted(resource_model.subresources,
key=lambda i: i.name):
identifiers = [
xform_name(i.target) for i in \
subresource.resource.identifiers if i.source == 'input']
docs += ' .. py:method:: {0}({1})\n\n'.format(
subresource.name,
', '.join(identifiers))
docs += (' Create a :py:class:`{0}.{1}`'
' instance.\n\n').format(service_name,
subresource.resource.type)
docs += '\n\n'
if resource_model.references:
docs += (' .. rst-class:: admonition-title\n\n References\n\n'
' References are related resource instances that have'
' a belongs-to relationship.\n\n')
for ref in sorted(resource_model.references, key=lambda i: i.name):
docs += (' .. py:attribute:: {0}\n\n '
'(:py:class:`{1}.{2}`) The related {3} if set,'
' otherwise ``None``.\n\n').format(
xform_name(ref.name), service_name,
ref.resource.type, ref.resource.type)
if resource_model.collections:
docs += (' .. rst-class:: admonition-title\n\n Collections\n\n'
' Collections provide an interface to iterate and'
' manipulate groups of resources.\n\n')
for collection in sorted(resource_model.collections,
key=lambda i: i.name):
docs += (' .. py:attribute:: {0}\n\n '
'(:py:class:`{1}.{2}CollectionManager`)'
' A collection of :py:class:`{3}.{4}` instances. This'
' collection uses the :py:meth:`{5}.Client.{6}` operation'
' to get items.\n\n').format(
xform_name(collection.name), service_name,
collection.name, service_name,
collection.resource.type, service_name,
xform_name(collection.request.operation))
if resource_model.waiters:
docs += (' .. rst-class:: admonition-title\n\n Waiters\n\n'
' Waiters provide an interface to wait for a resource'
' to reach a specific state.\n\n')
service_waiter_model = session.get_waiter_model(service_name)
for waiter in sorted(resource_model.waiters,
key=lambda i: i.name):
docs += document_waiter(waiter, service_name, resource_model,
service_model, service_waiter_model)
return docs
