def _add_attributes(self, section):
service_model = self._resource.meta.client.meta.service_model
attributes = {}
if self._resource.meta.resource_model.shape:
shape = service_model.shape_for(
self._resource.meta.resource_model.shape)
attributes = self._resource.meta.resource_model.get_attributes(
shape)
section = section.add_new_section('attributes')
attribute_list = []
if attributes:
add_resource_type_overview(
section=section,
resource_type='Attributes',
description=(
'Attributes provide access'
' to the properties of a resource. Attributes are lazy-'
'loaded the first time one is accessed via the'
' :py:meth:`load` method.'),
intro_link='identifiers_attributes_intro')
self.member_map['attributes'] = attribute_list
for attr_name in sorted(attributes):
_, attr_shape = attributes[attr_name]
attribute_section = section.add_new_section(attr_name)
attribute_list.append(attr_name)
document_attribute(
section=attribute_section,
service_name=self._service_name,
resource_name=self._resource_name,
attr_name=attr_name,
event_emitter=self._resource.meta.client.meta.events,
attr_model=attr_shape
)
def document_sub_resources(self, section):
add_resource_type_overview(
section=section,
resource_type='Sub-resources',
description=(
'Sub-resources are methods that create a new instance of a'
' child resource. This resource\'s identifiers get passed'
' along to the child.'),
intro_link='subresources_intro',
)
sub_resources = sorted(
self._resource.meta.resource_model.subresources,
key=lambda sub_resource: sub_resource.name,
)
sub_resources_list = []
self.member_map['sub-resources'] = sub_resources_list
for sub_resource in sub_resources:
sub_resource_section = section.add_new_section(sub_resource.name)
sub_resources_list.append(sub_resource.name)
document_sub_resource(
section=sub_resource_section,
resource_name=self._resource_name,
sub_resource_model=sub_resource,
service_model=self._service_model,
)
def _add_attributes(self, section):
service_model = self._resource.meta.client.meta.service_model
attributes = {}
if self._resource.meta.resource_model.shape:
shape = service_model.shape_for(
self._resource.meta.resource_model.shape)
attributes = self._resource.meta.resource_model.get_attributes(
shape)
section = section.add_new_section('attributes')
attribute_list = []
if attributes:
add_resource_type_overview(
section=section,
resource_type='Attributes',
description=(
'Attributes provide access'
' to the properties of a resource. Attributes are lazy-'
'loaded the first time one is accessed via the'
' :py:meth:`load` method.'),
intro_link='identifiers_attributes_intro')
self.member_map['attributes'] = attribute_list
for attr_name in sorted(attributes):
_, attr_shape = attributes[attr_name]
attribute_section = section.add_new_section(attr_name)
attribute_list.append(attr_name)
document_attribute(section=attribute_section,
attr_name=attr_name,
attr_model=attr_shape)
def _add_attributes(self, section):
service_model = self._resource.meta.client.meta.service_model
attributes = {}
if self._resource.meta.resource_model.shape:
shape = service_model.shape_for(
self._resource.meta.resource_model.shape)
attributes = self._resource.meta.resource_model.get_attributes(
shape)
section = section.add_new_section('attributes')
attribute_list = []
if attributes:
add_resource_type_overview(
section=section,
resource_type='Attributes',
description=(
'Attributes provide access'
' to the properties of a resource. Attributes are lazy-'
'loaded the first time one is accessed via the'
' :py:meth:`load` method.'),
intro_link='identifiers_attributes_intro')
self.member_map['attributes'] = attribute_list
for attr_name, (_, attr_shape) in attributes.items():
attribute_section = section.add_new_section(attr_name)
attribute_list.append(attr_name)
attribute_section.style.start_sphinx_py_attr(attr_name)
attr_type = '*(%s)* ' % py_type_name(attr_shape.type_name)
attribute_section.write(attr_type)
attribute_section.include_doc_string(attr_shape.documentation)
def document_actions(self, section):
modeled_actions_list = self._resource_model.actions
modeled_actions = {}
for modeled_action in modeled_actions_list:
modeled_actions[modeled_action.name] = modeled_action
resource_actions = get_resource_public_actions(
self._resource.__class__)
self.member_map['actions'] = sorted(resource_actions)
add_resource_type_overview(
section=section,
resource_type='Actions',
description=(
'Actions call operations on resources. They may '
'automatically handle the passing in of arguments set '
'from identifiers and some attributes.'),
intro_link='actions_intro')
for action_name in sorted(resource_actions):
action_section = section.add_new_section(action_name)
if action_name in ['load', 'reload'] and self._resource_model.load:
self._document_load_reload_action(action_section, action_name,
self._resource_model.load)
elif action_name in modeled_actions:
self._document_modeled_action(action_section,
modeled_actions[action_name])
else:
document_custom_method(section, action_name,
resource_actions[action_name])
def _add_attributes(self, section):
service_model = self._resource.meta.client.meta.service_model
attributes = {}
if self._resource.meta.resource_model.shape:
shape = service_model.shape_for(self._resource.meta.resource_model.shape)
attributes = self._resource.meta.resource_model.get_attributes(shape)
section = section.add_new_section("attributes")
attribute_list = []
if attributes:
add_resource_type_overview(
section=section,
resource_type="Attributes",
description=(
"Attributes provide access"
" to the properties of a resource. Attributes are lazy-"
"loaded the first time one is accessed via the"
" :py:meth:`load` method."
),
intro_link="identifiers_attributes_intro",
)
self.member_map["attributes"] = attribute_list
for attr_name in sorted(attributes):
_, attr_shape = attributes[attr_name]
attribute_section = section.add_new_section(attr_name)
attribute_list.append(attr_name)
attribute_section.style.start_sphinx_py_attr(attr_name)
attr_type = "*(%s)* " % py_type_name(attr_shape.type_name)
attribute_section.write(attr_type)
attribute_section.include_doc_string(attr_shape.documentation)
def document_actions(self, section):
modeled_actions_list = self._resource_model.actions
modeled_actions = {}
for modeled_action in modeled_actions_list:
modeled_actions[modeled_action.name] = modeled_action
resource_actions = get_resource_public_actions(
self._resource.__class__)
self.member_map['actions'] = sorted(resource_actions)
add_resource_type_overview(
section=section,
resource_type='Actions',
description=(
'Actions call operations on resources. They may '
'automatically handle the passing in of arguments set '
'from identifiers and some attributes.'),
intro_link='actions_intro')
for action_name in sorted(resource_actions):
action_section = section.add_new_section(action_name)
if action_name in ['load', 'reload'] and self._resource_model.load:
self._document_load_reload_action(
action_section, action_name, self._resource_model.load)
elif action_name in modeled_actions:
self._document_modeled_action(
action_section, modeled_actions[action_name])
else:
document_custom_method(
section, action_name, resource_actions[action_name])
def document_resource_waiters(self, section):
waiters = self._resource.meta.resource_model.waiters
add_resource_type_overview(
section=section,
resource_type="Waiters",
description=("Waiters provide an interface to wait for a resource" " to reach a specific state."),
intro_link="waiters_intro",
)
waiter_list = []
self.member_map["waiters"] = waiter_list
for waiter in waiters:
waiter_section = section.add_new_section(waiter.name)
waiter_list.append(waiter.name)
waiter_model = self._service_waiter_model.get_waiter(waiter.waiter_name)
operation_model = self._service_model.operation_model(waiter_model.operation)
ignore_params = get_resource_ignore_params(waiter.params)
description = (
"Waits until this %s is %s. This method calls "
":py:meth:`%s.Waiter.%s.wait` which polls. "
":py:meth:`%s.Client.%s` every %s seconds until "
"a successful state is reached. An error is returned "
"after %s failed checks."
% (
self._resource_name,
" ".join(waiter.name.split("_")[2:]),
self._service_docs_name,
xform_name(waiter.waiter_name),
self._service_docs_name,
xform_name(waiter_model.operation),
waiter_model.delay,
waiter_model.max_attempts,
)
)
example_prefix = "%s.%s" % (xform_name(self._resource_name), waiter.name)
document_model_driven_method(
section=waiter_section,
method_name=waiter.name,
operation_model=operation_model,
event_emitter=self._resource.meta.client.meta.events,
example_prefix=example_prefix,
method_description=description,
exclude_input=ignore_params,
)
if "return" in waiter_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 = waiter_section.get_section("return")
return_section.clear_text()
return_section.remove_all_sections()
return_section.write(":returns: None")
def document_collections(self, section):
collections = self._resource.meta.resource_model.collections
collections_list = []
add_resource_type_overview(
section=section,
resource_type="Collections",
description=("Collections provide an interface to iterate over and " "manipulate groups of resources. "),
intro_link="guide_collections",
)
self.member_map["collections"] = collections_list
for collection in collections:
collection_section = section.add_new_section(collection.name)
collections_list.append(collection.name)
self._document_collection(collection_section, collection)
def document_resource_waiters(self, section):
waiters = self._resource.meta.resource_model.waiters
add_resource_type_overview(
section=section,
resource_type='Waiters',
description=(
'Waiters provide an interface to wait for a resource'
' to reach a specific state.'),
intro_link='waiters_intro')
waiter_list = []
self.member_map['waiters'] = waiter_list
for waiter in waiters:
waiter_section = section.add_new_section(waiter.name)
waiter_list.append(waiter.name)
waiter_model = self._service_waiter_model.get_waiter(
waiter.waiter_name)
operation_model = self._service_model.operation_model(
waiter_model.operation)
ignore_params = get_resource_ignore_params(waiter.params)
description = (
'Waits until this %s is %s. This method calls '
':py:meth:`%s.Waiter.%s.wait` which polls. '
':py:meth:`%s.Client.%s` every %s seconds until '
'a successful state is reached. An error is returned '
'after %s failed checks.' % (
self._resource_name, ' '.join(waiter.name.split('_')[2:]),
self._service_docs_name, xform_name(waiter.waiter_name),
self._service_docs_name,
xform_name(waiter_model.operation),
waiter_model.delay, waiter_model.max_attempts))
example_prefix = '%s.%s' % (
xform_name(self._resource_name), waiter.name)
document_model_driven_method(
section=waiter_section, method_name=waiter.name,
operation_model=operation_model,
event_emitter=self._resource.meta.client.meta.events,
example_prefix=example_prefix,
method_description=description,
exclude_input=ignore_params
)
if 'return' in waiter_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 = waiter_section.get_section('return')
return_section.clear_text()
return_section.remove_all_sections()
return_section.write(':returns: None')
def document_collections(self, section):
collections = self._resource.meta.resource_model.collections
collections_list = []
add_resource_type_overview(
section=section,
resource_type='Collections',
description=(
'Collections provide an interface to iterate over and '
'manipulate groups of resources. '),
intro_link='guide_collections')
self.member_map['collections'] = collections_list
for collection in collections:
collection_section = section.add_new_section(collection.name)
collections_list.append(collection.name)
self._document_collection(collection_section, collection)
def _add_references(self, section):
section = section.add_new_section('references')
references = self._resource.meta.resource_model.references
reference_list = []
if references:
add_resource_type_overview(
section=section,
resource_type='References',
description=(
'References are related resource instances that have '
'a belongs-to relationship.'),
intro_link='references_intro')
self.member_map['references'] = reference_list
for reference in references:
reference_section = section.add_new_section(reference.name)
reference_list.append(reference.name)
document_reference(section=reference_section,
reference_model=reference)
def _add_references(self, section):
section = section.add_new_section("references")
references = self._resource.meta.resource_model.references
reference_list = []
if references:
add_resource_type_overview(
section=section,
resource_type="References",
description=("References are related resource instances that have " "a belongs-to relationship."),
intro_link="references_intro",
)
self.member_map["references"] = reference_list
for reference in references:
reference_section = section.add_new_section(reference.name)
reference_list.append(reference.name)
reference_section.style.start_sphinx_py_attr(reference.name)
reference_type = "(:py:class:`%s`) " % reference.resource.type
reference_section.write(reference_type)
reference_section.include_doc_string("The related %s if set, otherwise ``None``." % reference.name)
def document_sub_resources(self, section):
add_resource_type_overview(
section=section,
resource_type='Sub-resources',
description=(
'Sub-resources are methods that create a new instance of a'
' child resource. This resource\'s identifiers get passed'
' along to the child.'),
intro_link='subresources_intro')
sub_resources = sorted(
self._resource.meta.resource_model.subresources,
key=lambda sub_resource: sub_resource.name
)
sub_resources_list = []
self.member_map['sub-resources'] = sub_resources_list
for sub_resource in sub_resources:
sub_resource_section = section.add_new_section(sub_resource.name)
sub_resources_list.append(sub_resource.name)
self._document_sub_resource(sub_resource_section, sub_resource)
def _add_identifiers(self, section):
identifiers = self._resource.meta.resource_model.identifiers
section = section.add_new_section('identifiers')
member_list = []
if identifiers:
self.member_map['identifiers'] = member_list
add_resource_type_overview(
section=section,
resource_type='Identifiers',
description=(
'Identifiers are properties of a resource that are '
'set upon instantation of the resource.'),
intro_link='identifiers_attributes_intro')
for identifier in identifiers:
identifier_section = section.add_new_section(identifier.name)
member_list.append(identifier.name)
document_identifier(section=identifier_section,
resource_name=self._resource_name,
identifier_model=identifier)
def document_resource_waiters(self, section):
waiters = self._resource.meta.resource_model.waiters
add_resource_type_overview(
section=section,
resource_type='Waiters',
description=('Waiters provide an interface to wait for a resource'
' to reach a specific state.'),
intro_link='waiters_intro')
waiter_list = []
self.member_map['waiters'] = waiter_list
for waiter in waiters:
waiter_section = section.add_new_section(waiter.name)
waiter_list.append(waiter.name)
document_resource_waiter(
section=waiter_section,
resource_name=self._resource_name,
event_emitter=self._resource.meta.client.meta.events,
service_model=self._service_model,
resource_waiter_model=waiter,
service_waiter_model=self._service_waiter_model)
def _add_references(self, section):
section = section.add_new_section('references')
references = self._resource.meta.resource_model.references
reference_list = []
if references:
add_resource_type_overview(
section=section,
resource_type='References',
description=(
'References are related resource instances that have '
'a belongs-to relationship.'),
intro_link='references_intro')
self.member_map['references'] = reference_list
for reference in references:
reference_section = section.add_new_section(reference.name)
reference_list.append(reference.name)
document_reference(
section=reference_section,
reference_model=reference
)
def document_resource_waiters(self, section):
waiters = self._resource.meta.resource_model.waiters
add_resource_type_overview(
section=section,
resource_type='Waiters',
description=(
'Waiters provide an interface to wait for a resource'
' to reach a specific state.'),
intro_link='waiters_intro')
waiter_list = []
self.member_map['waiters'] = waiter_list
for waiter in waiters:
waiter_section = section.add_new_section(waiter.name)
waiter_list.append(waiter.name)
waiter_model = self._service_waiter_model.get_waiter(
waiter.waiter_name)
operation_model = self._service_model.operation_model(
waiter_model.operation)
ignore_params = get_resource_ignore_params(waiter.params)
description = (
'Waits until this %s is %s. This method calls '
':py:meth:`%s.Waiter.%s.wait` which polls. '
':py:meth:`%s.Client.%s` every %s seconds until '
'a successful state is reached. An error is returned '
'after %s failed checks.' % (
self._resource_name, ' '.join(waiter.name.split('_')[2:]),
self._service_docs_name, xform_name(waiter.waiter_name),
self._service_docs_name,
xform_name(waiter_model.operation),
waiter_model.delay, waiter_model.max_attempts))
example_prefix = '%s.%s' % (
xform_name(self._resource_name), waiter.name)
document_model_driven_method(
section=waiter_section, method_name=waiter.name,
operation_model=operation_model,
event_emitter=self._resource.meta.client.meta.events,
example_prefix=example_prefix,
method_description=description,
exclude_input=ignore_params
)
def _add_references(self, section):
section = section.add_new_section('references')
references = self._resource.meta.resource_model.references
reference_list = []
if references:
add_resource_type_overview(
section=section,
resource_type='References',
description=(
'References are related resource instances that have '
'a belongs-to relationship.'),
intro_link='references_intro')
self.member_map['references'] = reference_list
for reference in references:
reference_section = section.add_new_section(reference.name)
reference_list.append(reference.name)
reference_section.style.start_sphinx_py_attr(reference.name)
reference_type = '(:py:class:`%s`) ' % reference.resource.type
reference_section.write(reference_type)
reference_section.include_doc_string(
'The related %s if set, otherwise ``None``.' % reference.name)
def _add_identifiers(self, section):
identifiers = self._resource.meta.resource_model.identifiers
section = section.add_new_section('identifiers')
member_list = []
if identifiers:
self.member_map['identifiers'] = member_list
add_resource_type_overview(
section=section,
resource_type='Identifiers',
description=(
'Identifiers are properties of a resource that are '
'set upon instantation of the resource.'),
intro_link='identifiers_attributes_intro')
for identifier in identifiers:
identifier_section = section.add_new_section(identifier.name)
member_list.append(identifier.name)
identifier_section.style.start_sphinx_py_attr(identifier.name)
description = get_identifier_description(
self._resource_name, identifier.name)
description = '*(string)* ' + description
identifier_section.write(description)
def _add_identifiers(self, section):
identifiers = self._resource.meta.resource_model.identifiers
section = section.add_new_section('identifiers')
member_list = []
if identifiers:
self.member_map['identifiers'] = member_list
add_resource_type_overview(
section=section,
resource_type='Identifiers',
description=(
'Identifiers are properties of a resource that are '
'set upon instantation of the resource.'),
intro_link='identifiers_attributes_intro')
for identifier in identifiers:
identifier_section = section.add_new_section(identifier.name)
member_list.append(identifier.name)
document_identifier(
section=identifier_section,
resource_name=self._resource_name,
identifier_model=identifier
)
def document_resource_waiters(self, section):
waiters = self._resource.meta.resource_model.waiters
add_resource_type_overview(
section=section,
resource_type='Waiters',
description=(
'Waiters provide an interface to wait for a resource'
' to reach a specific state.'),
intro_link='waiters_intro')
waiter_list = []
self.member_map['waiters'] = waiter_list
for waiter in waiters:
waiter_section = section.add_new_section(waiter.name)
waiter_list.append(waiter.name)
document_resource_waiter(
section=waiter_section,
resource_name=self._resource_name,
event_emitter=self._resource.meta.client.meta.events,
service_model=self._service_model,
resource_waiter_model=waiter,
service_waiter_model=self._service_waiter_model
)
def _add_references(self, section):
section = section.add_new_section('references')
references = self._resource.meta.resource_model.references
reference_list = []
if references:
add_resource_type_overview(
section=section,
resource_type='References',
description=(
'References are related resource instances that have '
'a belongs-to relationship.'),
intro_link='references_intro')
self.member_map['references'] = reference_list
for reference in references:
reference_section = section.add_new_section(reference.name)
reference_list.append(reference.name)
reference_section.style.start_sphinx_py_attr(reference.name)
reference_type = '(:py:class:`%s`) ' % reference.resource.type
reference_section.write(reference_type)
reference_section.include_doc_string(
'The related %s if set, otherwise ``None``.' % reference.name
)
