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 )