Repository: incubator-ariatosca Updated Branches: refs/heads/ARIA-286-sphinx-documentation 66213279b -> 7ed92d0fe
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/service_template.py ---------------------------------------------------------------------- diff --git a/aria/modeling/service_template.py b/aria/modeling/service_template.py index 063605d..ba62416 100644 --- a/aria/modeling/service_template.py +++ b/aria/modeling/service_template.py @@ -54,50 +54,46 @@ class ServiceTemplateBase(TemplateModelMixin): 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) + :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 + :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 + :ivar meta_data: custom annotations + :vartype meta_data: {:obj:`basestring`: :class:`Metadata`} + :ivar node_templates: templates for creating nodes + :vartype node_templates: {:obj:`basestring`: :class:`NodeTemplate`} + :ivar group_templates: templates for creating groups + :vartype group_templates: {:obj:`basestring`: :class:`GroupTemplate`} + :ivar policy_templates: templates for creating policies + :vartype policy_templates: {:obj:`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`] + :ivar inputs: externally provided parameters + :vartype inputs: {:obj:`basestring`: :class:`Input`} + :ivar outputs: these parameters are filled in after service installation + :vartype outputs: {:obj:`basestring`: :class:`Output`} + :ivar workflow_templates: custom workflows that can be performed on the service + :vartype workflow_templates: {:obj:`basestring`: :class:`OperationTemplate`} + :ivar plugin_specifications: plugins used by the service + :vartype plugin_specifications: {:obj:`basestring`: :class:`PluginSpecification`} + :ivar node_types: base for the node type hierarchy + :vartype node_types: Type + :ivar group_types: base for the group type hierarchy + :vartype group_types: Type + :ivar policy_types: base for the policy type hierarchy + :vartype policy_types: Type + :ivar relationship_types: base for the relationship type hierarchy + :vartype relationship_types: Type + :ivar capability_types: base for the capability type hierarchy + :vartype capability_types: Type + :ivar interface_types: base for the interface type hierarchy + :vartype interface_types: Type + :ivar artifact_types: base for the artifact type hierarchy + :vartype artifact_types: Type + :ivar created_at: creation timestamp + :vartype created_at: datetime.datetime + :ivar updated_at: update timestamp + :vartype updated_at: datetime.datetime """ __tablename__ = 'service_template' @@ -212,6 +208,11 @@ 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 @@ -403,40 +404,40 @@ 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 + :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 + :ivar type: node type + + :ivar description: human-readable description :vartype description: basestring - :ivar default_instances: Default number nodes that will appear in the service + :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 + :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 + :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 + :ivar properties: associated parameters + :vartype properties: {:obj:`basestring`: :class:`Property`} + :ivar interface_templates: bundles of operations + :vartype interface_templates: {:obj:`basestring`: :class:`InterfaceTemplate`} + :ivar artifact_templates: associated files + :vartype artifact_templates: {:obj:`basestring`: :class:`ArtifactTemplate`} + :ivar capability_templates: exposed capabilities + :vartype capability_templates: {:obj:`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 + :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 + :ivar service_template: containing service template + :vartype service_template: 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 + :ivar policy_templates: policy templates enacted on this node :vartype policy_templates: [:class:`PolicyTemplate`] - :ivar substitution_template_mapping: Our contribution to service substitution + :ivar substitution_template_mapping: our contribution to service substitution :vartype substitution_template_mapping: :class:`SubstitutionTemplateMapping` - :ivar nodes: Instantiated nodes + :ivar nodes: instantiated nodes :vartype nodes: [:class:`Node`] """ @@ -620,23 +621,23 @@ class GroupTemplateBase(TemplateModelMixin): Groups are logical containers for zero or more nodes. - :ivar name: Name (unique for this service template) + :ivar name: name (unique for this service template) :vartype name: basestring - :ivar type: Group type - :vartype type: :class:`Type` - :ivar description: Human-readable description + :ivar type: group type + + :ivar description: human-readable description :vartype description: basestring - :ivar node_templates: All nodes instantiated by these templates will be members of the group + :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 + :ivar properties: associated parameters + :vartype properties: {:obj:`basestring`: :class:`Property`} + :ivar interface_templates: bundles of operations + :vartype interface_templates: {:obj:`basestring`: :class:`InterfaceTemplate`} + :ivar service_template: containing service template :vartype service_template: :class:`ServiceTemplate` - :ivar policy_templates: Policy templates enacted on this group + :ivar policy_templates: policy templates enacted on this group :vartype policy_templates: [:class:`PolicyTemplate`] - :ivar groups: Instantiated groups + :ivar groups: instantiated groups :vartype groups: [:class:`Group`] """ @@ -754,21 +755,20 @@ 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) + :ivar name: name (unique for this service template) :vartype name: basestring - :ivar type: Policy type - :vartype type: :class:`Type` - :ivar description: Human-readable description + :ivar type: policy type + :ivar description: human-readable description :vartype description: basestring - :ivar node_templates: Policy will be enacted on all nodes instantiated by these templates + :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 + :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 + :ivar properties: associated parameters + :vartype properties: {:obj:`basestring`: :class:`Property`} + :ivar service_template: containing service template :vartype service_template: :class:`ServiceTemplate` - :ivar policies: Instantiated policies + :ivar policies: instantiated policies :vartype policies: [:class:`Policy`] """ @@ -886,13 +886,13 @@ 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 + :ivar node_type: exposed node type + :vartype node_type: Type + :ivar mappings: requirement and capability mappings + :vartype mappings: {:obj:`basestring`: :class:`SubstitutionTemplateMapping`} + :ivar service_template: containing service template :vartype service_template: :class:`ServiceTemplate` - :ivar substitutions: Instantiated substitutions + :ivar substitutions: instantiated substitutions :vartype substitutions: [:class:`Substitution`] """ @@ -970,16 +970,16 @@ class SubstitutionTemplateMappingBase(TemplateModelMixin): Only one of `capability_template` and `requirement_template` can be set. - :ivar name: Exposed capability or requirement name + :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` + :ivar node_template: node template + :vartype node_template: NodeTemplate + :ivar capability_template: capability template in the node template + :vartype capability_template: CapabilityTemplate + :ivar requirement_template: requirement template in the node template + :vartype requirement_template: RequirementTemplate + :ivar substitution_template: containing substitution template + :vartype substitution_template: SubstitutionTemplate """ __tablename__ = 'substitution_template_mapping' @@ -1106,26 +1106,26 @@ class RequirementTemplateBase(TemplateModelMixin): 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) + :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) + :ivar target_node_type: required node type (optional) + :vartype target_node_type: Type + :ivar target_node_template: required node template (optional) + :vartype target_node_template: NodeTemplate + :ivar target_capability_type: required capability type (optional) + :vartype target_capability_type: 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 + :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 + :ivar relationship_template: template for relationships (optional) + :vartype relationship_template: RelationshipTemplate + :ivar node_template: containing node template + :vartype node_template: 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` + :ivar substitution_mapping: our contribution to service substitution + :vartype substitution_mapping: SubstitutionMapping """ __tablename__ = 'requirement_template' @@ -1325,19 +1325,19 @@ class RelationshipTemplateBase(TemplateModelMixin): 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) + :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 + :ivar type: relationship 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 + :ivar properties: associated parameters + :vartype properties: {:obj:`basestring`: :class:`Property`} + :ivar interface_templates: bundles of operations + :vartype interface_templates: {:obj:`basestring`: :class:`InterfaceTemplate`} + :ivar requirement_template: containing requirement template + :vartype requirement_template: RequirementTemplate + :ivar relationships: instantiated relationships :vartype relationships: [:class:`Relationship`] """ @@ -1434,25 +1434,25 @@ 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) + :ivar name: name (unique for the node template) :vartype name: basestring - :ivar type: Capability type - :vartype type: :class:`Type` - :ivar description: Human-readable description + :ivar type: capability 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 + :ivar valid_source_node_types: reject requirements that are not from these node types (optional) + :vartype valid_source_node_types: Type` + :ivar min_occurrences: minimum number of requirement matches required :vartype min_occurrences: int - :ivar max_occurrences: Maximum number of requirement matches allowed + :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 + :ivar properties: associated parameters + :vartype properties: {:obj:`basestring`: :class:`Property`} + :ivar node_template: containing node template + :vartype node_template: NodeTemplate + :ivar substitution_template_mapping: our contribution to service substitution + :vartype substitution_template_mapping: SubstitutionTemplateMapping + :ivar capabilities: instantiated capabilities :vartype capabilities: [:class:`Capability`] """ @@ -1595,23 +1595,23 @@ class InterfaceTemplateBase(TemplateModelMixin): """ A typed set of :class:`OperationTemplate`. - :ivar name: Name (unique for the node, group, or relationship template) + :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 + :ivar type: interface 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 + :ivar inputs: inputs that can be used by all operations in the interface + :vartype inputs: {:obj:`basestring`: :class:`Input`} + :ivar operation_templates: operations + :vartype operation_templates: {:obj:`basestring`: :class:`OperationTemplate`} + :ivar node_template: containing node template + :vartype node_template: NodeTemplate + :ivar group_template: containing group template + :vartype group_template: GroupTemplate + :ivar relationship_template: containing relationship template + :vartype relationship_template: RelationshipTemplate + :ivar interfaces: instantiated interfaces :vartype interfaces: [:class:`Interface`] """ @@ -1737,37 +1737,37 @@ class OperationTemplateBase(TemplateModelMixin): Operations are executed by an associated :class:`PluginSpecification` via an executor. - :ivar name: Name (unique for the interface or service template) + :ivar name: name (unique for the interface or service template) :vartype name: basestring - :ivar description: Human-readable description + :ivar description: human-readable description :vartype description: basestring - :ivar relationship_edge: When true specified that the operation is on the relationship's + :ivar relationship_edge: when ``True`` specifies 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) + :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 + :ivar dependencies: dependency strings (interpreted by the plugin) + :vartype dependencies: [obj:`basestring`] + :ivar inputs: inputs that can be used by this operation + :vartype inputs: {:obj:`basestring`: :class:`Input`} + :ivar plugin_specification: associated plugin + :vartype plugin_specification: PluginSpecification + :ivar configurations: configuration (interpreted by the plugin) + :vartype configurations: {obj:`basestring`: :class:`Configuration`} + :ivar function: name of the operation function :vartype function: basestring - :ivar executor: Name of executor to run the operation with + :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 + :ivar max_attempts: maximum number of attempts allowed in case of failure :vartype max_attempts: int - :ivar retry_interval: Interval between retries (in seconds) + :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 + :ivar interface_template: containing interface template + :vartype interface_template: InterfaceTemplate + :ivar service_template: containing service template + :vartype service_template: ServiceTemplate + :ivar operations: instantiated operations :vartype operations: [:class:`Operation`] """ @@ -1924,25 +1924,25 @@ class ArtifactTemplateBase(TemplateModelMixin): """ A file associated with a :class:`NodeTemplate`. - :ivar name: Name (unique for the node template) + :ivar name: name (unique for the node template) :vartype name: basestring - :ivar type: Artifact type - :vartype type: :class:`Type` - :ivar description: Human-readable description + :ivar type: artifact type + + :ivar description: human-readable description :vartype description: basestring - :ivar source_path: Source path (CSAR or repository) + :ivar source_path: source path (CSAR or repository) :vartype source_path: basestring - :ivar target_path: Path at destination machine + :ivar target_path: path at destination machine :vartype target_path: basestring - :ivar repository_url: Repository URL + :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 + :ivar repository_credential: credentials for accessing the repository + :vartype repository_credential: {:obj:`basestring`: :obj:`basestring`} + :ivar properties: associated parameters + :vartype properties: {:obj:`basestring`: :class:`Property`} + :ivar node_template: containing node template + :vartype node_template: NodeTemplate + :ivar artifacts: instantiated artifacts :vartype artifacts: [:class:`Artifact`] """ @@ -2057,14 +2057,14 @@ class PluginSpecificationBase(TemplateModelMixin): """ Plugin specification. - :ivar name: Required plugin name + :ivar name: required plugin name :vartype name: basestring - :ivar version: Minimum plugin version + :ivar version: minimum plugin version :vartype version: basestring - :ivar enabled: Whether the plugin is enabled + :ivar enabled: whether the plugin is enabled :vartype enabled: bool - :ivar plugin: The matching plugin (or None if not matched) - :vartype plugin: :class:`Plugin` + :ivar plugin: the matching plugin (or ``None`` if not matched) + :vartype plugin: Plugin """ __tablename__ = 'plugin_specification' http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/types.py ---------------------------------------------------------------------- diff --git a/aria/modeling/types.py b/aria/modeling/types.py index d420c6b..4c25f93 100644 --- a/aria/modeling/types.py +++ b/aria/modeling/types.py @@ -14,7 +14,7 @@ # limitations under the License. """ -ARIA modeling types module (private) +Allows JSON-serializable collections to be used as SQLAlchemy column types. """ import json @@ -56,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 @@ -71,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): @@ -121,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: @@ -146,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) @@ -173,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: @@ -185,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 = {} @@ -220,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 = {} @@ -258,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/7ed92d0f/aria/modeling/utils.py ---------------------------------------------------------------------- diff --git a/aria/modeling/utils.py b/aria/modeling/utils.py index 6a2d6df..9d02194 100644 --- a/aria/modeling/utils.py +++ b/aria/modeling/utils.py @@ -14,7 +14,7 @@ # limitations under the License. """ -ARIA modeling utils module +Miscellaneous modeling utilities. """ import os @@ -30,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): + # Hack to make sure Sphinx doesn't grab the base constructor's docstring + super(self, JSONEncoder).__init__(*args, **kwargs) + def default(self, o): # pylint: disable=method-hidden from .mixins import ModelMixin if isinstance(o, ModelMixin): @@ -44,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): @@ -64,11 +71,11 @@ 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`} + :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 http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/orchestrator/decorators.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/decorators.py b/aria/orchestrator/decorators.py index 389bfb8..09a2167 100644 --- a/aria/orchestrator/decorators.py +++ b/aria/orchestrator/decorators.py @@ -32,7 +32,7 @@ OPERATION_DECORATOR_RESERVED_ARGUMENTS = set(('ctx', 'toolbelt')) def workflow(func=None, suffix_template=''): """ - Workflow decorator + Workflow decorator. """ if func is None: return partial(workflow, suffix_template=suffix_template) @@ -58,7 +58,7 @@ def workflow(func=None, suffix_template=''): def operation(func=None, toolbelt=False, suffix_template='', logging_handlers=None): """ - Operation decorator + Operation decorator. """ if func is None: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/orchestrator/workflows/api/task.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/api/task.py b/aria/orchestrator/workflows/api/task.py index f7d2c66..c2600b0 100644 --- a/aria/orchestrator/workflows/api/task.py +++ b/aria/orchestrator/workflows/api/task.py @@ -60,17 +60,17 @@ class OperationTask(BaseTask): :ivar name: formatted name (includes actor type, actor name, and interface/operation names) :vartype name: basestring :ivar actor: node or relationship - :vartype actor: :class:`aria.modeling.models.Node`|:class:`aria.modeling.models.Relationship` + :vartype actor: :class:`Node`|:class:`Relationship` :ivar interface_name: interface name on actor :vartype interface_name: basestring :ivar operation_name: operation name on interface :vartype operation_name: basestring :ivar plugin: plugin (or None for default plugin) - :vartype plugin: :class:`aria.modeling.models.Plugin` + :vartype plugin: :class:`Plugin` :ivar function: path to Python function :vartype function: basestring :ivar arguments: arguments to send to Python function - :vartype arguments: {basestring, :class:`aria.modeling.models.Argument`} + :vartype arguments: {::obj:`basestring`: :class:`Argument`} :ivar ignore_failure: whether to ignore failures :vartype ignore_failure: bool :ivar max_attempts: maximum number of attempts allowed in case of failure @@ -91,13 +91,13 @@ class OperationTask(BaseTask): retry_interval=None): """ :param actor: node or relationship - :type actor: :class:`aria.modeling.models.Node`|:class:`aria.modeling.models.Relationship` + :type actor: :class:`Node`|:class:`Relationship` :param interface_name: interface name on actor :type interface_name: basestring :param operation_name: operation name on interface :type operation_name: basestring :param arguments: override argument values - :type arguments: {basestring, object} + :type arguments: {:obj:`basestring`: object} :param ignore_failure: override whether to ignore failures :type ignore_failure: bool :param max_attempts: override maximum number of attempts allowed in case of failure http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/consumption/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/consumption/context.py b/aria/parser/consumption/context.py index a8b75df..e73a8ab 100644 --- a/aria/parser/consumption/context.py +++ b/aria/parser/consumption/context.py @@ -29,16 +29,20 @@ _thread_locals = threading.local() class ConsumptionContext(object): """ - Properties: - - * :code:`args`: The runtime arguments (usually provided on the command line) - * :code:`out`: Message output stream (defaults to stdout) - * :code:`style`: Message output style - * :code:`validation`: :class:`aria.validation.ValidationContext` - * :code:`loading`: :class:`aria.loading.LoadingContext` - * :code:`reading`: :class:`aria.reading.ReadingContext` - * :code:`presentation`: :class:`aria.presentation.PresentationContext` - * :code:`modeling`: :class:`aria.service.ModelingContext` + :ivar args: runtime arguments (usually provided on the command line) + :ivar out: message output stream (defaults to stdout) + :ivar style: message output style + :vartype style: Style + :ivar validation: validation context + :vartype validation: :class:`ValidationContext` + :ivar loading: loading context + :vartype loading: :class:`LoadingContext` + :ivar reading: reading context + :vartype reading: :class:`ReadingContext` + :ivar presentation: presentation context + :vartype presentation: :class:`PresentationContext` + :ivar modeling: modeling context + :vartype modeling: :class:`ModelingContext` """ @staticmethod @@ -71,7 +75,7 @@ class ConsumptionContext(object): def write(self, string): """ - Writes to our :code:`out`, making sure to encode UTF-8 if required. + Writes to our ``out``, making sure to encode UTF-8 if required. """ try: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/consumption/presentation.py ---------------------------------------------------------------------- diff --git a/aria/parser/consumption/presentation.py b/aria/parser/consumption/presentation.py index 7766473..fc41614 100644 --- a/aria/parser/consumption/presentation.py +++ b/aria/parser/consumption/presentation.py @@ -26,11 +26,11 @@ class Read(Consumer): """ Reads the presentation, handling imports recursively. - It works by consuming a data source via appropriate :class:`aria.loader.Loader`, - :class:`aria.reader.Reader`, and :class:`aria.presenter.Presenter` instances. + It works by consuming a data source via appropriate :class:`aria.parser.loader.Loader`, + :class:`aria.parser.reader.Reader`, and :class:`aria.parser.presenter.Presenter` instances. It supports agnostic raw data composition for presenters that have - :code:`_get_import_locations` and :code:`_merge_import`. + ``_get_import_locations`` and ``_merge_import``. To improve performance, loaders are called asynchronously on separate threads. http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/loading/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/context.py b/aria/parser/loading/context.py index 44e3fd1..e4ada0e 100644 --- a/aria/parser/loading/context.py +++ b/aria/parser/loading/context.py @@ -22,8 +22,10 @@ class LoadingContext(object): """ Properties: - * :code:`loader_source`: For finding loader instances - * :code:`prefixes`: List of additional prefixes for :class:`UriTextLoader` + :ivar loader_source: for finding loader instances + :vartype loader_source: LoaderSource + :ivar prefixes: additional prefixes for :class:`UriTextLoader` + :vartype prefixes: [:obj:`basestring`] """ def __init__(self): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/loading/literal.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/literal.py b/aria/parser/loading/literal.py index 1b99fd8..c9a4335 100644 --- a/aria/parser/loading/literal.py +++ b/aria/parser/loading/literal.py @@ -21,7 +21,7 @@ class LiteralLoader(Loader): """ ARIA literal loader. - See :class:`aria.loading.LiteralLocation`. + See :class:`aria.parser.loading.LiteralLocation`. """ def __init__(self, location): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/loading/location.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/location.py b/aria/parser/loading/location.py index 5bc6fab..f31c330 100644 --- a/aria/parser/loading/location.py +++ b/aria/parser/loading/location.py @@ -23,8 +23,8 @@ class Location(object): """ Base class for ARIA locations. - Locations are used by :class:`aria.loading.LoaderSource` to delegate to - an appropriate :class:`aria.loading.Loader`. + Locations are used by :class:`aria.parser.loading.LoaderSource` to delegate to + an appropriate :class:`aria.parser.loading.Loader`. """ def is_equivalent(self, location): @@ -41,7 +41,7 @@ class UriLocation(Location): If no scheme is included, it should be treated as a filesystem path. - See :class:`aria.loading.UriTextLoader`. + See :class:`aria.parser.loading.UriTextLoader`. """ def __init__(self, uri): @@ -68,7 +68,7 @@ class LiteralLocation(Location): """ A location that embeds content. - See :class:`aria.loading.LiteralLoader`. + See :class:`aria.parser.loading.LiteralLoader`. """ def __init__(self, content, name='literal'): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/loading/uri.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/uri.py b/aria/parser/loading/uri.py index 1b23bf6..30f4e44 100644 --- a/aria/parser/loading/uri.py +++ b/aria/parser/loading/uri.py @@ -29,14 +29,14 @@ class UriTextLoader(Loader): """ Base class for ARIA URI loaders. - See :class:`aria.loading.UriLocation`. + See :class:`aria.parser.loading.UriLocation`. Supports a list of search prefixes that are tried in order if the URI cannot be found. They will be: - * If :code:`origin_location` is provided its prefix will come first. + * If ``origin_location`` is provided its prefix will come first. * Then the prefixes in the :class:`LoadingContext` will be added. - * Finally, the global prefixes specified in :code:`URI_LOADER_PREFIXES` will be added. + * Finally, the global prefixes specified in ``URI_LOADER_PREFIXES`` will be added. """ def __init__(self, context, location, origin_location=None): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/modeling/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/modeling/context.py b/aria/parser/modeling/context.py index 4a53641..d482a10 100644 --- a/aria/parser/modeling/context.py +++ b/aria/parser/modeling/context.py @@ -38,14 +38,18 @@ class IdType(object): class ModelingContext(object): """ - Properties: - - * :code:`template`: The generated service template - * :code:`instance`: The generated service instance - * :code:`node_id_format`: Format for node instance IDs - * :code:`id_type`: Type of IDs to use for instances - * :code:`id_max_length`: Maximum allowed instance ID length - * :code:`inputs`: Dict of inputs values + :ivar template: generated service template + :vartype template: aria.modeling.models.ServiceTemplate + :ivar instance: generated service instance + :vartype instance: aria.modeling.models.Service + :ivar node_id_format: format for node instance IDs + :vartype node_id_format: basestring + :ivar id_type: type of IDs to use for instances + :vartype id_type: basestring + :ivar id_max_length: maximum allowed instance ID length + :vartype id_max_length: int + :ivar inputs: inputs values + :vartype inputs: {basestring, object} """ def __init__(self): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/presentation/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/context.py b/aria/parser/presentation/context.py index 26dcb39..eaa2103 100644 --- a/aria/parser/presentation/context.py +++ b/aria/parser/presentation/context.py @@ -19,16 +19,22 @@ from .source import DefaultPresenterSource class PresentationContext(object): """ - Properties: - - * :code:`presenter`: The generated presenter instance - * :code:`location`: From where we will generate the presenter - * :code:`presenter_source`: For finding presenter classes - * :code:`presenter_class`: Overrides :code:`presenter_source` with a specific class - * :code:`import_profile`: Whether to import the profile by default (defaults to true) - * :code:`threads`: Number of threads to use when reading data - * :code:`timeout`: Timeout in seconds for loading data - * :code:`print_exceptions`: Whether to print exceptions while reading data + :ivar presenter: the generated presenter instance + :vartype presenter: Presenter + :ivar location: from where we will generate the presenter + :vartype location: Location + :ivar presenter_source: for finding presenter classes + :vartype presenter_source: PresenterSource + :ivar presenter_class: overrides ``presenter_source`` with a specific class + :vartype presenter_class: type + :ivar import_profile: whether to import the profile by default (defaults to ``True``) + :vartype import_profile: bool + :ivar threads: number of threads to use when reading data + :vartype threads: int + :ivar timeout: timeout in seconds for loading data + :vartype timeout: float + :ivar print_exceptions: whether to print exceptions while reading data + :vartype print_exceptions: bool """ def __init__(self): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/presentation/field_validators.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/field_validators.py b/aria/parser/presentation/field_validators.py index 9903a1b..aa04913 100644 --- a/aria/parser/presentation/field_validators.py +++ b/aria/parser/presentation/field_validators.py @@ -25,9 +25,9 @@ def type_validator(type_name, *types_dict_names): Makes sure that the field refers to an existing type defined in the root presenter. The arguments from the second onwards are used to locate a nested field under - :code:`service_template` under the root presenter. The first of these can optionally - be a function, in which case it will be called to convert type names. This can be used - to support shorthand type names, aliases, etc. + ``service_template`` under the root presenter. The first of these can optionally be a function, + in which case it will be called to convert type names. This can be used to support shorthand + type names, aliases, etc. Can be used with the :func:`field_validator` decorator. """ @@ -58,9 +58,9 @@ def list_type_validator(type_name, *types_dict_names): Assumes that the field is a list. The arguments from the second onwards are used to locate a nested field under - :code:`service_template` under the root presenter. The first of these can optionally - be a function, in which case it will be called to convert type names. This can be used - to support shorthand type names, aliases, etc. + ``service_template`` under the root presenter. The first of these can optionally be a function, + in which case it will be called to convert type names. This can be used to support shorthand + type names, aliases, etc. Can be used with the :func:`field_validator` decorator. """ @@ -115,10 +115,9 @@ def derived_from_validator(*types_dict_names): Checks that we do not derive from ourselves and that we do not cause a circular hierarchy. - The arguments are used to locate a nested field under - :code:`service_template` under the root presenter. - The first of these can optionally be a function, in which case it will be called to convert type - names. This can be used to support shorthand type names, aliases, etc. + The arguments are used to locate a nested field under ``service_template`` under the root + presenter. The first of these can optionally be a function, in which case it will be called to + convert type names. This can be used to support shorthand type names, aliases, etc. Can be used with the :func:`field_validator` decorator. """ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/presentation/fields.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/fields.py b/aria/parser/presentation/fields.py index 7f85723..959bad1 100644 --- a/aria/parser/presentation/fields.py +++ b/aria/parser/presentation/fields.py @@ -39,19 +39,16 @@ def has_fields(cls): """ Class decorator for validated field support. - 1. Adds a :code:`FIELDS` class property that is a dict of all the fields. - Will inherit and merge :code:`FIELDS` properties from base classes if - they have them. + 1. Adds a ``FIELDS`` class property that is a dict of all the fields. Will inherit and merge + ``FIELDS`` properties from base classes if they have them. - 2. Generates automatic :code:`@property` implementations for the fields - with the help of a set of special function decorators. + 2. Generates automatic ``@property`` implementations for the fields with the help of a set of + special function decorators. - The class also works with the Python dict protocol, so that - fields can be accessed via dict semantics. The functionality is - identical to that of using attribute access. + The class also works with the Python dict protocol, so that fields can be accessed via dict + semantics. The functionality is identical to that of using attribute access. - The class will also gain two utility methods, :code:`_iter_field_names` - and :code:`_iter_fields`. + The class will also gain two utility methods, ``_iter_field_names`` and ``_iter_fields``. """ # Make sure we have FIELDS @@ -267,8 +264,8 @@ def field_getter(getter_func): """ Method decorator for overriding the getter function of a field. - The signature of the getter function must be: :code:`f(field, presentation, context)`. - The default getter can be accessed as :code:`field.default_get(presentation, context)`. + The signature of the getter function must be: ``f(field, presentation, context)``. + The default getter can be accessed as ```field.default_get(presentation, context)``. The function must already be decorated with a field decorator. """ @@ -286,8 +283,8 @@ def field_setter(setter_func): """ Method decorator for overriding the setter function of a field. - The signature of the setter function must be: :code:`f(field, presentation, context, value)`. - The default setter can be accessed as :code:`field.default_set(presentation, context, value)`. + The signature of the setter function must be: ``f(field, presentation, context, value)``. + The default setter can be accessed as ``field.default_set(presentation, context, value)``. The function must already be decorated with a field decorator. """ @@ -305,8 +302,8 @@ def field_validator(validator_fn): """ Method decorator for overriding the validator function of a field. - The signature of the validator function must be: :code:f(field, presentation, context)`. - The default validator can be accessed as :code:`field.default_validate(presentation, context)`. + The signature of the validator function must be: ``f(field, presentation, context)``. + The default validator can be accessed as ``field.default_validate(presentation, context)``. The function must already be decorated with a field decorator. """ @@ -373,7 +370,7 @@ def has_fields_contains(self, key): class Field(object): """ - Field handler used by :code:`@has_fields` decorator. + Field handler used by ``@has_fields`` decorator. """ def __init__(self, field_variant, func, cls=None, default=None, allowed=None, required=False): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/presentation/null.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/null.py b/aria/parser/presentation/null.py index a018df4..287d2ba 100644 --- a/aria/parser/presentation/null.py +++ b/aria/parser/presentation/null.py @@ -33,7 +33,7 @@ NULL = Null() def none_to_null(value): """ - Convert :code:`None` to :code:`NULL`, recursively. + Convert ``None`` to ``NULL``, recursively. """ if value is None: @@ -51,7 +51,7 @@ def none_to_null(value): def null_to_none(value): """ - Convert :code:`NULL` to :code:`None`, recursively. + Convert ``NULL`` to ``None``, recursively. """ if value is NULL: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/presentation/presentation.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/presentation.py b/aria/parser/presentation/presentation.py index 644d880..b92506c 100644 --- a/aria/parser/presentation/presentation.py +++ b/aria/parser/presentation/presentation.py @@ -52,18 +52,17 @@ class PresentationBase(HasCachedMethods): def _validate(self, context): """ - Validates the presentation while reporting errors in the validation context but - *not* raising exceptions. + Validates the presentation while reporting errors in the validation context but *not* + raising exceptions. - The base class does not thing, but subclasses may override this for specialized - validation. + The base class does not thing, but subclasses may override this for specialized validation. """ @property def _fullname(self): """ - Always returns a usable full name of the presentation, whether it itself is named, - or recursing to its container, and finally defaulting to the class name. + Always returns a usable full name of the presentation, whether it itself is named, or + recursing to its container, and finally defaulting to the class name. """ if self._name is not None: @@ -75,10 +74,10 @@ class PresentationBase(HasCachedMethods): @property def _locator(self): """ - Attempts to return the most relevant locator, whether we have one, or recursing - to our container. + Attempts to return the most relevant locator, whether we have one, or recursing to our + container. - :rtype: :class:`aria.reading.Locator` + :rtype: :class:`aria.parser.reading.Locator` """ return get_locator(self._raw, self._container) @@ -98,8 +97,8 @@ class PresentationBase(HasCachedMethods): def _get_from_dict(self, *names): """ - Gets attributes recursively, except for the last name which is used - to get a value from the last dict. + Gets attributes recursively, except for the last name which is used to get a value from the + last dict. """ if names: @@ -110,10 +109,10 @@ class PresentationBase(HasCachedMethods): def _get_child_locator(self, *names): """ - Attempts to return the locator of one our children. Will default to our locator - if not found. + Attempts to return the locator of one our children. Will default to our locator if not + found. - :rtype: :class:`aria.reading.Locator` + :rtype: :class:`aria.parser.reading.Locator` """ if hasattr(self._raw, '_locator'): @@ -126,9 +125,8 @@ class PresentationBase(HasCachedMethods): """ Emits a colorized representation. - The base class will emit a sensible default representation of the fields, - (by calling :code:`_dump_content`), but subclasses may override this for specialized - dumping. + The base class will emit a sensible default representation of the fields, (by calling + ``_dump_content``), but subclasses may override this for specialized dumping. """ if self._name: @@ -142,8 +140,8 @@ class PresentationBase(HasCachedMethods): """ Emits a colorized representation of the contents. - The base class will call :code:`_dump_field` on all the fields, but subclasses may - override this for specialized dumping. + The base class will call ``_dump_field`` on all the fields, but subclasses may override + this for specialized dumping. """ if field_names: @@ -159,8 +157,8 @@ class PresentationBase(HasCachedMethods): """ Emits a colorized representation of the field. - According to the field type, this may trigger nested recursion. The nested - types will delegate to their :code:`_dump` methods. + According to the field type, this may trigger nested recursion. The nested types will + delegate to their ``_dump`` methods. """ field = self.FIELDS[field_name] # pylint: disable=no-member @@ -179,16 +177,14 @@ class PresentationBase(HasCachedMethods): class Presentation(PresentationBase): """ - Base class for ARIA presentations. A presentation is a Pythonic wrapper around - agnostic raw data, adding the ability to read and modify the data with proper - validation. + Base class for ARIA presentations. A presentation is a Pythonic wrapper around agnostic raw + data, adding the ability to read and modify the data with proper validation. - ARIA presentation classes will often be decorated with @has_fields, as that - mechanism automates a lot of field-specific validation. However, that is not a - requirement. + ARIA presentation classes will often be decorated with ``@has_fields``, as that mechanism + automates a lot of field-specific validation. However, that is not a requirement. - Make sure that your utility property and method names begin with a "_", because - those names without a "_" prefix are normally reserved for fields. + Make sure that your utility property and method names begin with a "\_", because those names + without a "\_" prefix are normally reserved for fields. """ def _validate(self, context): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/presentation/source.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/source.py b/aria/parser/presentation/source.py index 7198b07..4bfb8e1 100644 --- a/aria/parser/presentation/source.py +++ b/aria/parser/presentation/source.py @@ -32,7 +32,7 @@ class PresenterSource(object): class DefaultPresenterSource(PresenterSource): """ - The default ARIA presenter source supports TOSCA Simple Profile. + The default ARIA presenter source. """ def __init__(self, classes=None): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/presentation/utils.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/utils.py b/aria/parser/presentation/utils.py index fbe971b..f0fd390 100644 --- a/aria/parser/presentation/utils.py +++ b/aria/parser/presentation/utils.py @@ -25,7 +25,7 @@ def get_locator(*values): """ Gets the first available locator. - :rtype: :class:`aria.reading.Locator` + :rtype: :class:`aria.parser.reading.Locator` """ for v in values: @@ -53,7 +53,7 @@ def validate_primitive(value, cls, coerce=False): Checks if the value is of the primitive type, optionally attempting to coerce it if it is not. - Raises a :code:`ValueError` if it isn't or if coercion failed. + :raises ValueError: if not a primitive type or if coercion failed. """ if (cls is not None) and (value is not None) and (value is not NULL): @@ -112,14 +112,14 @@ def validate_known_fields(context, presentation): def get_parent_presentation(context, presentation, *types_dict_names): """ - Returns the parent presentation according to the :code:`derived_from` field, or None if invalid. + Returns the parent presentation according to the ``derived_from`` field, or ``None`` if invalid. Checks that we do not derive from ourselves and that we do not cause a circular hierarchy. The arguments from the third onwards are used to locate a nested field under - :code:`service_template` under the root presenter. The first of these can optionally - be a function, in which case it will be called to convert type names. This can be used - to support shorthand type names, aliases, etc. + ``service_template`` under the root presenter. The first of these can optionally be a function, + in which case it will be called to convert type names. This can be used to support shorthand + type names, aliases, etc. """ type_name = presentation.derived_from http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/reading/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/reading/context.py b/aria/parser/reading/context.py index 02d4de9..12f27e8 100644 --- a/aria/parser/reading/context.py +++ b/aria/parser/reading/context.py @@ -16,10 +16,10 @@ from .source import DefaultReaderSource class ReadingContext(object): """ - Properties: - - * :code:`reader_source`: For finding reader instances - * :code:`reader`: Overrides :code:`reader_source` with a specific class + :ivar reader_source: for finding reader instances + :vartype reader_source: ReaderSource + :ivar reader: overrides ``reader_source`` with a specific class + :vartype reader: type """ def __init__(self): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/reading/locator.py ---------------------------------------------------------------------- diff --git a/aria/parser/reading/locator.py b/aria/parser/reading/locator.py index 4142ee7..965164d 100644 --- a/aria/parser/reading/locator.py +++ b/aria/parser/reading/locator.py @@ -124,7 +124,7 @@ class Locator(object): def deepcopy_with_locators(value): """ - Like :code:`deepcopy`, but also copies over locators. + Like :func:`deepcopy`, but also copies over locators. """ res = deepcopy(value) @@ -134,7 +134,7 @@ def deepcopy_with_locators(value): def copy_locators(target, source): """ - Copies over :code:`_locator` for all elements, recursively. + Copies over ``_locator`` for all elements, recursively. Assumes that target and source have exactly the same list/dict structure. """ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/reading/reader.py ---------------------------------------------------------------------- diff --git a/aria/parser/reading/reader.py b/aria/parser/reading/reader.py index fe64697..1a29f11 100644 --- a/aria/parser/reading/reader.py +++ b/aria/parser/reading/reader.py @@ -18,7 +18,7 @@ class Reader(object): """ Base class for ARIA readers. - Readers provide agnostic raw data by consuming :class:`aria.loading.Loader` instances. + Readers provide agnostic raw data by consuming :class:`aria.parser.loading.Loader` instances. """ def __init__(self, context, location, loader): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/parser/validation/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/validation/context.py b/aria/parser/validation/context.py index d81f1cd..cc87973 100644 --- a/aria/parser/validation/context.py +++ b/aria/parser/validation/context.py @@ -23,13 +23,14 @@ from ...utils.formatting import as_raw class ValidationContext(object): """ - Properties: - - * :code:`allow_unknown_fields`: When False (the default) will report an issue - if an unknown field is used - * :code:`allow_primitive_coersion`: When False (the default) will not attempt to - coerce primitive field types - * :code:`max_level`: Maximum validation level to report (default is all) + :ivar allow_unknown_fields: when ``False`` (the default) will report an issue if an unknown + field is used + :vartype allow_unknown_fields: bool + :ivar allow_primitive_coersion`: when ``False`` (the default) will not attempt to coerce + primitive field types + :vartype allow_primitive_coersion: bool + :ivar max_level: maximum validation level to report (default is all) + :vartype max_level: int """ def __init__(self): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/utils/__init__.py ---------------------------------------------------------------------- diff --git a/aria/utils/__init__.py b/aria/utils/__init__.py index da51070..2a957a9 100644 --- a/aria/utils/__init__.py +++ b/aria/utils/__init__.py @@ -14,5 +14,5 @@ # limitations under the License. """ -ARIA utilities package +General-purpose utilities package. """ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/utils/argparse.py ---------------------------------------------------------------------- diff --git a/aria/utils/argparse.py b/aria/utils/argparse.py index b4ad8ac..f8d7e88 100644 --- a/aria/utils/argparse.py +++ b/aria/utils/argparse.py @@ -31,7 +31,7 @@ class ArgumentParser(BaseArgumentParser): def add_flag_argument(self, name, help_true=None, help_false=None, default=False): """ - Adds a flag argument as two arguments: :code:`--my-flag` and :code:`--no-my-flag`. + Adds a flag argument as two arguments: ``--my-flag`` and ``--no-my-flag``. """ dest = name.replace('-', '_') http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/utils/caching.py ---------------------------------------------------------------------- diff --git a/aria/utils/caching.py b/aria/utils/caching.py index 47aa7c4..5c82b0d 100644 --- a/aria/utils/caching.py +++ b/aria/utils/caching.py @@ -31,8 +31,8 @@ class cachedmethod(object): # pylint: disable=invalid-name The implementation is thread-safe. - Supports :code:`cache_info` to be compatible with Python 3's :code:`functools.lru_cache`. - Note that the statistics are combined for all instances of the class. + Supports ``cache_info`` to be compatible with Python 3's ``functools.lru_cache``. Note that the + statistics are combined for all instances of the class. Won't use the cache if not called when bound to an object, allowing you to override the cache. @@ -43,6 +43,7 @@ class cachedmethod(object): # pylint: disable=invalid-name ENABLED = True def __init__(self, func): + self.__doc__ = func.__doc__ self.func = func self.hits = 0 self.misses = 0 http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/utils/collections.py ---------------------------------------------------------------------- diff --git a/aria/utils/collections.py b/aria/utils/collections.py index 93c56fa..89bb390 100644 --- a/aria/utils/collections.py +++ b/aria/utils/collections.py @@ -243,7 +243,7 @@ def is_removable(_container, _key, v): def prune(value, is_removable_function=is_removable): """ - Deletes :code:`None` and empty lists and dicts, recursively. + Deletes ``None`` and empty lists and dicts, recursively. """ if isinstance(value, list): @@ -262,10 +262,10 @@ def prune(value, is_removable_function=is_removable): return value -# TODO (left for tal): Move following two methods to some place parser specific +# TODO: Move following two methods to some place parser specific def deepcopy_with_locators(value): """ - Like :code:`deepcopy`, but also copies over locators. + Like :func:`deepcopy`, but also copies over locators. """ res = deepcopy(value) @@ -275,7 +275,7 @@ def deepcopy_with_locators(value): def copy_locators(target, source): """ - Copies over :code:`_locator` for all elements, recursively. + Copies over ``_locator`` for all elements, recursively. Assumes that target and source have exactly the same list/dict structure. """ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/utils/formatting.py ---------------------------------------------------------------------- diff --git a/aria/utils/formatting.py b/aria/utils/formatting.py index b35f801..0ccfa9f 100644 --- a/aria/utils/formatting.py +++ b/aria/utils/formatting.py @@ -46,8 +46,7 @@ yaml.representer.RoundTripRepresenter.add_representer( class JsonAsRawEncoder(json.JSONEncoder): """ - A :class:`JSONEncoder` that will use the :code:`as_raw` property of objects - if available. + A :class:`JSONEncoder` that will use the ``as_raw`` property of objects if available. """ def raw_encoder_default(self, obj): try: @@ -65,8 +64,7 @@ class JsonAsRawEncoder(json.JSONEncoder): class YamlAsRawDumper(yaml.dumper.RoundTripDumper): # pylint: disable=too-many-ancestors """ - A :class:`RoundTripDumper` that will use the :code:`as_raw` property of objects - if available. + A :class:`RoundTripDumper` that will use the ``as_raw`` property of objects if available. """ def represent_data(self, data): @@ -105,8 +103,8 @@ def decode_dict(data): def safe_str(value): """ - Like :code:`str` coercion, but makes sure that Unicode strings are properly - encoded, and will never return None. + Like :func:`str` coercion, but makes sure that Unicode strings are properly encoded, and will + never return ``None``. """ try: @@ -117,7 +115,7 @@ def safe_str(value): def safe_repr(value): """ - Like :code:`repr`, but calls :code:`as_raw` and :code:`as_agnostic` first. + Like :func:`repr`, but calls :func:`as_raw` and :func:`as_agnostic` first. """ return repr(as_agnostic(as_raw(value))) @@ -147,7 +145,7 @@ def pluralize(noun): def as_raw(value): """ - Converts values using their :code:`as_raw` property, if it exists, recursively. + Converts values using their ``as_raw`` property, if it exists, recursively. """ if hasattr(value, 'as_raw'): @@ -168,7 +166,7 @@ def as_raw(value): def as_raw_list(value): """ - Assuming value is a list, converts its values using :code:`as_raw`. + Assuming value is a list, converts its values using :func:`as_raw`. """ if value is None: @@ -180,8 +178,7 @@ def as_raw_list(value): def as_raw_dict(value): """ - Assuming value is a dict, converts its values using :code:`as_raw`. - The keys are left as is. + Assuming value is a dict, converts its values using :func:`as_raw`. The keys are left as is. """ if value is None: @@ -192,8 +189,8 @@ def as_raw_dict(value): def as_agnostic(value): """ - Converts subclasses of list and dict to standard lists and dicts, and Unicode strings - to non-Unicode if possible, recursively. + Converts subclasses of list and dict to standard lists and dicts, and Unicode strings to + non-Unicode if possible, recursively. Useful for creating human-readable output of structures. """ @@ -220,8 +217,7 @@ def as_agnostic(value): def json_dumps(value, indent=2): """ - JSON dumps that supports Unicode and the :code:`as_raw` property of objects - if available. + JSON dumps that supports Unicode and the ``as_raw`` property of objects if available. """ return json.dumps(value, indent=indent, ensure_ascii=False, cls=JsonAsRawEncoder) @@ -229,8 +225,7 @@ def json_dumps(value, indent=2): def yaml_dumps(value, indent=2): """ - YAML dumps that supports Unicode and the :code:`as_raw` property of objects - if available. + YAML dumps that supports Unicode and the ``as_raw`` property of objects if available. """ return yaml.dump(value, indent=indent, allow_unicode=True, Dumper=YamlAsRawDumper) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/utils/threading.py ---------------------------------------------------------------------- diff --git a/aria/utils/threading.py b/aria/utils/threading.py index 5bced68..d60f28f 100644 --- a/aria/utils/threading.py +++ b/aria/utils/threading.py @@ -30,6 +30,7 @@ from .exceptions import print_exception class ExecutorException(Exception): pass + class DaemonThread(Thread): def __init__(self, *args, **kwargs): super(DaemonThread, self).__init__(*args, **kwargs) @@ -58,6 +59,7 @@ class DaemonThread(Thread): # Exceptions might occur in daemon threads during interpreter shutdown pass + # https://gist.github.com/tliron/81dd915166b0bfc64be08b4f8e22c835 class FixedThreadPoolExecutor(object): """ @@ -135,7 +137,7 @@ class FixedThreadPoolExecutor(object): The task will be called ASAP on the next available worker thread in the pool. - Will raise an :class:`ExecutorException` exception if cannot be submitted. + :raises ExecutorException: if cannot be submitted """ try: @@ -242,6 +244,7 @@ class FixedThreadPoolExecutor(object): self.close() return False + class LockedList(list): """ A list that supports the "with" keyword with a built-in lock. http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/utils/uris.py ---------------------------------------------------------------------- diff --git a/aria/utils/uris.py b/aria/utils/uris.py index 75f376d..c2f276e 100644 --- a/aria/utils/uris.py +++ b/aria/utils/uris.py @@ -26,7 +26,7 @@ _IS_WINDOWS = (os.name == 'nt') def as_file(uri): """ - If the URI is a file (either the :code:`file` scheme or no scheme), then returns the normalized + If the URI is a file (either the ``file`` scheme or no scheme), then returns the normalized path. Otherwise, returns None. """ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/docs/aria.modeling.rst ---------------------------------------------------------------------- diff --git a/docs/aria.modeling.rst b/docs/aria.modeling.rst index 3daa0a0..d7fd138 100644 --- a/docs/aria.modeling.rst +++ b/docs/aria.modeling.rst @@ -45,6 +45,11 @@ .. automodule:: aria.modeling.relationship +:mod:`aria.modeling.types` +########################## + +.. automodule:: aria.modeling.types + :mod:`aria.modeling.utils` ########################## http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/docs/conf.py ---------------------------------------------------------------------- diff --git a/docs/conf.py b/docs/conf.py index 330118c..4f57968 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -48,7 +48,11 @@ with open('../VERSION') as f: # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -extensions = ['sphinx.ext.autodoc', 'sphinx_click.ext'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.intersphinx', + 'sphinx_click.ext' +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -351,19 +355,54 @@ texinfo_documents = [ # # texinfo_no_detailmenu = False + +# -- Options for InterSphinx + +intersphinx_mapping = { + 'python': ('https://docs.python.org/2.7', None) +} + # -- Options for Python domain -# Include __init__ docstring into class docstring +# Append __init__ docstring into class docstring autoclass_content = 'both' # Default to everything important -autodoc_default_flags = ['members', 'undoc-members', 'show-inheritance'] +autodoc_default_flags = [ + 'members', + 'undoc-members', + 'show-inheritance' +] +_skip_fields = ( + 'FIELDS', + 'ALLOW_UNKNOWN_FIELDS', + 'SHORT_FORM_FIELD' +) + +_no_skip_fields = ( + '__evaluate__', +) + +# Event handling def on_skip_members(app, what, name, obj, skip, options): - if not skip: - if name in ('FIELDS', 'ALLOW_UNKNOWN_FIELDS', 'SHORT_FORM_FIELD'): - skip = True + if (name in _skip_fields) or name.endswith('_fk'): + skip = True + elif name in _no_skip_fields: + skip = False return skip - + +from sphinx.domains.python import PythonDomain + +class PatchedPythonDomain(PythonDomain): + # See: https://github.com/sphinx-doc/sphinx/issues/3866 + def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + if 'refspecific' in node: + del node['refspecific'] + return super(PatchedPythonDomain, self).resolve_xref( + env, fromdocname, builder, typ, target, node, contnode) + def setup(app): app.connect('autodoc-skip-member', on_skip_members) + app.override_domain(PatchedPythonDomain) + print PatchedPythonDomain.roles
