Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id 1D8B3200CC4 for ; Thu, 29 Jun 2017 02:07:14 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id 1C727160BF7; Thu, 29 Jun 2017 00:07:14 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id BDDC2160BFC for ; Thu, 29 Jun 2017 02:07:11 +0200 (CEST) Received: (qmail 17302 invoked by uid 500); 29 Jun 2017 00:07:10 -0000 Mailing-List: contact commits-help@ariatosca.incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@ariatosca.incubator.apache.org Delivered-To: mailing list commits@ariatosca.incubator.apache.org Received: (qmail 17293 invoked by uid 99); 29 Jun 2017 00:07:10 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd3-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 29 Jun 2017 00:07:10 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd3-us-west.apache.org (ASF Mail Server at spamd3-us-west.apache.org) with ESMTP id 6D2B6181428 for ; Thu, 29 Jun 2017 00:07:10 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd3-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -4.222 X-Spam-Level: X-Spam-Status: No, score=-4.222 tagged_above=-999 required=6.31 tests=[KAM_ASCII_DIVIDERS=0.8, RCVD_IN_DNSWL_HI=-5, RCVD_IN_MSPIKE_H3=-0.01, RCVD_IN_MSPIKE_WL=-0.01, RP_MATCHES_RCVD=-0.001, SPF_PASS=-0.001] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd3-us-west.apache.org [10.40.0.10]) (amavisd-new, port 10024) with ESMTP id Fr-N_I7yPYqt for ; Thu, 29 Jun 2017 00:06:58 +0000 (UTC) Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with SMTP id 2CF6960DB8 for ; Thu, 29 Jun 2017 00:06:50 +0000 (UTC) Received: (qmail 15996 invoked by uid 99); 29 Jun 2017 00:06:49 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 29 Jun 2017 00:06:49 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id E4473ED4A2; Thu, 29 Jun 2017 00:06:48 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: emblemparade@apache.org To: commits@ariatosca.incubator.apache.org Date: Thu, 29 Jun 2017 00:06:59 -0000 Message-Id: <994e8211128a4310b5c9e850e87b0aae@git.apache.org> In-Reply-To: <5441a2b2b81b4d3990027b685dcdf1e9@git.apache.org> References: <5441a2b2b81b4d3990027b685dcdf1e9@git.apache.org> X-Mailer: ASF-Git Admin Mailer Subject: [12/15] incubator-ariatosca git commit: ARIA-286 Sphinx documentation for code and CLI archived-at: Thu, 29 Jun 2017 00:07:14 -0000 http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/modeling/service_template.py ---------------------------------------------------------------------- diff --git a/aria/modeling/service_template.py b/aria/modeling/service_template.py index 344da6d..57fd672 100644 --- a/aria/modeling/service_template.py +++ b/aria/modeling/service_template.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +ARIA modeling service template module +""" + # pylint: disable=too-many-lines, no-self-argument, no-member, abstract-method from __future__ import absolute_import # so we can import standard 'types' @@ -28,7 +32,6 @@ from sqlalchemy import ( PickleType ) from sqlalchemy.ext.declarative import declared_attr -from sqlalchemy.ext.associationproxy import association_proxy from ..parser import validation from ..parser.consumption import ConsumptionContext @@ -45,116 +48,46 @@ from . import ( class ServiceTemplateBase(TemplateModelMixin): """ - A service template is a source for creating :class:`Service` instances. - - It is usually created by various DSL parsers, such as ARIA's TOSCA extension. However, it can - also be created programmatically. - - :ivar name: Name (unique for this ARIA installation) - :vartype name: basestring - :ivar description: Human-readable description - :vartype description: basestring - :ivar main_file_name: Filename of CSAR or YAML file from which this service template was parsed - :vartype main_file_name: basestring - :ivar meta_data: Custom annotations - :vartype meta_data: {basestring: :class:`Metadata`} - :ivar node_templates: Templates for creating nodes - :vartype node_templates: {basestring: :class:`NodeTemplate`} - :ivar group_templates: Templates for creating groups - :vartype group_templates: {basestring: :class:`GroupTemplate`} - :ivar policy_templates: Templates for creating policies - :vartype policy_templates: {basestring: :class:`PolicyTemplate`} - :ivar substitution_template: The entire service can appear as a node - :vartype substitution_template: :class:`SubstitutionTemplate` - :ivar inputs: Externally provided parameters - :vartype inputs: {basestring: :class:`Input`} - :ivar outputs: These parameters are filled in after service installation - :vartype outputs: {basestring: :class:`Output`} - :ivar workflow_templates: Custom workflows that can be performed on the service - :vartype workflow_templates: {basestring: :class:`OperationTemplate`} - :ivar plugin_specifications: Plugins used by the service - :vartype plugin_specifications: {basestring: :class:`PluginSpecification`} - :ivar node_types: Base for the node type hierarchy - :vartype node_types: :class:`Type` - :ivar group_types: Base for the group type hierarchy - :vartype group_types: :class:`Type` - :ivar policy_types: Base for the policy type hierarchy - :vartype policy_types: :class:`Type` - :ivar relationship_types: Base for the relationship type hierarchy - :vartype relationship_types: :class:`Type` - :ivar capability_types: Base for the capability type hierarchy - :vartype capability_types: :class:`Type` - :ivar interface_types: Base for the interface type hierarchy - :vartype interface_types: :class:`Type` - :ivar artifact_types: Base for the artifact type hierarchy - :vartype artifact_types: :class:`Type` - :ivar created_at: Creation timestamp - :vartype created_at: :class:`datetime.datetime` - :ivar updated_at: Update timestamp - :vartype updated_at: :class:`datetime.datetime` - :ivar services: Instantiated services - :vartype services: [:class:`Service`] + Template for creating :class:`Service` instances. + + Usually created by various DSL parsers, such as ARIA's TOSCA extension. However, it can also be + created programmatically. """ __tablename__ = 'service_template' - __private_fields__ = ['substitution_template_fk', + __private_fields__ = ('substitution_template_fk', 'node_type_fk', 'group_type_fk', 'policy_type_fk', 'relationship_type_fk', 'capability_type_fk', 'interface_type_fk', - 'artifact_type_fk'] - - description = Column(Text) - main_file_name = Column(Text) - created_at = Column(DateTime, nullable=False, index=True) - updated_at = Column(DateTime) - - # region foreign keys - - @declared_attr - def substitution_template_fk(cls): - """For ServiceTemplate one-to-one to SubstitutionTemplate""" - return relationship.foreign_key('substitution_template', nullable=True) - - @declared_attr - def node_type_fk(cls): - """For ServiceTemplate one-to-one to Type""" - return relationship.foreign_key('type', nullable=True) + 'artifact_type_fk') - @declared_attr - def group_type_fk(cls): - """For ServiceTemplate one-to-one to Type""" - return relationship.foreign_key('type', nullable=True) + description = Column(Text, doc=""" + Human-readable description. - @declared_attr - def policy_type_fk(cls): - """For ServiceTemplate one-to-one to Type""" - return relationship.foreign_key('type', nullable=True) + :type: :obj:`basestring` + """) - @declared_attr - def relationship_type_fk(cls): - """For ServiceTemplate one-to-one to Type""" - return relationship.foreign_key('type', nullable=True) + main_file_name = Column(Text, doc=""" + Filename of CSAR or YAML file from which this service template was parsed. + + :type: :obj:`basestring` + """) - @declared_attr - def capability_type_fk(cls): - """For ServiceTemplate one-to-one to Type""" - return relationship.foreign_key('type', nullable=True) + created_at = Column(DateTime, nullable=False, index=True, doc=""" + Creation timestamp. - @declared_attr - def interface_type_fk(cls): - """For ServiceTemplate one-to-one to Type""" - return relationship.foreign_key('type', nullable=True) + :type: :class:`~datetime.datetime` + """) - @declared_attr - def artifact_type_fk(cls): - """For ServiceTemplate one-to-one to Type""" - return relationship.foreign_key('type', nullable=True) + updated_at = Column(DateTime, doc=""" + Update timestamp. - # endregion + :type: :class:`~datetime.datetime` + """) # region association proxies @@ -164,41 +97,81 @@ class ServiceTemplateBase(TemplateModelMixin): @declared_attr def substitution_template(cls): + """ + Exposes an entire service as a single node. + + :type: :class:`SubstitutionTemplate` + """ return relationship.one_to_one( cls, 'substitution_template', back_populates=relationship.NO_BACK_POP) @declared_attr def node_types(cls): + """ + Base for the node type hierarchy, + + :type: :class:`Type` + """ return relationship.one_to_one( cls, 'type', fk='node_type_fk', back_populates=relationship.NO_BACK_POP) @declared_attr def group_types(cls): + """ + Base for the group type hierarchy, + + :type: :class:`Type` + """ return relationship.one_to_one( cls, 'type', fk='group_type_fk', back_populates=relationship.NO_BACK_POP) @declared_attr def policy_types(cls): + """ + Base for the policy type hierarchy, + + :type: :class:`Type` + """ return relationship.one_to_one( cls, 'type', fk='policy_type_fk', back_populates=relationship.NO_BACK_POP) @declared_attr def relationship_types(cls): + """ + Base for the relationship type hierarchy, + + :type: :class:`Type` + """ return relationship.one_to_one( cls, 'type', fk='relationship_type_fk', back_populates=relationship.NO_BACK_POP) @declared_attr def capability_types(cls): + """ + Base for the capability type hierarchy, + + :type: :class:`Type` + """ return relationship.one_to_one( cls, 'type', fk='capability_type_fk', back_populates=relationship.NO_BACK_POP) @declared_attr def interface_types(cls): + """ + Base for the interface type hierarchy, + + :type: :class:`Type` + """ return relationship.one_to_one( cls, 'type', fk='interface_type_fk', back_populates=relationship.NO_BACK_POP) @declared_attr def artifact_types(cls): + """ + Base for the artifact type hierarchy, + + :type: :class:`Type` + """ return relationship.one_to_one( cls, 'type', fk='artifact_type_fk', back_populates=relationship.NO_BACK_POP) @@ -208,34 +181,74 @@ class ServiceTemplateBase(TemplateModelMixin): @declared_attr def services(cls): + """ + Instantiated services. + + :type: [:class:`Service`] + """ return relationship.one_to_many(cls, 'service', dict_key='name') @declared_attr def node_templates(cls): - return relationship.one_to_many(cls, 'node_template', dict_key='name') - - @declared_attr - def outputs(cls): - return relationship.one_to_many(cls, 'output', dict_key='name') + """ + Templates for creating nodes. - @declared_attr - def inputs(cls): - return relationship.one_to_many(cls, 'input', dict_key='name') + :type: {:obj:`basestring`, :class:`NodeTemplate`} + """ + return relationship.one_to_many(cls, 'node_template', dict_key='name') @declared_attr def group_templates(cls): + """ + Templates for creating groups. + + :type: {:obj:`basestring`, :class:`GroupTemplate`} + """ return relationship.one_to_many(cls, 'group_template', dict_key='name') @declared_attr def policy_templates(cls): + """ + Templates for creating policies. + + :type: {:obj:`basestring`, :class:`PolicyTemplate`} + """ return relationship.one_to_many(cls, 'policy_template', dict_key='name') @declared_attr def workflow_templates(cls): + """ + Templates for creating workflows. + + :type: {:obj:`basestring`, :class:`OperationTemplate`} + """ return relationship.one_to_many(cls, 'operation_template', dict_key='name') @declared_attr + def outputs(cls): + """ + Declarations for output parameters are filled in after service installation. + + :type: {:obj:`basestring`: :class:`Output`} + """ + return relationship.one_to_many(cls, 'output', dict_key='name') + + @declared_attr + def inputs(cls): + """ + Declarations for externally provided parameters. + + :type: {:obj:`basestring`: :class:`Input`} + """ + return relationship.one_to_many(cls, 'input', dict_key='name') + + @declared_attr def plugin_specifications(cls): + """ + Required plugins for instantiated services. + + :type: {:obj:`basestring`: :class:`PluginSpecification`} + """ return relationship.one_to_many(cls, 'plugin_specification', dict_key='name') # endregion @@ -248,11 +261,60 @@ class ServiceTemplateBase(TemplateModelMixin): @declared_attr def meta_data(cls): + """ + Associated metadata. + + :type: {:obj:`basestring`: :class:`Metadata`} + """ # Warning! We cannot use the attr name "metadata" because it's used by SQLAlchemy! return relationship.many_to_many(cls, 'metadata', dict_key='name') # endregion + # region foreign keys + + @declared_attr + def substitution_template_fk(cls): + """For ServiceTemplate one-to-one to SubstitutionTemplate""" + return relationship.foreign_key('substitution_template', nullable=True) + + @declared_attr + def node_type_fk(cls): + """For ServiceTemplate one-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + @declared_attr + def group_type_fk(cls): + """For ServiceTemplate one-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + @declared_attr + def policy_type_fk(cls): + """For ServiceTemplate one-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + @declared_attr + def relationship_type_fk(cls): + """For ServiceTemplate one-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + @declared_attr + def capability_type_fk(cls): + """For ServiceTemplate one-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + @declared_attr + def interface_type_fk(cls): + """For ServiceTemplate one-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + @declared_attr + def artifact_type_fk(cls): + """For ServiceTemplate one-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + # endregion + @property def as_raw(self): return collections.OrderedDict(( @@ -397,75 +459,24 @@ class ServiceTemplateBase(TemplateModelMixin): class NodeTemplateBase(TemplateModelMixin): """ - A template for creating zero or more :class:`Node` instances. - - :ivar name: Name (unique for this service template; will usually be used as a prefix for node - names) - :vartype name: basestring - :ivar type: Node type - :vartype type: :class:`Type` - :ivar description: Human-readable description - :vartype description: basestring - :ivar default_instances: Default number nodes that will appear in the service - :vartype default_instances: int - :ivar min_instances: Minimum number nodes that will appear in the service - :vartype min_instances: int - :ivar max_instances: Maximum number nodes that will appear in the service - :vartype max_instances: int - :ivar properties: Associated parameters - :vartype properties: {basestring: :class:`Property`} - :ivar interface_templates: Bundles of operations - :vartype interface_templates: {basestring: :class:`InterfaceTemplate`} - :ivar artifact_templates: Associated files - :vartype artifact_templates: {basestring: :class:`ArtifactTemplate`} - :ivar capability_templates: Exposed capabilities - :vartype capability_templates: {basestring: :class:`CapabilityTemplate`} - :ivar requirement_templates: Potential relationships with other nodes - :vartype requirement_templates: [:class:`RequirementTemplate`] - :ivar target_node_template_constraints: Constraints for filtering relationship targets - :vartype target_node_template_constraints: [:class:`NodeTemplateConstraint`] - :ivar service_template: Containing service template - :vartype service_template: :class:`ServiceTemplate` - :ivar group_templates: We are a member of these groups - :vartype group_templates: [:class:`GroupTemplate`] - :ivar policy_templates: Policy templates enacted on this node - :vartype policy_templates: [:class:`PolicyTemplate`] - :ivar substitution_template_mapping: Our contribution to service substitution - :vartype substitution_template_mapping: :class:`SubstitutionTemplateMapping` - :ivar nodes: Instantiated nodes - :vartype nodes: [:class:`Node`] + Template for creating zero or more :class:`Node` instances, which are typed vertices in the + service topology. """ __tablename__ = 'node_template' - __private_fields__ = ['type_fk', - 'service_template_fk'] - - # region foreign_keys - - @declared_attr - def type_fk(cls): - """For NodeTemplate many-to-one to Type""" - return relationship.foreign_key('type') - - @declared_attr - def service_template_fk(cls): - """For ServiceTemplate one-to-many to NodeTemplate""" - return relationship.foreign_key('service_template') - - # endregion + __private_fields__ = ('type_fk', + 'service_template_fk') # region association proxies @declared_attr def service_template_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('service_template', 'name') + return relationship.association_proxy('service_template', 'name') @declared_attr def type_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('type', 'name') + return relationship.association_proxy('type', 'name') # endregion @@ -477,30 +488,65 @@ class NodeTemplateBase(TemplateModelMixin): @declared_attr def nodes(cls): + """ + Instantiated nodes. + + :type: [:class:`Node`] + """ return relationship.one_to_many(cls, 'node') @declared_attr def interface_templates(cls): + """ + Associated interface templates. + + :type: {:obj:`basestring`: :class:`InterfaceTemplate`} + """ return relationship.one_to_many(cls, 'interface_template', dict_key='name') @declared_attr def artifact_templates(cls): + """ + Associated artifacts. + + :type: {:obj:`basestring`: :class:`ArtifactTemplate`} + """ return relationship.one_to_many(cls, 'artifact_template', dict_key='name') @declared_attr def capability_templates(cls): + """ + Associated exposed capability templates. + + :type: {:obj:`basestring`: :class:`CapabilityTemplate`} + """ return relationship.one_to_many(cls, 'capability_template', dict_key='name') @declared_attr def requirement_templates(cls): + """ + Associated potential relationships with other nodes. + + :type: [:class:`RequirementTemplate`] + """ return relationship.one_to_many(cls, 'requirement_template', other_fk='node_template_fk') @declared_attr def properties(cls): + """ + Declarations for associated immutable parameters. + + :type: {:obj:`basestring`: :class:`Property`} + """ return relationship.one_to_many(cls, 'property', dict_key='name') @declared_attr def attributes(cls): + """ + Declarations for associated mutable parameters. + + :type: {:obj:`basestring`: :class:`Attribute`} + """ return relationship.one_to_many(cls, 'attribute', dict_key='name') # endregion @@ -509,19 +555,67 @@ class NodeTemplateBase(TemplateModelMixin): @declared_attr def type(cls): + """ + Node type. + + :type: :class:`Type` + """ return relationship.many_to_one(cls, 'type', back_populates=relationship.NO_BACK_POP) @declared_attr def service_template(cls): + """ + Containing service template. + + :type: :class:`ServiceTemplate` + """ return relationship.many_to_one(cls, 'service_template') # endregion - description = Column(Text) - default_instances = Column(Integer, default=1) - min_instances = Column(Integer, default=0) - max_instances = Column(Integer, default=None) - target_node_template_constraints = Column(PickleType) + # region foreign_keys + + @declared_attr + def type_fk(cls): + """For NodeTemplate many-to-one to Type""" + return relationship.foreign_key('type') + + @declared_attr + def service_template_fk(cls): + """For ServiceTemplate one-to-many to NodeTemplate""" + return relationship.foreign_key('service_template') + + # endregion + + description = Column(Text, doc=""" + Human-readable description. + + :type: :obj:`basestring` + """) + + default_instances = Column(Integer, default=1, doc=""" + Default number nodes that will appear in the service. + + :type: :obj:`int` + """) + + min_instances = Column(Integer, default=0, doc=""" + Minimum number nodes that will appear in the service. + + :type: :obj:`int` + """) + + max_instances = Column(Integer, default=None, doc=""" + Maximum number nodes that will appear in the service. + + :type: :obj:`int` + """) + + target_node_template_constraints = Column(PickleType, doc=""" + Constraints for filtering relationship targets. + + :type: [:class:`NodeTemplateConstraint`] + """) def is_target_node_template_valid(self, target_node_template): if self.target_node_template_constraints: @@ -612,48 +706,14 @@ class NodeTemplateBase(TemplateModelMixin): class GroupTemplateBase(TemplateModelMixin): """ - A template for creating a :class:`Group` instance. - - Groups are logical containers for zero or more nodes. - - :ivar name: Name (unique for this service template) - :vartype name: basestring - :ivar type: Group type - :vartype type: :class:`Type` - :ivar description: Human-readable description - :vartype description: basestring - :ivar node_templates: All nodes instantiated by these templates will be members of the group - :vartype node_templates: [:class:`NodeTemplate`] - :ivar properties: Associated parameters - :vartype properties: {basestring: :class:`Property`} - :ivar interface_templates: Bundles of operations - :vartype interface_templates: {basestring: :class:`InterfaceTemplate`} - :ivar service_template: Containing service template - :vartype service_template: :class:`ServiceTemplate` - :ivar policy_templates: Policy templates enacted on this group - :vartype policy_templates: [:class:`PolicyTemplate`] - :ivar groups: Instantiated groups - :vartype groups: [:class:`Group`] + Template for creating a :class:`Group` instance, which is a typed logical container for zero or + more :class:`Node` instances. """ __tablename__ = 'group_template' - __private_fields__ = ['type_fk', - 'service_template_fk'] - - # region foreign keys - - @declared_attr - def type_fk(cls): - """For GroupTemplate many-to-one to Type""" - return relationship.foreign_key('type') - - @declared_attr - def service_template_fk(cls): - """For ServiceTemplate one-to-many to GroupTemplate""" - return relationship.foreign_key('service_template') - - # endregion + __private_fields__ = ('type_fk', + 'service_template_fk') # region association proxies @@ -667,14 +727,29 @@ class GroupTemplateBase(TemplateModelMixin): @declared_attr def groups(cls): + """ + Instantiated groups. + + :type: [:class:`Group`] + """ return relationship.one_to_many(cls, 'group') @declared_attr def interface_templates(cls): + """ + Associated interface templates. + + :type: {:obj:`basestring`: :class:`InterfaceTemplate`} + """ return relationship.one_to_many(cls, 'interface_template', dict_key='name') @declared_attr def properties(cls): + """ + Declarations for associated immutable parameters. + + :type: {:obj:`basestring`: :class:`Property`} + """ return relationship.one_to_many(cls, 'property', dict_key='name') # endregion @@ -683,10 +758,20 @@ class GroupTemplateBase(TemplateModelMixin): @declared_attr def service_template(cls): + """ + Containing service template. + + :type: :class:`ServiceTemplate` + """ return relationship.many_to_one(cls, 'service_template') @declared_attr def type(cls): + """ + Group type. + + :type: :class:`Type` + """ return relationship.many_to_one(cls, 'type', back_populates=relationship.NO_BACK_POP) # endregion @@ -695,11 +780,34 @@ class GroupTemplateBase(TemplateModelMixin): @declared_attr def node_templates(cls): + """ + Nodes instantiated by these templates will be members of the group. + + :type: [:class:`NodeTemplate`] + """ return relationship.many_to_many(cls, 'node_template') # endregion - description = Column(Text) + # region foreign keys + + @declared_attr + def type_fk(cls): + """For GroupTemplate many-to-one to Type""" + return relationship.foreign_key('type') + + @declared_attr + def service_template_fk(cls): + """For ServiceTemplate one-to-many to GroupTemplate""" + return relationship.foreign_key('service_template') + + # endregion + + description = Column(Text, doc=""" + Human-readable description. + + :type: :obj:`basestring` + """) @property def as_raw(self): @@ -747,44 +855,14 @@ class GroupTemplateBase(TemplateModelMixin): class PolicyTemplateBase(TemplateModelMixin): """ - Policies can be applied to zero or more :class:`NodeTemplate` or :class:`GroupTemplate` - instances. - - :ivar name: Name (unique for this service template) - :vartype name: basestring - :ivar type: Policy type - :vartype type: :class:`Type` - :ivar description: Human-readable description - :vartype description: basestring - :ivar node_templates: Policy will be enacted on all nodes instantiated by these templates - :vartype node_templates: [:class:`NodeTemplate`] - :ivar group_templates: Policy will be enacted on all nodes in these groups - :vartype group_templates: [:class:`GroupTemplate`] - :ivar properties: Associated parameters - :vartype properties: {basestring: :class:`Property`} - :ivar service_template: Containing service template - :vartype service_template: :class:`ServiceTemplate` - :ivar policies: Instantiated policies - :vartype policies: [:class:`Policy`] + Template for creating a :class:`Policy` instance, which is a typed set of orchestration hints + applied to zero or more :class:`Node` or :class:`Group` instances. """ __tablename__ = 'policy_template' - __private_fields__ = ['type_fk', 'service_template_fk'] - - # region foreign keys - - @declared_attr - def type_fk(cls): - """For PolicyTemplate many-to-one to Type""" - return relationship.foreign_key('type') - - @declared_attr - def service_template_fk(cls): - """For ServiceTemplate one-to-many to PolicyTemplate""" - return relationship.foreign_key('service_template') - - # endregion + __private_fields__ = ('type_fk', + 'service_template_fk') # region association proxies @@ -798,10 +876,20 @@ class PolicyTemplateBase(TemplateModelMixin): @declared_attr def policies(cls): + """ + Instantiated policies. + + :type: [:class:`Policy`] + """ return relationship.one_to_many(cls, 'policy') @declared_attr def properties(cls): + """ + Declarations for associated immutable parameters. + + :type: {:obj:`basestring`: :class:`Property`} + """ return relationship.one_to_many(cls, 'property', dict_key='name') # endregion @@ -810,10 +898,20 @@ class PolicyTemplateBase(TemplateModelMixin): @declared_attr def service_template(cls): + """ + Containing service template. + + :type: :class:`ServiceTemplate` + """ return relationship.many_to_one(cls, 'service_template') @declared_attr def type(cls): + """ + Policy type. + + :type: :class:`Type` + """ return relationship.many_to_one(cls, 'type', back_populates=relationship.NO_BACK_POP) # endregion @@ -822,15 +920,43 @@ class PolicyTemplateBase(TemplateModelMixin): @declared_attr def node_templates(cls): + """ + Policy will be enacted on all nodes instantiated by these templates. + + :type: {:obj:`basestring`: :class:`NodeTemplate`} + """ return relationship.many_to_many(cls, 'node_template') @declared_attr def group_templates(cls): + """ + Policy will be enacted on all nodes in all groups instantiated by these templates. + + :type: {:obj:`basestring`: :class:`GroupTemplate`} + """ return relationship.many_to_many(cls, 'group_template') # endregion - description = Column(Text) + # region foreign keys + + @declared_attr + def type_fk(cls): + """For PolicyTemplate many-to-one to Type""" + return relationship.foreign_key('type') + + @declared_attr + def service_template_fk(cls): + """For ServiceTemplate one-to-many to PolicyTemplate""" + return relationship.foreign_key('service_template') + + # endregion + + description = Column(Text, doc=""" + Human-readable description. + + :type: :obj:`basestring` + """) @property def as_raw(self): @@ -879,30 +1005,13 @@ class PolicyTemplateBase(TemplateModelMixin): class SubstitutionTemplateBase(TemplateModelMixin): """ - Used to substitute a single node for the entire deployment. - - :ivar node_type: Exposed node type - :vartype node_type: :class:`Type` - :ivar mappings: Requirement and capability mappings - :vartype mappings: {basestring: :class:`SubstitutionTemplateMapping`} - :ivar service_template: Containing service template - :vartype service_template: :class:`ServiceTemplate` - :ivar substitutions: Instantiated substitutions - :vartype substitutions: [:class:`Substitution`] + Template for creating a :class:`Substitution` instance, which exposes an entire instantiated + service as a single node. """ __tablename__ = 'substitution_template' - __private_fields__ = ['node_type_fk'] - - # region foreign keys - - @declared_attr - def node_type_fk(cls): - """For SubstitutionTemplate many-to-one to Type""" - return relationship.foreign_key('type') - - # endregion + __private_fields__ = ('node_type_fk',) # region association proxies @@ -916,10 +1025,20 @@ class SubstitutionTemplateBase(TemplateModelMixin): @declared_attr def substitutions(cls): + """ + Instantiated substitutions. + + :type: [:class:`Substitution`] + """ return relationship.one_to_many(cls, 'substitution') @declared_attr def mappings(cls): + """ + Map requirement and capabilities to exposed node. + + :type: {:obj:`basestring`: :class:`SubstitutionTemplateMapping`} + """ return relationship.one_to_many(cls, 'substitution_template_mapping', dict_key='name') # endregion @@ -928,10 +1047,24 @@ class SubstitutionTemplateBase(TemplateModelMixin): @declared_attr def node_type(cls): + """ + Exposed node type. + + :type: :class:`Type` + """ return relationship.many_to_one(cls, 'type', back_populates=relationship.NO_BACK_POP) # endregion + # region foreign keys + + @declared_attr + def node_type_fk(cls): + """For SubstitutionTemplate many-to-one to Type""" + return relationship.foreign_key('type') + + # endregion + @property def as_raw(self): return collections.OrderedDict(( @@ -961,52 +1094,20 @@ class SubstitutionTemplateBase(TemplateModelMixin): class SubstitutionTemplateMappingBase(TemplateModelMixin): """ - Used by :class:`SubstitutionTemplate` to map a capability or a requirement to a node. - - Only one of `capability_template` and `requirement_template` can be set. - - :ivar name: Exposed capability or requirement name - :vartype name: basestring - :ivar node_template: Node template - :vartype node_template: :class:`NodeTemplate` - :ivar capability_template: Capability template in the node template - :vartype capability_template: :class:`CapabilityTemplate` - :ivar requirement_template: Requirement template in the node template - :vartype requirement_template: :class:`RequirementTemplate` - :ivar substitution_template: Containing substitution template - :vartype substitution_template: :class:`SubstitutionTemplate` + Used by :class:`SubstitutionTemplate` to map a capability template or a requirement template to + the exposed node. + + The :attr:`name` field should match the capability or requirement name on the exposed node's + type. + + Only one of :attr:`capability_template` and :attr:`requirement_template` can be set. """ __tablename__ = 'substitution_template_mapping' - __private_fields__ = ['substitution_template_fk', - 'node_template_fk', + __private_fields__ = ('substitution_template_fk', 'capability_template_fk', - 'requirement_template_fk'] - - # region foreign keys - - @declared_attr - def substitution_template_fk(cls): - """For SubstitutionTemplate one-to-many to SubstitutionTemplateMapping""" - return relationship.foreign_key('substitution_template') - - @declared_attr - def node_template_fk(cls): - """For SubstitutionTemplate one-to-one to NodeTemplate""" - return relationship.foreign_key('node_template') - - @declared_attr - def capability_template_fk(cls): - """For SubstitutionTemplate one-to-one to CapabilityTemplate""" - return relationship.foreign_key('capability_template', nullable=True) - - @declared_attr - def requirement_template_fk(cls): - """For SubstitutionTemplate one-to-one to RequirementTemplate""" - return relationship.foreign_key('requirement_template', nullable=True) - - # endregion + 'requirement_template_fk') # region association proxies @@ -1015,17 +1116,22 @@ class SubstitutionTemplateMappingBase(TemplateModelMixin): # region one_to_one relationships @declared_attr - def node_template(cls): - return relationship.one_to_one( - cls, 'node_template', back_populates=relationship.NO_BACK_POP) - - @declared_attr def capability_template(cls): + """ + Capability template to expose (can be ``None``). + + :type: :class:`CapabilityTemplate` + """ return relationship.one_to_one( cls, 'capability_template', back_populates=relationship.NO_BACK_POP) @declared_attr def requirement_template(cls): + """ + Requirement template to expose (can be ``None``). + + :type: :class:`RequirementTemplate` + """ return relationship.one_to_one( cls, 'requirement_template', back_populates=relationship.NO_BACK_POP) @@ -1039,10 +1145,34 @@ class SubstitutionTemplateMappingBase(TemplateModelMixin): @declared_attr def substitution_template(cls): + """ + Containing substitution template. + + :type: :class:`SubstitutionTemplate` + """ return relationship.many_to_one(cls, 'substitution_template', back_populates='mappings') # endregion + # region foreign keys + + @declared_attr + def substitution_template_fk(cls): + """For SubstitutionTemplate one-to-many to SubstitutionTemplateMapping""" + return relationship.foreign_key('substitution_template') + + @declared_attr + def capability_template_fk(cls): + """For SubstitutionTemplate one-to-one to CapabilityTemplate""" + return relationship.foreign_key('capability_template', nullable=True) + + @declared_attr + def requirement_template_fk(cls): + """For SubstitutionTemplate one-to-one to RequirementTemplate""" + return relationship.foreign_key('requirement_template', nullable=True) + + # endregion + @property def as_raw(self): return collections.OrderedDict(( @@ -1054,7 +1184,11 @@ class SubstitutionTemplateMappingBase(TemplateModelMixin): def instantiate(self, container): from . import models context = ConsumptionContext.get_thread_local() - nodes = self.node_template.nodes + if self.capability_template is not None: + node_template = self.capability_template.node_template + else: + node_template = self.requirement_template.node_template + nodes = node_template.nodes if len(nodes) == 0: context.validation.report( 'mapping "{0}" refers to node template "{1}" but there are no ' @@ -1070,9 +1204,10 @@ class SubstitutionTemplateMappingBase(TemplateModelMixin): if a_capability.capability_template.name == self.capability_template.name: capability = a_capability return models.SubstitutionMapping(name=self.name, - node=node, capability=capability, - requirement_template=self.requirement_template) + requirement_template=self.requirement_template, + node=node) + def validate(self): context = ConsumptionContext.get_thread_local() @@ -1085,9 +1220,13 @@ class SubstitutionTemplateMappingBase(TemplateModelMixin): def dump(self): context = ConsumptionContext.get_thread_local() + if self.capability_template is not None: + node_template = self.capability_template.node_template + else: + node_template = self.requirement_template.node_template console.puts('{0} -> {1}.{2}'.format( context.style.node(self.name), - context.style.node(self.node_template.name), + context.style.node(node_template.name), context.style.node(self.capability_template.name if self.capability_template else self.requirement_template.name))) @@ -1095,70 +1234,26 @@ class SubstitutionTemplateMappingBase(TemplateModelMixin): class RequirementTemplateBase(TemplateModelMixin): """ - A requirement for a :class:`NodeTemplate`. During instantiation will be matched with a - capability of another node. - - Requirements may optionally contain a :class:`RelationshipTemplate` that will be created between - the nodes. - - :ivar name: Name (a node template can have multiple requirements with the same name) - :vartype name: basestring - :ivar target_node_type: Required node type (optional) - :vartype target_node_type: :class:`Type` - :ivar target_node_template: Required node template (optional) - :vartype target_node_template: :class:`NodeTemplate` - :ivar target_capability_type: Required capability type (optional) - :vartype target_capability_type: :class:`Type` - :ivar target_capability_name: Name of capability in target node (optional) - :vartype target_capability_name: basestring - :ivar target_node_template_constraints: Constraints for filtering relationship targets - :vartype target_node_template_constraints: [:class:`NodeTemplateConstraint`] - :ivar relationship_template: Template for relationships (optional) - :vartype relationship_template: :class:`RelationshipTemplate` - :ivar node_template: Containing node template - :vartype node_template: :class:`NodeTemplate` - :ivar substitution_template_mapping: Our contribution to service substitution - :vartype substitution_template_mapping: :class:`SubstitutionTemplateMapping` - :ivar substitution_mapping: Our contribution to service substitution - :vartype substitution_mapping: :class:`SubstitutionMapping` - """ + Template for creating :class:`Relationship` instances, which are optionally-typed edges in the + service topology, connecting a :class:`Node` to a :class:`Capability` of another node. - __tablename__ = 'requirement_template' + Note that there is no equivalent "Requirement" instance model. Instead, during instantiation a + requirement template is matched with a capability and a :class:`Relationship` is instantiated. - __private_fields__ = ['target_node_type_fk', - 'target_node_template_fk', - 'target_capability_type_fk' - 'node_template_fk', - 'relationship_template_fk'] + A requirement template *must* target a :class:`CapabilityType` or a capability name. It can + optionally target a specific :class:`NodeType` or :class:`NodeTemplate`. - # region foreign keys - - @declared_attr - def target_node_type_fk(cls): - """For RequirementTemplate many-to-one to Type""" - return relationship.foreign_key('type', nullable=True) - - @declared_attr - def target_node_template_fk(cls): - """For RequirementTemplate one-to-one to NodeTemplate""" - return relationship.foreign_key('node_template', nullable=True) - - @declared_attr - def target_capability_type_fk(cls): - """For RequirementTemplate one-to-one to NodeTemplate""" - return relationship.foreign_key('type', nullable=True) - - @declared_attr - def node_template_fk(cls): - """For NodeTemplate one-to-many to RequirementTemplate""" - return relationship.foreign_key('node_template') + Requirement templates may optionally contain a :class:`RelationshipTemplate`. If they do not, + a :class:`Relationship` will be instantiated with default values. + """ - @declared_attr - def relationship_template_fk(cls): - """For RequirementTemplate one-to-one to RelationshipTemplate""" - return relationship.foreign_key('relationship_template', nullable=True) + __tablename__ = 'requirement_template' - # endregion + __private_fields__ = ('target_capability_type_fk', + 'target_node_template_fk', + 'target_node_type_fk', + 'relationship_template_fk', + 'node_template_fk') # region association proxies @@ -1167,21 +1262,36 @@ class RequirementTemplateBase(TemplateModelMixin): # region one_to_one relationships @declared_attr - def target_node_template(cls): + def target_capability_type(cls): + """ + Target capability type. + + :type: :class:`CapabilityType` + """ return relationship.one_to_one(cls, - 'node_template', - fk='target_node_template_fk', + 'type', + fk='target_capability_type_fk', back_populates=relationship.NO_BACK_POP) @declared_attr - def target_capability_type(cls): + def target_node_template(cls): + """ + Target node template (can be ``None``). + + :type: :class:`NodeTemplate` + """ return relationship.one_to_one(cls, - 'type', - fk='target_capability_type_fk', + 'node_template', + fk='target_node_template_fk', back_populates=relationship.NO_BACK_POP) @declared_attr def relationship_template(cls): + """ + Associated relationship template (can be ``None``). + + :type: :class:`RelationshipTemplate` + """ return relationship.one_to_one(cls, 'relationship_template') # endregion @@ -1190,6 +1300,11 @@ class RequirementTemplateBase(TemplateModelMixin): @declared_attr def relationships(cls): + """ + Instantiated relationships. + + :type: [:class:`Relationship`] + """ return relationship.one_to_many(cls, 'relationship') # endregion @@ -1198,17 +1313,65 @@ class RequirementTemplateBase(TemplateModelMixin): @declared_attr def node_template(cls): + """ + Containing node template. + + :type: :class:`NodeTemplate` + """ return relationship.many_to_one(cls, 'node_template', fk='node_template_fk') @declared_attr def target_node_type(cls): + """ + Target node type (can be ``None``). + + :type: :class:`Type` + """ return relationship.many_to_one( cls, 'type', fk='target_node_type_fk', back_populates=relationship.NO_BACK_POP) # endregion - target_capability_name = Column(Text) - target_node_template_constraints = Column(PickleType) + # region foreign keys + + @declared_attr + def target_node_type_fk(cls): + """For RequirementTemplate many-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + @declared_attr + def target_node_template_fk(cls): + """For RequirementTemplate one-to-one to NodeTemplate""" + return relationship.foreign_key('node_template', nullable=True) + + @declared_attr + def target_capability_type_fk(cls): + """For RequirementTemplate one-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + @declared_attr + def node_template_fk(cls): + """For NodeTemplate one-to-many to RequirementTemplate""" + return relationship.foreign_key('node_template') + + @declared_attr + def relationship_template_fk(cls): + """For RequirementTemplate one-to-one to RelationshipTemplate""" + return relationship.foreign_key('relationship_template', nullable=True) + + # endregion + + target_capability_name = Column(Text, doc=""" + Target capability name in node template or node type (can be ``None``). + + :type: :obj:`basestring` + """) + + target_node_template_constraints = Column(PickleType, doc=""" + Constraints for filtering relationship targets. + + :type: [:class:`NodeTemplateConstraint`] + """) def find_target(self, source_node_template): context = ConsumptionContext.get_thread_local() @@ -1313,41 +1476,16 @@ class RequirementTemplateBase(TemplateModelMixin): class RelationshipTemplateBase(TemplateModelMixin): """ - Optional addition to a :class:`RequirementTemplate` in :class:`NodeTemplate` that can be applied - when the requirement is matched with a capability. - - Note that a relationship template here is not equivalent to a relationship template entity in - TOSCA. For example, a TOSCA requirement specifying a relationship type instead of a template - would still be represented here as a relationship template. - - :ivar name: Name (optional; if present is unique for this service template) - :vartype name: basestring - :ivar type: Relationship type - :vartype type: :class:`Type` - :ivar description: Human-readable description - :vartype description: basestring - :ivar properties: Associated parameters - :vartype properties: {basestring: :class:`Property`} - :ivar interface_templates: Bundles of operations - :vartype interface_templates: {basestring: :class:`InterfaceTemplate`} - :ivar requirement_template: Containing requirement template - :vartype requirement_template: :class:`RequirementTemplate` - :ivar relationships: Instantiated relationships - :vartype relationships: [:class:`Relationship`] + Optional addition to a :class:`RequirementTemplate`. + + Note that a relationship template here is not exactly equivalent to a relationship template + entity in TOSCA. For example, a TOSCA requirement specifying a relationship type rather than a + relationship template would still be represented here as a relationship template. """ __tablename__ = 'relationship_template' - __private_fields__ = ['type_fk'] - - # region foreign keys - - @declared_attr - def type_fk(cls): - """For RelationshipTemplate many-to-one to Type""" - return relationship.foreign_key('type', nullable=True) - - # endregion + __private_fields__ = ('type_fk',) # region association proxies @@ -1361,14 +1499,29 @@ class RelationshipTemplateBase(TemplateModelMixin): @declared_attr def relationships(cls): + """ + Instantiated relationships. + + :type: [:class:`Relationship`] + """ return relationship.one_to_many(cls, 'relationship') @declared_attr def interface_templates(cls): + """ + Associated interface templates. + + :type: {:obj:`basestring`: :class:`InterfaceTemplate`} + """ return relationship.one_to_many(cls, 'interface_template', dict_key='name') @declared_attr def properties(cls): + """ + Declarations for associated immutable parameters. + + :type: {:obj:`basestring`: :class:`Property`} + """ return relationship.one_to_many(cls, 'property', dict_key='name') # endregion @@ -1377,11 +1530,29 @@ class RelationshipTemplateBase(TemplateModelMixin): @declared_attr def type(cls): + """ + Relationship type. + + :type: :class:`Type` + """ return relationship.many_to_one(cls, 'type', back_populates=relationship.NO_BACK_POP) # endregion - description = Column(Text) + # region foreign keys + + @declared_attr + def type_fk(cls): + """For RelationshipTemplate many-to-one to Type""" + return relationship.foreign_key('type', nullable=True) + + # endregion + + description = Column(Text, doc=""" + Human-readable description. + + :type: :obj:`basestring` + """) @property def as_raw(self): @@ -1426,50 +1597,15 @@ class RelationshipTemplateBase(TemplateModelMixin): class CapabilityTemplateBase(TemplateModelMixin): """ - A capability of a :class:`NodeTemplate`. Nodes expose zero or more capabilities that can be - matched with :class:`Requirement` instances of other nodes. - - :ivar name: Name (unique for the node template) - :vartype name: basestring - :ivar type: Capability type - :vartype type: :class:`Type` - :ivar description: Human-readable description - :vartype description: basestring - :ivar valid_source_node_types: Reject requirements that are not from these node types (optional) - :vartype valid_source_node_types: [:class:`Type`] - :ivar min_occurrences: Minimum number of requirement matches required - :vartype min_occurrences: int - :ivar max_occurrences: Maximum number of requirement matches allowed - :vartype min_occurrences: int - :ivar properties: Associated parameters - :vartype properties: {basestring: :class:`Property`} - :ivar node_template: Containing node template - :vartype node_template: :class:`NodeTemplate` - :ivar substitution_template_mapping: Our contribution to service substitution - :vartype substitution_template_mapping: :class:`SubstitutionTemplateMapping` - :ivar capabilities: Instantiated capabilities - :vartype capabilities: [:class:`Capability`] + Template for creating :class:`Capability` instances, typed attachments which serve two purposes: + to provide extra properties and attributes to :class:`Node` instances, and to expose targets for + :class:`Relationship` instances from other nodes. """ __tablename__ = 'capability_template' - __private_fields__ = ['type_fk', - 'node_template_fk'] - - # region foreign keys - - @declared_attr - def type_fk(cls): - """For CapabilityTemplate many-to-one to Type""" - return relationship.foreign_key('type') - - @declared_attr - def node_template_fk(cls): - """For NodeTemplate one-to-many to CapabilityTemplate""" - return relationship.foreign_key('node_template') - - # endregion - + __private_fields__ = ('type_fk', + 'node_template_fk') # region association proxies @@ -1483,10 +1619,20 @@ class CapabilityTemplateBase(TemplateModelMixin): @declared_attr def capabilities(cls): + """ + Instantiated capabilities. + + :type: [:class:`Capability`] + """ return relationship.one_to_many(cls, 'capability') @declared_attr def properties(cls): + """ + Declarations for associated immutable parameters. + + :type: {:obj:`basestring`: :class:`Property`} + """ return relationship.one_to_many(cls, 'property', dict_key='name') # endregion @@ -1495,10 +1641,20 @@ class CapabilityTemplateBase(TemplateModelMixin): @declared_attr def node_template(cls): + """ + Containing node template. + + :type: :class:`NodeTemplate` + """ return relationship.many_to_one(cls, 'node_template') @declared_attr def type(cls): + """ + Capability type. + + :type: :class:`Type` + """ return relationship.many_to_one(cls, 'type', back_populates=relationship.NO_BACK_POP) # endregion @@ -1507,13 +1663,46 @@ class CapabilityTemplateBase(TemplateModelMixin): @declared_attr def valid_source_node_types(cls): + """ + Reject requirements that are not from these node types. + + :type: [:class:`Type`] + """ return relationship.many_to_many(cls, 'type', prefix='valid_sources') # endregion - description = Column(Text) - min_occurrences = Column(Integer, default=None) # optional - max_occurrences = Column(Integer, default=None) # optional + # region foreign keys + + @declared_attr + def type_fk(cls): + """For CapabilityTemplate many-to-one to Type""" + return relationship.foreign_key('type') + + @declared_attr + def node_template_fk(cls): + """For NodeTemplate one-to-many to CapabilityTemplate""" + return relationship.foreign_key('node_template') + + # endregion + + description = Column(Text, doc=""" + Human-readable description. + + :type: :obj:`basestring` + """) + + min_occurrences = Column(Integer, default=None, doc=""" + Minimum number of requirement matches required. + + :type: :obj:`int` + """) + + max_occurrences = Column(Integer, default=None, doc=""" + Maximum number of requirement matches allowed. + + :type: :obj:`int` + """) def satisfies_requirement(self, source_node_template, @@ -1588,58 +1777,19 @@ class CapabilityTemplateBase(TemplateModelMixin): class InterfaceTemplateBase(TemplateModelMixin): """ - A typed set of :class:`OperationTemplate`. - - :ivar name: Name (unique for the node, group, or relationship template) - :vartype name: basestring - :ivar type: Interface type - :vartype type: :class:`Type` - :ivar description: Human-readable description - :vartype description: basestring - :ivar inputs: Inputs that can be used by all operations in the interface - :vartype inputs: {basestring: :class:`Input`} - :ivar operation_templates: Operations - :vartype operation_templates: {basestring: :class:`OperationTemplate`} - :ivar node_template: Containing node template - :vartype node_template: :class:`NodeTemplate` - :ivar group_template: Containing group template - :vartype group_template: :class:`GroupTemplate` - :ivar relationship_template: Containing relationship template - :vartype relationship_template: :class:`RelationshipTemplate` - :ivar interfaces: Instantiated interfaces - :vartype interfaces: [:class:`Interface`] + Template for creating :class:`Interface` instances, which are typed bundles of + :class:`Operation` instances. + + Can be associated with a :class:`NodeTemplate`, a :class:`GroupTemplate`, or a + :class:`RelationshipTemplate`. """ __tablename__ = 'interface_template' - __private_fields__ = ['type_fk', + __private_fields__ = ('type_fk', 'node_template_fk', 'group_template_fk', - 'relationship_template_fk'] - - # region foreign keys - - @declared_attr - def type_fk(cls): - """For InterfaceTemplate many-to-one to Type""" - return relationship.foreign_key('type') - - @declared_attr - def node_template_fk(cls): - """For NodeTemplate one-to-many to InterfaceTemplate""" - return relationship.foreign_key('node_template', nullable=True) - - @declared_attr - def group_template_fk(cls): - """For GroupTemplate one-to-many to InterfaceTemplate""" - return relationship.foreign_key('group_template', nullable=True) - - @declared_attr - def relationship_template_fk(cls): - """For RelationshipTemplate one-to-many to InterfaceTemplate""" - return relationship.foreign_key('relationship_template', nullable=True) - - # endregion + 'relationship_template_fk') # region association proxies @@ -1653,14 +1803,30 @@ class InterfaceTemplateBase(TemplateModelMixin): @declared_attr def inputs(cls): + """ + Declarations for externally provided parameters that can be used by all operations of the + interface. + + :type: {:obj:`basestring`: :class:`Input`} + """ return relationship.one_to_many(cls, 'input', dict_key='name') @declared_attr def interfaces(cls): + """ + Instantiated interfaces. + + :type: [:class:`Interface`] + """ return relationship.one_to_many(cls, 'interface') @declared_attr def operation_templates(cls): + """ + Associated operation templates. + + :type: {:obj:`basestring`: :class:`OperationTemplate`} + """ return relationship.one_to_many(cls, 'operation_template', dict_key='name') # endregion @@ -1668,24 +1834,72 @@ class InterfaceTemplateBase(TemplateModelMixin): # region many_to_one relationships @declared_attr - def relationship_template(cls): - return relationship.many_to_one(cls, 'relationship_template') + def node_template(cls): + """ + Containing node template (can be ``None``). + + :type: :class:`NodeTemplate` + """ + return relationship.many_to_one(cls, 'node_template') @declared_attr def group_template(cls): + """ + Containing group template (can be ``None``). + + :type: :class:`GroupTemplate` + """ return relationship.many_to_one(cls, 'group_template') @declared_attr - def node_template(cls): - return relationship.many_to_one(cls, 'node_template') + def relationship_template(cls): + """ + Containing relationship template (can be ``None``). + + :type: :class:`RelationshipTemplate` + """ + return relationship.many_to_one(cls, 'relationship_template') @declared_attr def type(cls): + """ + Interface type. + + :type: :class:`Type` + """ return relationship.many_to_one(cls, 'type', back_populates=relationship.NO_BACK_POP) # endregion - description = Column(Text) + # region foreign keys + + @declared_attr + def type_fk(cls): + """For InterfaceTemplate many-to-one to Type""" + return relationship.foreign_key('type') + + @declared_attr + def node_template_fk(cls): + """For NodeTemplate one-to-many to InterfaceTemplate""" + return relationship.foreign_key('node_template', nullable=True) + + @declared_attr + def group_template_fk(cls): + """For GroupTemplate one-to-many to InterfaceTemplate""" + return relationship.foreign_key('group_template', nullable=True) + + @declared_attr + def relationship_template_fk(cls): + """For RelationshipTemplate one-to-many to InterfaceTemplate""" + return relationship.foreign_key('relationship_template', nullable=True) + + # endregion + + description = Column(Text, doc=""" + Human-readable description. + + :type: :obj:`basestring` + """) @property def as_raw(self): @@ -1728,68 +1942,15 @@ class InterfaceTemplateBase(TemplateModelMixin): class OperationTemplateBase(TemplateModelMixin): """ - An operation in a :class:`InterfaceTemplate`. - - Operations are executed by an associated :class:`PluginSpecification` via an executor. - - :ivar name: Name (unique for the interface or service template) - :vartype name: basestring - :ivar description: Human-readable description - :vartype description: basestring - :ivar relationship_edge: When true specified that the operation is on the relationship's - target edge instead of its source (only used by relationship - operations) - :vartype relationship_edge: bool - :ivar implementation: Implementation (interpreted by the plugin) - :vartype implementation: basestring - :ivar dependencies: Dependency strings (interpreted by the plugin) - :vartype dependencies: [basestring] - :ivar inputs: Inputs that can be used by this operation - :vartype inputs: {basestring: :class:`Input`} - :ivar plugin_specification: Associated plugin - :vartype plugin_specification: :class:`PluginSpecification` - :ivar configurations: Configuration (interpreted by the plugin) - :vartype configurations: {basestring, :class:`Configuration`} - :ivar function: Name of the operation function - :vartype function: basestring - :ivar executor: Name of executor to run the operation with - :vartype executor: basestring - :ivar max_attempts: Maximum number of attempts allowed in case of failure - :vartype max_attempts: int - :ivar retry_interval: Interval between retries (in seconds) - :vartype retry_interval: int - :ivar interface_template: Containing interface template - :vartype interface_template: :class:`InterfaceTemplate` - :ivar service_template: Containing service template - :vartype service_template: :class:`ServiceTemplate` - :ivar operations: Instantiated operations - :vartype operations: [:class:`Operation`] + Template for creating :class:`Operation` instances, which are entry points to Python functions + called as part of a workflow execution. """ __tablename__ = 'operation_template' - __private_fields__ = ['service_template_fk', + __private_fields__ = ('service_template_fk', 'interface_template_fk', - 'plugin_fk'] - - # region foreign keys - - @declared_attr - def service_template_fk(cls): - """For ServiceTemplate one-to-many to OperationTemplate""" - return relationship.foreign_key('service_template', nullable=True) - - @declared_attr - def interface_template_fk(cls): - """For InterfaceTemplate one-to-many to OperationTemplate""" - return relationship.foreign_key('interface_template', nullable=True) - - @declared_attr - def plugin_specification_fk(cls): - """For OperationTemplate one-to-one to PluginSpecification""" - return relationship.foreign_key('plugin_specification', nullable=True) - - # endregion + 'plugin_fk') # region association proxies @@ -1799,6 +1960,11 @@ class OperationTemplateBase(TemplateModelMixin): @declared_attr def plugin_specification(cls): + """ + Associated plugin specification. + + :type: :class:`PluginSpecification` + """ return relationship.one_to_one( cls, 'plugin_specification', back_populates=relationship.NO_BACK_POP) @@ -1807,15 +1973,30 @@ class OperationTemplateBase(TemplateModelMixin): # region one_to_many relationships @declared_attr - def inputs(cls): - return relationship.one_to_many(cls, 'input', dict_key='name') - - @declared_attr def operations(cls): + """ + Instantiated operations. + + :type: [:class:`Operation`] + """ return relationship.one_to_many(cls, 'operation') @declared_attr + def inputs(cls): + """ + Declarations for parameters provided to the :attr:`implementation`. + + :type: {:obj:`basestring`: :class:`Input`} + """ + return relationship.one_to_many(cls, 'input', dict_key='name') + + @declared_attr def configurations(cls): + """ + Configuration parameters for the operation instance Python :attr:`function`. + + :type: {:obj:`basestring`: :class:`Configuration`} + """ return relationship.one_to_many(cls, 'configuration', dict_key='name') # endregion @@ -1824,11 +2005,21 @@ class OperationTemplateBase(TemplateModelMixin): @declared_attr def service_template(cls): + """ + Containing service template (can be ``None``). For workflow operation templates. + + :type: :class:`ServiceTemplate` + """ return relationship.many_to_one(cls, 'service_template', back_populates='workflow_templates') @declared_attr def interface_template(cls): + """ + Containing interface template (can be ``None``). + + :type: :class:`InterfaceTemplate` + """ return relationship.many_to_one(cls, 'interface_template') # endregion @@ -1837,14 +2028,73 @@ class OperationTemplateBase(TemplateModelMixin): # endregion - description = Column(Text) - relationship_edge = Column(Boolean) - implementation = Column(Text) - dependencies = Column(modeling_types.StrictList(item_cls=basestring)) - function = Column(Text) - executor = Column(Text) - max_attempts = Column(Integer) - retry_interval = Column(Integer) + # region foreign keys + + @declared_attr + def service_template_fk(cls): + """For ServiceTemplate one-to-many to OperationTemplate""" + return relationship.foreign_key('service_template', nullable=True) + + @declared_attr + def interface_template_fk(cls): + """For InterfaceTemplate one-to-many to OperationTemplate""" + return relationship.foreign_key('interface_template', nullable=True) + + @declared_attr + def plugin_specification_fk(cls): + """For OperationTemplate one-to-one to PluginSpecification""" + return relationship.foreign_key('plugin_specification', nullable=True) + + # endregion + + description = Column(Text, doc=""" + Human-readable description. + + :type: :obj:`basestring` + """) + + relationship_edge = Column(Boolean, doc=""" + When ``True`` specifies that the operation is on the relationship's target edge; ``False`` is + the source edge (only used by operations on relationships) + + :type: :obj:`bool` + """) + + implementation = Column(Text, doc=""" + Implementation (usually the name of an artifact). + + :type: :obj:`basestring` + """) + + dependencies = Column(modeling_types.StrictList(item_cls=basestring), doc=""" + Dependencies (usually names of artifacts). + + :type: [:obj:`basestring`] + """) + + function = Column(Text, doc=""" + Full path to Python function. + + :type: :obj:`basestring` + """) + + executor = Column(Text, doc=""" + Name of executor. + + :type: :obj:`basestring` + """) + + max_attempts = Column(Integer, doc=""" + Maximum number of attempts allowed in case of task failure. + + :type: :obj:`int` + """) + + retry_interval = Column(Integer, doc=""" + Interval between task retry attemps (in seconds). + + :type: :obj:`float` + """) @property def as_raw(self): @@ -1917,48 +2167,14 @@ class OperationTemplateBase(TemplateModelMixin): class ArtifactTemplateBase(TemplateModelMixin): """ - A file associated with a :class:`NodeTemplate`. - - :ivar name: Name (unique for the node template) - :vartype name: basestring - :ivar type: Artifact type - :vartype type: :class:`Type` - :ivar description: Human-readable description - :vartype description: basestring - :ivar source_path: Source path (CSAR or repository) - :vartype source_path: basestring - :ivar target_path: Path at destination machine - :vartype target_path: basestring - :ivar repository_url: Repository URL - :vartype repository_path: basestring - :ivar repository_credential: Credentials for accessing the repository - :vartype repository_credential: {basestring: basestring} - :ivar properties: Associated parameters - :vartype properties: {basestring: :class:`Property`} - :ivar node_template: Containing node template - :vartype node_template: :class:`NodeTemplate` - :ivar artifacts: Instantiated artifacts - :vartype artifacts: [:class:`Artifact`] + Template for creating an :class:`Artifact` instance, which is a typed file, either provided in a + CSAR or downloaded from a repository. """ __tablename__ = 'artifact_template' - __private_fields__ = ['type_fk', - 'node_template_fk'] - - # region foreign keys - - @declared_attr - def type_fk(cls): - """For ArtifactTemplate many-to-one to Type""" - return relationship.foreign_key('type') - - @declared_attr - def node_template_fk(cls): - """For NodeTemplate one-to-many to ArtifactTemplate""" - return relationship.foreign_key('node_template') - - # endregion + __private_fields__ = ('type_fk', + 'node_template_fk') # region association proxies @@ -1972,10 +2188,20 @@ class ArtifactTemplateBase(TemplateModelMixin): @declared_attr def artifacts(cls): + """ + Instantiated artifacts. + + :type: [:class:`Artifact`] + """ return relationship.one_to_many(cls, 'artifact') @declared_attr def properties(cls): + """ + Declarations for associated immutable parameters. + + :type: {:obj:`basestring`: :class:`Property`} + """ return relationship.one_to_many(cls, 'property', dict_key='name') # endregion @@ -1984,19 +2210,67 @@ class ArtifactTemplateBase(TemplateModelMixin): @declared_attr def node_template(cls): + """ + Containing node template. + + :type: :class:`NodeTemplate` + """ return relationship.many_to_one(cls, 'node_template') @declared_attr def type(cls): + """ + Artifact type. + + :type: :class:`Type` + """ return relationship.many_to_one(cls, 'type', back_populates=relationship.NO_BACK_POP) # endregion - description = Column(Text) - source_path = Column(Text) - target_path = Column(Text) - repository_url = Column(Text) - repository_credential = Column(modeling_types.StrictDict(basestring, basestring)) + # region foreign keys + + @declared_attr + def type_fk(cls): + """For ArtifactTemplate many-to-one to Type""" + return relationship.foreign_key('type') + + @declared_attr + def node_template_fk(cls): + """For NodeTemplate one-to-many to ArtifactTemplate""" + return relationship.foreign_key('node_template') + + # endregion + + description = Column(Text, doc=""" + Human-readable description. + + :type: :obj:`basestring` + """) + + source_path = Column(Text, doc=""" + Source path (in CSAR or repository). + + :type: :obj:`basestring` + """) + + target_path = Column(Text, doc=""" + Path at which to install at destination. + + :type: :obj:`basestring` + """) + + repository_url = Column(Text, doc=""" + Repository URL. + + :type: :obj:`basestring` + """) + + repository_credential = Column(modeling_types.StrictDict(basestring, basestring), doc=""" + Credentials for accessing the repository. + + :type: {:obj:`basestring`, :obj:`basestring`} + """) @property def as_raw(self): @@ -2050,52 +2324,64 @@ class ArtifactTemplateBase(TemplateModelMixin): class PluginSpecificationBase(TemplateModelMixin): """ - Plugin specification. - - :ivar name: Required plugin name - :vartype name: basestring - :ivar version: Minimum plugin version - :vartype version: basestring - :ivar enabled: Whether the plugin is enabled - :vartype enabled: bool - :ivar plugin: The matching plugin (or None if not matched) - :vartype plugin: :class:`Plugin` + Requirement for a :class:`Plugin`. + + The actual plugin to be selected depends on those currently installed in ARIA. """ __tablename__ = 'plugin_specification' - __private_fields__ = ['service_template_fk', - 'plugin_fk'] + __private_fields__ = ('service_template_fk', + 'plugin_fk') - version = Column(Text) - enabled = Column(Boolean, nullable=False, default=True) + version = Column(Text, doc=""" + Minimum plugin version. - # region foreign keys + :type: :obj:`basestring` + """) - @declared_attr - def service_template_fk(cls): - """For ServiceTemplate one-to-many to PluginSpecification""" - return relationship.foreign_key('service_template', nullable=True) - - @declared_attr - def plugin_fk(cls): - """For PluginSpecification many-to-one to Plugin""" - return relationship.foreign_key('plugin', nullable=True) + enabled = Column(Boolean, nullable=False, default=True, doc=""" + Whether the plugin is enabled. - # endregion + :type: :obj:`bool` + """) # region many_to_one relationships @declared_attr def service_template(cls): + """ + Containing service template. + + :type: :class:`ServiceTemplate` + """ return relationship.many_to_one(cls, 'service_template') @declared_attr def plugin(cls): # pylint: disable=method-hidden + """ + Matched plugin. + + :type: :class:`Plugin` + """ return relationship.many_to_one(cls, 'plugin', back_populates=relationship.NO_BACK_POP) # endregion + # region foreign keys + + @declared_attr + def service_template_fk(cls): + """For ServiceTemplate one-to-many to PluginSpecification""" + return relationship.foreign_key('service_template', nullable=True) + + @declared_attr + def plugin_fk(cls): + """For PluginSpecification many-to-one to Plugin""" + return relationship.foreign_key('plugin', nullable=True) + + # endregion + @property def as_raw(self): return collections.OrderedDict(( http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/modeling/types.py ---------------------------------------------------------------------- diff --git a/aria/modeling/types.py b/aria/modeling/types.py index 920a0c2..c34326e 100644 --- a/aria/modeling/types.py +++ b/aria/modeling/types.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Allows JSON-serializable collections to be used as SQLAlchemy column types. +""" + import json from collections import namedtuple @@ -52,12 +56,18 @@ class _MutableType(TypeDecorator): class Dict(_MutableType): + """ + JSON-serializable dict type for SQLAlchemy columns. + """ @property def python_type(self): return dict class List(_MutableType): + """ + JSON-serializable list type for SQLAlchemy columns. + """ @property def python_type(self): return list @@ -67,7 +77,9 @@ class _StrictDictMixin(object): @classmethod def coerce(cls, key, value): - "Convert plain dictionaries to MutableDict." + """ + Convert plain dictionaries to MutableDict. + """ try: if not isinstance(value, cls): if isinstance(value, dict): @@ -117,7 +129,9 @@ class _MutableDict(mutable.MutableDict): @classmethod def coerce(cls, key, value): - "Convert plain dictionaries to MutableDict." + """ + Convert plain dictionaries to MutableDict. + """ try: return mutable.MutableDict.coerce(key, value) except ValueError as e: @@ -142,7 +156,9 @@ class _StrictListMixin(object): raise exceptions.ValueFormatException('could not coerce to MutableDict', cause=e) def __setitem__(self, index, value): - """Detect list set events and emit change events.""" + """ + Detect list set events and emit change events. + """ self._assert_item(value) super(_StrictListMixin, self).__setitem__(index, value) @@ -169,7 +185,9 @@ class _MutableList(mutable.MutableList): @classmethod def coerce(cls, key, value): - "Convert plain dictionaries to MutableDict." + """ + Convert plain dictionaries to MutableDict. + """ try: return mutable.MutableList.coerce(key, value) except ValueError as e: @@ -181,9 +199,9 @@ _StrictValue = namedtuple('_StrictValue', 'type_cls, listener_cls') class _StrictDict(object): """ - This entire class functions as a factory for strict dicts and their listeners. - No type class, and no listener type class is created more than once. If a relevant type class - exists it is returned. + This entire class functions as a factory for strict dicts and their listeners. No type class, + and no listener type class is created more than once. If a relevant type class exists it is + returned. """ _strict_map = {} @@ -216,13 +234,19 @@ class _StrictDict(object): StrictDict = _StrictDict() +""" +JSON-serializable strict dict type for SQLAlchemy columns. + +:param key_cls: +:param value_cls: +""" class _StrictList(object): """ - This entire class functions as a factory for strict lists and their listeners. - No type class, and no listener type class is created more than once. If a relevant type class - exists it is returned. + This entire class functions as a factory for strict lists and their listeners. No type class, + and no listener type class is created more than once. If a relevant type class exists it is + returned. """ _strict_map = {} @@ -254,6 +278,11 @@ class _StrictList(object): StrictList = _StrictList() +""" +JSON-serializable strict list type for SQLAlchemy columns. + +:param item_cls: +""" def _mutable_association_listener(mapper, cls): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/modeling/utils.py ---------------------------------------------------------------------- diff --git a/aria/modeling/utils.py b/aria/modeling/utils.py index 43be410..5193cd9 100644 --- a/aria/modeling/utils.py +++ b/aria/modeling/utils.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Miscellaneous modeling utilities. +""" + import os from json import JSONEncoder from StringIO import StringIO @@ -26,6 +30,13 @@ from ..utils.formatting import string_list_as_string class ModelJSONEncoder(JSONEncoder): + """ + JSON encoder that automatically unwraps ``value`` attributes. + """ + def __init__(self, *args, **kwargs): + # Just here to make sure Sphinx doesn't grab the base constructor's docstring + super(ModelJSONEncoder, self).__init__(*args, **kwargs) + def default(self, o): # pylint: disable=method-hidden from .mixins import ModelMixin if isinstance(o, ModelMixin): @@ -40,8 +51,8 @@ class ModelJSONEncoder(JSONEncoder): class NodeTemplateContainerHolder(object): """ - Wrapper that allows using a :class:`aria.modeling.models.NodeTemplate` model directly as the - ``container_holder`` input for :func:`aria.modeling.functions.evaluate`. + Wrapper that allows using a :class:`~aria.modeling.models.NodeTemplate` model directly as the + ``container_holder`` input for :func:`~aria.modeling.functions.evaluate`. """ def __init__(self, node_template): @@ -60,18 +71,17 @@ def merge_parameter_values(parameter_values, declared_parameters, model_cls): Exceptions will be raised for validation errors. :param parameter_values: provided parameter values or None - :type parameter_values: {basestring, object} + :type parameter_values: {:obj:`basestring`: object} :param declared_parameters: declared parameters - :type declared_parameters: {basestring, :class:`aria.modeling.models.Parameter`} + :type declared_parameters: {:obj:`basestring`: :class:`~aria.modeling.models.Parameter`} :return: the merged parameters - :rtype: {basestring, :class:`aria.modeling.models.Parameter`} - :raises aria.modeling.exceptions.UndeclaredParametersException: if a key in ``parameter_values`` - does not exist in ``declared_parameters`` - :raises aria.modeling.exceptions.MissingRequiredParametersException: if a key in - ``declared_parameters`` does not exist in ``parameter_values`` and also has no default - value - :raises aria.modeling.exceptions.ParametersOfWrongTypeException: if a value in - ``parameter_values`` does not match its type in ``declared_parameters`` + :rtype: {:obj:`basestring`: :class:`~aria.modeling.models.Parameter`} + :raises ~aria.modeling.exceptions.UndeclaredParametersException: if a key in + ``parameter_values`` does not exist in ``declared_parameters`` + :raises ~aria.modeling.exceptions.MissingRequiredParametersException: if a key in + ``declared_parameters`` does not exist in ``parameter_values`` and also has no default value + :raises ~aria.modeling.exceptions.ParametersOfWrongTypeException: if a value in + ``parameter_values`` does not match its type in ``declared_parameters`` """ parameter_values = parameter_values or {} @@ -204,6 +214,22 @@ def dump_interfaces(interfaces, name='Interfaces'): class classproperty(object): # pylint: disable=invalid-name def __init__(self, f): self._func = f + self.__doct__ = f.__doc__ def __get__(self, instance, owner): return self._func(owner) + + +def fix_doc(cls): + """ + Class decorator to use the last base class's docstring and make sure Sphinx doesn't grab the + base constructor's docstring. + """ + original_init = cls.__init__ + def init(*args, **kwargs): + original_init(*args, **kwargs) + + cls.__init__ = init + cls.__doc__ = cls.__bases__[-1].__doc__ + + return cls http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/orchestrator/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/__init__.py b/aria/orchestrator/__init__.py index b855aed..24fee9e 100644 --- a/aria/orchestrator/__init__.py +++ b/aria/orchestrator/__init__.py @@ -12,9 +12,11 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. + """ -ARIA orchestrator +Orchestrator package. """ + from .decorators import ( workflow, operation, http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/orchestrator/context/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/context/__init__.py b/aria/orchestrator/context/__init__.py index ad89b13..a87828d 100644 --- a/aria/orchestrator/context/__init__.py +++ b/aria/orchestrator/context/__init__.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Provides contexts to workflow and operation +Contexts for workflows and operations. """ from . import workflow, operation http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/orchestrator/context/common.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/context/common.py b/aria/orchestrator/context/common.py index f4df317..f400142 100644 --- a/aria/orchestrator/context/common.py +++ b/aria/orchestrator/context/common.py @@ -14,8 +14,9 @@ # limitations under the License. """ -A common context for both workflow and operation +Common code for contexts. """ + import logging from contextlib import contextmanager from functools import partial @@ -33,7 +34,7 @@ from ...utils.uuid import generate_uuid class BaseContext(object): """ - Base context object for workflow and operation + Base class for contexts. """ INSTRUMENTATION_FIELDS = ( @@ -109,52 +110,48 @@ class BaseContext(object): @property def model(self): """ - Access to the model storage - :return: + Storage model API ("MAPI"). """ return self._model @property def resource(self): """ - Access to the resource storage - :return: + Storage resource API ("RAPI"). """ return self._resource @property def service_template(self): """ - The blueprint model + Service template model. """ return self.service.service_template @property def service(self): """ - The deployment model + Service instance model. """ return self.model.service.get(self._service_id) @property def name(self): """ - The operation name - :return: + Operation name. """ return self._name @property def id(self): """ - The operation id - :return: + Operation ID. """ return self._id def download_resource(self, destination, path=None): """ - Download a blueprint resource from the resource storage + Download a service template resource from the storage resource API ("RAPI"). """ try: self.resource.service.download(entry_id=str(self.service.id), @@ -167,9 +164,9 @@ class BaseContext(object): def download_resource_and_render(self, destination, path=None, variables=None): """ - Download a blueprint resource from the resource storage render its content as a jinja - template using the provided variables. ctx is available to the template without providing it - explicitly. + Downloads a service template resource from the resource storage and renders its content as a + Jinja template using the provided variables. ``ctx`` is available to the template without + providing it explicitly. """ resource_content = self.get_resource(path=path) resource_content = self._render_resource(resource_content=resource_content, @@ -179,7 +176,7 @@ class BaseContext(object): def get_resource(self, path=None): """ - Read a deployment resource as string from the resource storage + Reads a service instance resource as string from the resource storage. """ try: return self.resource.service.read(entry_id=str(self.service.id), path=path) @@ -189,9 +186,9 @@ class BaseContext(object): def get_resource_and_render(self, path=None, variables=None): """ - Read a deployment resource as string from the resource storage and render it as a jinja - template using the provided variables. ctx is available to the template without providing it - explicitly. + Reads a service instance resource as string from the resource storage and renders it as a + Jinja template using the provided variables. ``ctx`` is available to the template without + providing it explicitly. """ resource_content = self.get_resource(path=path) return self._render_resource(resource_content=resource_content, variables=variables) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/3f09ecde/aria/orchestrator/context/exceptions.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/context/exceptions.py b/aria/orchestrator/context/exceptions.py index fe762e1..e46e2b1 100644 --- a/aria/orchestrator/context/exceptions.py +++ b/aria/orchestrator/context/exceptions.py @@ -12,9 +12,11 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. + """ -Context based exceptions +Context exceptions. """ + from ..exceptions import OrchestratorError