Final work
Project: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/commit/5be27b0c Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/5be27b0c Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/5be27b0c Branch: refs/heads/ARIA-286-sphinx-documentation Commit: 5be27b0c0053dafacf67a4b0f068055c10dff28b Parents: 4ebbbb1 Author: Tal Liron <[email protected]> Authored: Wed Jun 28 18:27:11 2017 -0500 Committer: Tal Liron <[email protected]> Committed: Wed Jun 28 18:27:11 2017 -0500 ---------------------------------------------------------------------- aria/logger.py | 7 +- aria/modeling/mixins.py | 20 +-- aria/modeling/models.py | 162 ++++++++++++------- aria/modeling/orchestration.py | 19 +-- aria/modeling/relationship.py | 88 +++++----- aria/modeling/service_changes.py | 13 +- aria/modeling/service_instance.py | 16 +- aria/modeling/service_template.py | 7 +- aria/modeling/utils.py | 29 +++- aria/orchestrator/__init__.py | 2 +- aria/orchestrator/context/__init__.py | 2 +- aria/orchestrator/context/common.py | 37 ++--- aria/orchestrator/context/exceptions.py | 4 +- aria/orchestrator/context/operation.py | 8 +- aria/orchestrator/context/toolbelt.py | 11 +- aria/orchestrator/context/workflow.py | 22 ++- aria/orchestrator/decorators.py | 2 +- aria/orchestrator/events.py | 5 +- aria/orchestrator/exceptions.py | 4 +- aria/orchestrator/execution_plugin/__init__.py | 4 + aria/orchestrator/execution_plugin/common.py | 28 ++-- aria/orchestrator/execution_plugin/constants.py | 4 + .../execution_plugin/ctx_proxy/__init__.py | 4 + .../execution_plugin/ctx_proxy/client.py | 4 + .../execution_plugin/ctx_proxy/server.py | 4 + .../execution_plugin/environment_globals.py | 63 ++++---- .../orchestrator/execution_plugin/exceptions.py | 15 +- .../execution_plugin/instantiation.py | 4 + aria/orchestrator/execution_plugin/local.py | 4 + .../orchestrator/execution_plugin/operations.py | 4 + .../execution_plugin/ssh/__init__.py | 4 + .../execution_plugin/ssh/operations.py | 4 + aria/orchestrator/plugin.py | 22 ++- aria/orchestrator/workflow_runner.py | 21 +-- aria/orchestrator/workflows/__init__.py | 4 + aria/orchestrator/workflows/api/__init__.py | 2 +- aria/orchestrator/workflows/api/task.py | 70 ++++---- aria/orchestrator/workflows/api/task_graph.py | 129 ++++++++------- aria/orchestrator/workflows/builtin/__init__.py | 2 +- .../workflows/builtin/execute_operation.py | 14 +- aria/orchestrator/workflows/builtin/heal.py | 36 ++--- aria/orchestrator/workflows/builtin/install.py | 5 +- aria/orchestrator/workflows/builtin/start.py | 5 +- aria/orchestrator/workflows/builtin/stop.py | 5 +- .../orchestrator/workflows/builtin/uninstall.py | 5 +- aria/orchestrator/workflows/core/__init__.py | 2 +- aria/orchestrator/workflows/core/compile.py | 8 +- aria/orchestrator/workflows/core/engine.py | 10 +- .../workflows/core/events_handler.py | 5 +- aria/orchestrator/workflows/events_logging.py | 5 +- aria/orchestrator/workflows/exceptions.py | 11 +- .../orchestrator/workflows/executor/__init__.py | 2 +- aria/orchestrator/workflows/executor/base.py | 9 +- aria/orchestrator/workflows/executor/celery.py | 4 +- aria/orchestrator/workflows/executor/dry.py | 5 +- aria/orchestrator/workflows/executor/process.py | 4 +- aria/orchestrator/workflows/executor/thread.py | 10 +- aria/parser/__init__.py | 2 +- aria/parser/consumption/__init__.py | 32 ++++ aria/parser/consumption/consumer.py | 4 +- aria/parser/consumption/context.py | 2 + aria/parser/consumption/presentation.py | 5 +- aria/parser/exceptions.py | 4 + aria/parser/loading/__init__.py | 35 ++++ aria/parser/loading/context.py | 4 +- aria/parser/loading/literal.py | 2 +- aria/parser/loading/location.py | 8 +- aria/parser/loading/source.py | 2 +- aria/parser/loading/uri.py | 4 +- aria/parser/modeling/__init__.py | 4 + aria/parser/modeling/context.py | 4 +- aria/parser/presentation/__init__.py | 84 +++++++++- aria/parser/presentation/context.py | 8 +- aria/parser/presentation/presentation.py | 2 +- aria/parser/reading/__init__.py | 23 +++ aria/parser/reading/context.py | 2 + aria/parser/specification.py | 4 + aria/parser/validation/__init__.py | 4 + aria/parser/validation/context.py | 6 +- aria/storage/__init__.py | 23 +-- aria/storage/api.py | 78 ++++----- aria/storage/collection_instrumentation.py | 50 +++--- aria/storage/core.py | 57 ++----- aria/storage/exceptions.py | 4 +- aria/storage/filesystem_rapi.py | 53 +++--- aria/storage/sql_mapi.py | 71 ++++---- aria/utils/archive.py | 2 +- aria/utils/argparse.py | 2 +- aria/utils/caching.py | 2 +- aria/utils/collections.py | 17 +- aria/utils/console.py | 2 +- aria/utils/exceptions.py | 2 +- aria/utils/file.py | 7 +- aria/utils/formatting.py | 4 +- aria/utils/http.py | 18 +-- aria/utils/imports.py | 14 +- aria/utils/openclose.py | 4 +- aria/utils/plugin.py | 2 +- aria/utils/process.py | 2 +- aria/utils/specification.py | 2 +- aria/utils/threading.py | 45 +++--- aria/utils/type.py | 14 +- aria/utils/uris.py | 4 +- aria/utils/uuid.py | 17 +- aria/utils/validation.py | 8 +- aria/utils/versions.py | 15 +- docs/aria.cli.rst | 34 ++-- docs/aria.modeling.models.rst | 3 +- docs/aria.modeling.rst | 16 +- docs/aria.orchestrator.context.rst | 46 ++++++ ....orchestrator.execution_plugin.ctx_proxy.rst | 31 ++++ docs/aria.orchestrator.execution_plugin.rst | 39 ++++- docs/aria.orchestrator.execution_plugin.ssh.rst | 31 ++++ docs/aria.orchestrator.rst | 28 +++- docs/aria.orchestrator.workflows.api.rst | 31 ++++ docs/aria.orchestrator.workflows.builtin.rst | 57 +++++++ docs/aria.orchestrator.workflows.executor.rst | 46 ++++++ docs/aria.orchestrator.workflows.rst | 32 ++-- docs/aria.parser.consumption.rst | 42 +---- docs/aria.parser.loading.rst | 47 +----- docs/aria.parser.modeling.rst | 7 +- docs/aria.parser.presentation.rst | 47 +----- docs/aria.parser.reading.rst | 47 +----- docs/aria.parser.rst | 6 +- docs/aria.parser.validation.rst | 12 +- docs/aria.rst | 10 +- docs/aria.storage.rst | 14 +- docs/aria.utils.rst | 42 ++--- docs/aria_extension_tosca.rst | 30 ---- docs/aria_extension_tosca.simple_nfv_v1_0.rst | 20 +++ ...ria_extension_tosca.simple_v1_0.modeling.rst | 75 +++++++++ ...extension_tosca.simple_v1_0.presentation.rst | 40 +++++ docs/aria_extension_tosca.simple_v1_0.rst | 20 +++ docs/conf.py | 32 ++-- docs/index.rst | 12 +- docs/rest.rst | 20 +++ .../simple_nfv_v1_0/presenter.py | 4 +- .../simple_v1_0/__init__.py | 109 +++++++++++++ .../simple_v1_0/assignments.py | 44 ++--- .../simple_v1_0/definitions.py | 79 ++++----- .../aria_extension_tosca/simple_v1_0/filters.py | 8 +- .../aria_extension_tosca/simple_v1_0/misc.py | 56 +++++-- .../simple_v1_0/modeling/capabilities.py | 4 +- .../simple_v1_0/modeling/copy.py | 2 +- .../simple_v1_0/modeling/data_types.py | 10 +- .../simple_v1_0/modeling/functions.py | 18 +-- .../simple_v1_0/presentation/extensible.py | 2 +- .../presentation/field_validators.py | 40 ++--- .../simple_v1_0/presentation/types.py | 12 +- .../simple_v1_0/presenter.py | 4 +- .../simple_v1_0/templates.py | 96 +++++------ .../aria_extension_tosca/simple_v1_0/types.py | 98 +++++------ 152 files changed, 1971 insertions(+), 1295 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/logger.py ---------------------------------------------------------------------- diff --git a/aria/logger.py b/aria/logger.py index 3b01e48..f4f6ec9 100644 --- a/aria/logger.py +++ b/aria/logger.py @@ -42,7 +42,7 @@ class LoggerMixin(object): Provides logging functionality to a class. :ivar logger_name: logger name; default to the class name - :ivar logger_level: logger level; defaults to `logging.DEBUG` + :ivar logger_level: logger level; defaults to ``logging.DEBUG`` :ivar base_logger: child loggers are created from this; defaults to the root logger """ logger_name = None @@ -107,7 +107,6 @@ def create_console_log_handler(level=logging.DEBUG, formatter=None): """ :param level: :param formatter: - :return: """ console = logging.StreamHandler() console.setLevel(level) @@ -124,9 +123,9 @@ def create_sqla_log_handler(model, log_cls, execution_id, level=logging.DEBUG): class _DefaultConsoleFormat(logging.Formatter): """ - Info level log format: ``%(message)s`` + Info level log format: ``%(message)s``. - Every other log level is formatted: ``%(levelname)s: %(message)s`` + Every other log level is formatted: ``%(levelname)s: %(message)s``. """ def format(self, record): try: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/mixins.py ---------------------------------------------------------------------- diff --git a/aria/modeling/mixins.py b/aria/modeling/mixins.py index aafc1e9..883ff4a 100644 --- a/aria/modeling/mixins.py +++ b/aria/modeling/mixins.py @@ -50,8 +50,8 @@ class ModelMixin(object): Create a dict representation of the model. :param suppress_error: if set to ``True``, sets ``None`` to attributes that it's unable to - retrieve (e.g., if a relationship wasn't established yet, and so it's - impossible to access a property through it) + retrieve (e.g., if a relationship wasn't established yet, and so it's impossible to access + a property through it) """ res = dict() @@ -125,7 +125,7 @@ class InstanceModelMixin(ModelMixin): Mix-in for service instance models. All models support validation, diagnostic dumping, and representation as raw data (which can be - translated into JSON or YAML) via ``as_raw``. + translated into JSON or YAML) via :meth:`as_raw`. """ @property @@ -198,7 +198,7 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods): *All* parameters should have an owner model. - :raises exceptions.ValueError: if failed to find an owner, which signifies an abnormal, + :raises ~exceptions.ValueError: if failed to find an owner, which signifies an abnormal, orphaned parameter """ @@ -223,7 +223,7 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods): *All* parameters should have a container model. - :raises exceptions.ValueError: if failed to find a container model, which signifies an + :raises ~exceptions.ValueError: if failed to find a container model, which signifies an abnormal, orphaned parameter """ @@ -269,7 +269,7 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods): The :class:`~aria.modeling.models.Service` model containing this parameter, or ``None`` if not contained in a service. - :raises exceptions.ValueError: if failed to find a container model, which signifies an + :raises ~exceptions.ValueError: if failed to find a container model, which signifies an abnormal, orphaned parameter """ @@ -288,7 +288,7 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods): The :class:`~aria.modeling.models.ServiceTemplate` model containing this parameter, or ``None`` if not contained in a service template. - :raises exceptions.ValueError: if failed to find a container model, which signifies an + :raises ~exceptions.ValueError: if failed to find a container model, which signifies an abnormal, orphaned parameter """ @@ -349,10 +349,10 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods): cos01 specification <http://docs.oasis-open.org/tosca/TOSCA-Simple-Profile-YAML/v1.0/cos01 /TOSCA-Simple-Profile-YAML-v1.0-cos01.html#_Toc373867862>`__ - :param name: Parameter name + :param name: parameter name :type name: basestring - :param value: Parameter value - :param description: Description (optional) + :param value: parameter value + :param description: human-readable description (optional) :type description: basestring """ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/models.py ---------------------------------------------------------------------- diff --git a/aria/modeling/models.py b/aria/modeling/models.py index f2aa1ea..cf84fdb 100644 --- a/aria/modeling/models.py +++ b/aria/modeling/models.py @@ -14,7 +14,71 @@ # limitations under the License. """ -Models. +Data models. + +Service template models +----------------------- + +.. autosummary:: + :nosignatures: + + aria.modeling.models.ServiceTemplate + aria.modeling.models.NodeTemplate + aria.modeling.models.GroupTemplate + aria.modeling.models.PolicyTemplate + aria.modeling.models.SubstitutionTemplate + aria.modeling.models.SubstitutionTemplateMapping + aria.modeling.models.RequirementTemplate + aria.modeling.models.RelationshipTemplate + aria.modeling.models.CapabilityTemplate + aria.modeling.models.InterfaceTemplate + aria.modeling.models.OperationTemplate + aria.modeling.models.ArtifactTemplate + aria.modeling.models.PluginSpecification + +Service instance models +----------------------- + +.. autosummary:: + :nosignatures: + + aria.modeling.models.Service + aria.modeling.models.Node + aria.modeling.models.Group + aria.modeling.models.Policy + aria.modeling.models.Substitution + aria.modeling.models.SubstitutionMapping + aria.modeling.models.Relationship + aria.modeling.models.Capability + aria.modeling.models.Interface + aria.modeling.models.Operation + aria.modeling.models.Artifact + +Common models +------------- + +.. autosummary:: + :nosignatures: + + aria.modeling.models.Output + aria.modeling.models.Input + aria.modeling.models.Configuration + aria.modeling.models.Property + aria.modeling.models.Attribute + aria.modeling.models.Type + aria.modeling.models.Metadata + +Orchestration models +-------------------- + +.. autosummary:: + :nosignatures: + + aria.modeling.models.Execution + aria.modeling.models.Task + aria.modeling.models.Log + aria.modeling.models.Plugin + aria.modeling.models.Argument """ # pylint: disable=abstract-method @@ -31,7 +95,8 @@ from . import ( service_changes, service_common, orchestration, - mixins + mixins, + utils ) @@ -93,85 +158,70 @@ __all__ = ( ) -def _clean_init_doc(cls): - # 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 - return cls - - -def _fix_doc(cls): - # Use the last base class's docstring - cls.__doc__ = cls.__bases__[-1].__doc__ - return _clean_init_doc(cls) - - # region service template models -@_fix_doc [email protected]_doc class ServiceTemplate(aria_declarative_base, service_template.ServiceTemplateBase): name = Column(Text, index=True, unique=True) -@_fix_doc [email protected]_doc class NodeTemplate(aria_declarative_base, service_template.NodeTemplateBase): pass -@_fix_doc [email protected]_doc class GroupTemplate(aria_declarative_base, service_template.GroupTemplateBase): pass -@_fix_doc [email protected]_doc class PolicyTemplate(aria_declarative_base, service_template.PolicyTemplateBase): pass -@_fix_doc [email protected]_doc class SubstitutionTemplate(aria_declarative_base, service_template.SubstitutionTemplateBase): pass -@_fix_doc [email protected]_doc class SubstitutionTemplateMapping(aria_declarative_base, service_template.SubstitutionTemplateMappingBase): pass -@_fix_doc [email protected]_doc class RequirementTemplate(aria_declarative_base, service_template.RequirementTemplateBase): pass -@_fix_doc [email protected]_doc class RelationshipTemplate(aria_declarative_base, service_template.RelationshipTemplateBase): pass -@_fix_doc [email protected]_doc class CapabilityTemplate(aria_declarative_base, service_template.CapabilityTemplateBase): pass -@_fix_doc [email protected]_doc class InterfaceTemplate(aria_declarative_base, service_template.InterfaceTemplateBase): pass -@_fix_doc [email protected]_doc class OperationTemplate(aria_declarative_base, service_template.OperationTemplateBase): pass -@_fix_doc [email protected]_doc class ArtifactTemplate(aria_declarative_base, service_template.ArtifactTemplateBase): pass -@_fix_doc [email protected]_doc class PluginSpecification(aria_declarative_base, service_template.PluginSpecificationBase): pass @@ -180,57 +230,57 @@ class PluginSpecification(aria_declarative_base, service_template.PluginSpecific # region service instance models -@_fix_doc [email protected]_doc class Service(aria_declarative_base, service_instance.ServiceBase): name = Column(Text, index=True, unique=True) -@_fix_doc [email protected]_doc class Node(aria_declarative_base, service_instance.NodeBase): pass -@_fix_doc [email protected]_doc class Group(aria_declarative_base, service_instance.GroupBase): pass -@_fix_doc [email protected]_doc class Policy(aria_declarative_base, service_instance.PolicyBase): pass -@_fix_doc [email protected]_doc class Substitution(aria_declarative_base, service_instance.SubstitutionBase): pass -@_fix_doc [email protected]_doc class SubstitutionMapping(aria_declarative_base, service_instance.SubstitutionMappingBase): pass -@_fix_doc [email protected]_doc class Relationship(aria_declarative_base, service_instance.RelationshipBase): pass -@_fix_doc [email protected]_doc class Capability(aria_declarative_base, service_instance.CapabilityBase): pass -@_fix_doc [email protected]_doc class Interface(aria_declarative_base, service_instance.InterfaceBase): pass -@_fix_doc [email protected]_doc class Operation(aria_declarative_base, service_instance.OperationBase): pass -@_fix_doc [email protected]_doc class Artifact(aria_declarative_base, service_instance.ArtifactBase): pass @@ -239,17 +289,17 @@ class Artifact(aria_declarative_base, service_instance.ArtifactBase): # region service changes models -@_fix_doc [email protected]_doc class ServiceUpdate(aria_declarative_base, service_changes.ServiceUpdateBase): pass -@_fix_doc [email protected]_doc class ServiceUpdateStep(aria_declarative_base, service_changes.ServiceUpdateStepBase): pass -@_fix_doc [email protected]_doc class ServiceModification(aria_declarative_base, service_changes.ServiceModificationBase): pass @@ -258,37 +308,37 @@ class ServiceModification(aria_declarative_base, service_changes.ServiceModifica # region common service models -@_fix_doc [email protected]_doc class Input(aria_declarative_base, service_common.InputBase): pass -@_fix_doc [email protected]_doc class Configuration(aria_declarative_base, service_common.ConfigurationBase): pass -@_fix_doc [email protected]_doc class Output(aria_declarative_base, service_common.OutputBase): pass -@_fix_doc [email protected]_doc class Property(aria_declarative_base, service_common.PropertyBase): pass -@_fix_doc [email protected]_doc class Attribute(aria_declarative_base, service_common.AttributeBase): pass -@_fix_doc [email protected]_doc class Type(aria_declarative_base, service_common.TypeBase): pass -@_fix_doc [email protected]_doc class Metadata(aria_declarative_base, service_common.MetadataBase): pass @@ -297,27 +347,27 @@ class Metadata(aria_declarative_base, service_common.MetadataBase): # region orchestration models -@_fix_doc [email protected]_doc class Execution(aria_declarative_base, orchestration.ExecutionBase): pass -@_fix_doc [email protected]_doc class Plugin(aria_declarative_base, orchestration.PluginBase): pass -@_fix_doc [email protected]_doc class Task(aria_declarative_base, orchestration.TaskBase): pass -@_fix_doc [email protected]_doc class Log(aria_declarative_base, orchestration.LogBase): pass -@_fix_doc [email protected]_doc class Argument(aria_declarative_base, orchestration.ArgumentBase): pass http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/orchestration.py ---------------------------------------------------------------------- diff --git a/aria/modeling/orchestration.py b/aria/modeling/orchestration.py index 1c94966..a44a42d 100644 --- a/aria/modeling/orchestration.py +++ b/aria/modeling/orchestration.py @@ -31,7 +31,6 @@ from sqlalchemy import ( Float, orm, PickleType) -from sqlalchemy.ext.associationproxy import association_proxy from sqlalchemy.ext.declarative import declared_attr from ..orchestrator.exceptions import (TaskAbortException, TaskRetryException) @@ -117,18 +116,15 @@ class ExecutionBase(mixins.ModelMixin): @declared_attr def service_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('service', cls.name_column_name()) + return relationship.association_proxy('service', cls.name_column_name()) @declared_attr def service_template(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('service', 'service_template') + return relationship.association_proxy('service', 'service_template') @declared_attr def service_template_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('service', 'service_template_name') + return relationship.association_proxy('service', 'service_template_name') # endregion @@ -325,18 +321,15 @@ class TaskBase(mixins.ModelMixin): @declared_attr def node_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('node', cls.name_column_name()) + return relationship.association_proxy('node', cls.name_column_name()) @declared_attr def relationship_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('relationship', cls.name_column_name()) + return relationship.association_proxy('relationship', cls.name_column_name()) @declared_attr def execution_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('execution', cls.name_column_name()) + return relationship.association_proxy('execution', cls.name_column_name()) # endregion http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/relationship.py ---------------------------------------------------------------------- diff --git a/aria/modeling/relationship.py b/aria/modeling/relationship.py index ce0b055..55060c9 100644 --- a/aria/modeling/relationship.py +++ b/aria/modeling/relationship.py @@ -21,6 +21,7 @@ ARIA modeling relationship module from sqlalchemy.orm import relationship, backref from sqlalchemy.orm.collections import attribute_mapped_collection +from sqlalchemy.ext.associationproxy import association_proxy as original_association_proxy from sqlalchemy import ( Column, ForeignKey, @@ -48,9 +49,9 @@ def foreign_key(other_table, nullable=False): *This utility method should only be used during class creation.* - :param other_table: Other table name + :param other_table: other table name :type other_table: basestring - :param nullable: True to allow null values (meaning that there is no relationship) + :param nullable: ``True`` to allow null values (meaning that there is no relationship) :type nullable: bool """ @@ -68,9 +69,9 @@ def one_to_one_self(model_class, fk): *This utility method should only be used during class creation.* - :param model_class: The class in which this relationship will be declared + :param model_class: class in which this relationship will be declared :type model_class: type - :param fk: Foreign key name + :param fk: foreign key name :type fk: basestring """ @@ -104,12 +105,12 @@ def one_to_many_self(model_class, fk, dict_key=None): *This utility method should only be used during class creation.* - :param model_class: The class in which this relationship will be declared + :param model_class: class in which this relationship will be declared :type model_class: type :param fk: Foreign key name :type fk: basestring - :param dict_key: If set the value will be a dict with this key as the dict key; otherwise will - be a list + :param dict_key: if set the value will be a dict with this key as the dict key; otherwise will + be a list :type dict_key: basestring """ return _relationship( @@ -139,17 +140,17 @@ def one_to_one(model_class, *This utility method should only be used during class creation.* - :param model_class: The class in which this relationship will be declared + :param model_class: class in which this relationship will be declared :type model_class: type - :param other_table: Other table name + :param other_table: other table name :type other_table: basestring - :param fk: Foreign key name at our table (no need specify if there's no ambiguity) + :param fk: foreign key name at our table (no need specify if there's no ambiguity) :type fk: basestring - :param other_fk: Foreign key name at the other table (no need specify if there's no ambiguity) + :param other_fk: foreign key name at the other table (no need specify if there's no ambiguity) :type other_fk: basestring - :param back_populates: Override name of matching many-to-many property at other table; set to - false to disable - :type back_populates: basestring|bool + :param back_populates: override name of matching many-to-many property at other table; set to + ``False`` to disable + :type back_populates: basestring or bool """ backref_kwargs = None if back_populates is not NO_BACK_POP: @@ -183,18 +184,18 @@ def one_to_many(model_class, *This utility method should only be used during class creation.* - :param model_class: The class in which this relationship will be declared + :param model_class: class in which this relationship will be declared :type model_class: type - :param child_table: Child table name + :param child_table: child table name :type child_table: basestring - :param child_fk: Foreign key name at the child table (no need specify if there's no ambiguity) + :param child_fk: foreign key name at the child table (no need specify if there's no ambiguity) :type child_fk: basestring - :param dict_key: If set the value will be a dict with this key as the dict key; otherwise will - be a list + :param dict_key: if set the value will be a dict with this key as the dict key; otherwise will + be a list :type dict_key: basestring - :param back_populates: Override name of matching many-to-one property at child table; set to - false to disable - :type back_populates: basestring|bool + :param back_populates: override name of matching many-to-one property at child table; set to + ``false`` to disable + :type back_populates: basestring or bool """ rel_kwargs = rel_kwargs or {} rel_kwargs.setdefault('cascade', 'all') @@ -228,15 +229,15 @@ def many_to_one(model_class, *This utility method should only be used during class creation.* - :param model_class: The class in which this relationship will be declared + :param model_class: class in which this relationship will be declared :type model_class: type - :param parent_table: Parent table name + :param parent_table: parent table name :type parent_table: basestring - :param fk: Foreign key name at our table (no need specify if there's no ambiguity) + :param fk: foreign key name at our table (no need specify if there's no ambiguity) :type fk: basestring - :param back_populates: Override name of matching one-to-many property at parent table; set to - false to disable - :type back_populates: basestring|bool + :param back_populates: override name of matching one-to-many property at parent table; set to + ``False`` to disable + :type back_populates: basestring or bool """ if back_populates is None: back_populates = formatting.pluralize(model_class.__tablename__) @@ -267,18 +268,18 @@ def many_to_many(model_class, *This utility method should only be used during class creation.* - :param model_class: The class in which this relationship will be declared + :param model_class: class in which this relationship will be declared :type model_class: type - :param other_table: Parent table name + :param other_table: parent table name :type other_table: basestring - :param prefix: Optional prefix for extra table name as well as for ``other_property`` + :param prefix: optional prefix for extra table name as well as for ``other_property`` :type prefix: basestring - :param dict_key: If set the value will be a dict with this key as the dict key; otherwise will - be a list + :param dict_key: if set the value will be a dict with this key as the dict key; otherwise will + be a list :type dict_key: basestring - :param other_property: Override name of matching many-to-many property at other table; set to - false to disable - :type other_property: basestring|bool + :param other_property: override name of matching many-to-many property at other table; set to + ``False`` to disable + :type other_property: basestring or bool """ this_table = model_class.__tablename__ @@ -313,6 +314,21 @@ def many_to_many(model_class, ) +def association_proxy(*args, **kwargs): + if 'type' in kwargs: + type_ = kwargs.get('type') + del kwargs['type'] + else: + type_ = ':obj:`basestring`' + proxy = original_association_proxy(*args, **kwargs) + proxy.__doc__ = """ + Internal. For use in SQLAlchemy queries. + + :type: {0} + """.format(type_) + return proxy + + def _relationship(model_class, other_table_name, back_populates=None, http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/service_changes.py ---------------------------------------------------------------------- diff --git a/aria/modeling/service_changes.py b/aria/modeling/service_changes.py index b536443..061262a 100644 --- a/aria/modeling/service_changes.py +++ b/aria/modeling/service_changes.py @@ -27,7 +27,6 @@ from sqlalchemy import ( DateTime, Enum, ) -from sqlalchemy.ext.associationproxy import association_proxy from sqlalchemy.ext.declarative import declared_attr from .types import (List, Dict) @@ -56,13 +55,11 @@ class ServiceUpdateBase(ModelMixin): @declared_attr def execution_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('execution', cls.name_column_name()) + return relationship.association_proxy('execution', cls.name_column_name()) @declared_attr def service_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('service', cls.name_column_name()) + return relationship.association_proxy('service', cls.name_column_name()) # endregion @@ -144,8 +141,7 @@ class ServiceUpdateStepBase(ModelMixin): @declared_attr def service_update_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('service_update', cls.name_column_name()) + return relationship.association_proxy('service_update', cls.name_column_name()) # endregion @@ -228,8 +224,7 @@ class ServiceModificationBase(ModelMixin): @declared_attr def service_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('service', cls.name_column_name()) + return relationship.association_proxy('service', cls.name_column_name()) # endregion http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/service_instance.py ---------------------------------------------------------------------- diff --git a/aria/modeling/service_instance.py b/aria/modeling/service_instance.py index fa79091..de12ea2 100644 --- a/aria/modeling/service_instance.py +++ b/aria/modeling/service_instance.py @@ -27,7 +27,6 @@ from sqlalchemy import ( Boolean ) from sqlalchemy import DateTime -from sqlalchemy.ext.associationproxy import association_proxy from sqlalchemy.ext.declarative import declared_attr from sqlalchemy.ext.orderinglist import ordering_list @@ -63,8 +62,7 @@ class ServiceBase(InstanceModelMixin): @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', type=':obj:`basestring`') # endregion @@ -404,13 +402,11 @@ class NodeBase(InstanceModelMixin): @declared_attr def service_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('service', 'name') + return relationship.association_proxy('service', 'name', type=':obj:`basestring`') @declared_attr def node_template_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('node_template', 'name') + return relationship.association_proxy('node_template', 'name', type=':obj:`basestring`') # endregion @@ -1323,13 +1319,11 @@ class RelationshipBase(InstanceModelMixin): @declared_attr def source_node_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('source_node', 'name') + return relationship.association_proxy('source_node', 'name') @declared_attr def target_node_name(cls): - """Required for use by SQLAlchemy queries""" - return association_proxy('target_node', 'name') + return relationship.association_proxy('target_node', 'name') # endregion http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/service_template.py ---------------------------------------------------------------------- diff --git a/aria/modeling/service_template.py b/aria/modeling/service_template.py index 70ec831..c722400 100644 --- a/aria/modeling/service_template.py +++ b/aria/modeling/service_template.py @@ -32,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 @@ -473,13 +472,11 @@ class NodeTemplateBase(TemplateModelMixin): @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 http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/modeling/utils.py ---------------------------------------------------------------------- diff --git a/aria/modeling/utils.py b/aria/modeling/utils.py index a60a7a5..5193cd9 100644 --- a/aria/modeling/utils.py +++ b/aria/modeling/utils.py @@ -76,13 +76,12 @@ def merge_parameter_values(parameter_values, declared_parameters, model_cls): :type declared_parameters: {:obj:`basestring`: :class:`~aria.modeling.models.Parameter`} :return: the merged 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`` + :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 {} @@ -215,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/5be27b0c/aria/orchestrator/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/__init__.py b/aria/orchestrator/__init__.py index 1b9f25b..24fee9e 100644 --- a/aria/orchestrator/__init__.py +++ b/aria/orchestrator/__init__.py @@ -14,7 +14,7 @@ # limitations under the License. """ -ARIA orchestrator package +Orchestrator package. """ from .decorators import ( http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/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/5be27b0c/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/5be27b0c/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 http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/context/operation.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/context/operation.py b/aria/orchestrator/context/operation.py index d43b847..7d5f40c 100644 --- a/aria/orchestrator/context/operation.py +++ b/aria/orchestrator/context/operation.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Workflow and operation contexts +Operation contexts. """ import threading @@ -27,7 +27,7 @@ from . import common class BaseOperationContext(common.BaseContext): """ - Context object used during operation creation and execution + Base class for contexts used during operation creation and execution. """ def __init__(self, task_id, actor_id, **kwargs): @@ -116,7 +116,7 @@ class BaseOperationContext(common.BaseContext): class NodeOperationContext(BaseOperationContext): """ - Context for node based operations. + Context for node operations. """ @property @@ -138,7 +138,7 @@ class NodeOperationContext(BaseOperationContext): class RelationshipOperationContext(BaseOperationContext): """ - Context for relationship based operations. + Context for relationship operations. """ @property http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/context/toolbelt.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/context/toolbelt.py b/aria/orchestrator/context/toolbelt.py index b5a54a9..a2e1122 100644 --- a/aria/orchestrator/context/toolbelt.py +++ b/aria/orchestrator/context/toolbelt.py @@ -12,8 +12,9 @@ # 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. + """ -Provides with different tools for operations. +Tools for operations. """ from . import operation @@ -21,7 +22,7 @@ from . import operation class NodeToolBelt(object): """ - Node operation related tool belt + Node operation tool belt. """ def __init__(self, operation_context): self._op_context = operation_context @@ -38,7 +39,7 @@ class NodeToolBelt(object): class RelationshipToolBelt(object): """ - Relationship operation related tool belt + Relationship operation tool belt. """ def __init__(self, operation_context): self._op_context = operation_context @@ -46,9 +47,9 @@ class RelationshipToolBelt(object): def toolbelt(operation_context): """ - Get a toolbelt according to the current operation executor + Get a toolbelt from to the current operation executor. + :param operation_context: - :return: """ if isinstance(operation_context, operation.NodeOperationContext): return NodeToolBelt(operation_context) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/context/workflow.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/context/workflow.py b/aria/orchestrator/context/workflow.py index adcd635..670ff03 100644 --- a/aria/orchestrator/context/workflow.py +++ b/aria/orchestrator/context/workflow.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Workflow and operation contexts +Workflow context. """ import threading @@ -28,7 +28,7 @@ from .common import BaseContext class WorkflowContext(BaseContext): """ - Context object used during workflow creation and execution + Context used during workflow creation and execution. """ def __init__(self, workflow_name, @@ -59,21 +59,21 @@ class WorkflowContext(BaseContext): @property def execution(self): """ - The execution model + Execution model. """ return self.model.execution.get(self._execution_id) @execution.setter def execution(self, value): """ - Store the execution in the model storage + Stores the execution in the storage model API ("MAPI"). """ self.model.execution.put(value) @property def node_templates(self): """ - Iterator over nodes + Iterates over nodes templates. """ key = 'service_{0}'.format(self.model.node_template.model_cls.name_column_name()) @@ -86,7 +86,7 @@ class WorkflowContext(BaseContext): @property def nodes(self): """ - Iterator over node instances + Iterates over nodes. """ key = 'service_{0}'.format(self.model.node.model_cls.name_column_name()) return self.model.node.iter( @@ -121,7 +121,7 @@ class WorkflowContext(BaseContext): class _CurrentContext(threading.local): """ - Provides thread-level context, which sugarcoats the task mapi. + Provides a thread-level context, with sugar for the task MAPI. """ def __init__(self): @@ -133,9 +133,7 @@ class _CurrentContext(threading.local): def get(self): """ - Retrieves the current workflow context - :return: the workflow context - :rtype: WorkflowContext + Retrieves the current workflow context. """ if self._workflow_context is not None: return self._workflow_context @@ -144,9 +142,7 @@ class _CurrentContext(threading.local): @contextmanager def push(self, workflow_context): """ - Switches the current context to the provided context - :param workflow_context: the context to switch to. - :yields: the current context + Switches the current context to the provided context. """ prev_workflow_context = self._workflow_context self._set(workflow_context) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/decorators.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/decorators.py b/aria/orchestrator/decorators.py index 09a2167..4b163d6 100644 --- a/aria/orchestrator/decorators.py +++ b/aria/orchestrator/decorators.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Workflow and operation decorators +Workflow and operation decorators. """ from functools import partial, wraps http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/events.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/events.py b/aria/orchestrator/events.py index aa1b5bc..ef84e5d 100644 --- a/aria/orchestrator/events.py +++ b/aria/orchestrator/events.py @@ -14,10 +14,7 @@ # limitations under the License. """ -ARIA's events Sub-Package -Path: aria.events - -Events package provides events mechanism for different executions in aria. +Orchestrator events. """ from blinker import signal http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/exceptions.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/exceptions.py b/aria/orchestrator/exceptions.py index 71b6401..384458f 100644 --- a/aria/orchestrator/exceptions.py +++ b/aria/orchestrator/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. + """ -Orchestrator based exceptions +Orchestrator exceptions. """ + from aria.exceptions import AriaError http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/__init__.py b/aria/orchestrator/execution_plugin/__init__.py index 3624264..d15de99 100644 --- a/aria/orchestrator/execution_plugin/__init__.py +++ b/aria/orchestrator/execution_plugin/__init__.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Execution plugin package. +""" + from contextlib import contextmanager from . import instantiation http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/common.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/common.py b/aria/orchestrator/execution_plugin/common.py index 32e4575..ce6746c 100644 --- a/aria/orchestrator/execution_plugin/common.py +++ b/aria/orchestrator/execution_plugin/common.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Execution plugin utilities. +""" + import json import os import tempfile @@ -52,21 +56,23 @@ def download_script(ctx, script_path): def create_process_config(script_path, process, operation_kwargs, quote_json_env_vars=False): """ - update a process with it's environment variables, and return it. + Updates a process with its environment variables, and return it. + + Gets a dict representing a process and a dict representing the environment variables. Converts + each environment variable to a format of:: + + <string representing the name of the variable>: + <json formatted string representing the value of the variable>. - Get a dict representing a process and a dict representing the environment - variables. Convert each environment variable to a format of - <string representing the name of the variable> : - <json formatted string representing the value of the variable>. - Finally, update the process with the newly formatted environment variables, - and return the process. + Finally, updates the process with the newly formatted environment variables, and return the + process. - :param process: a dict representing a process + :param process: dict representing a process :type process: dict - :param operation_kwargs: a dict representing environment variables that - should exist in the process' running environment. + :param operation_kwargs: dict representing environment variables that should exist in the + process's running environment. :type operation_kwargs: dict - :return: the process updated with its environment variables. + :return: process updated with its environment variables :rtype: dict """ process = process or {} http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/constants.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/constants.py b/aria/orchestrator/execution_plugin/constants.py index 0b54dbe..8082e95 100644 --- a/aria/orchestrator/execution_plugin/constants.py +++ b/aria/orchestrator/execution_plugin/constants.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Execution plugin constants. +""" + from . import exceptions # related to local http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py b/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py index 7571c15..46c8cf1 100644 --- a/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py +++ b/aria/orchestrator/execution_plugin/ctx_proxy/__init__.py @@ -13,4 +13,8 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +``ctx`` proxy. +""" + from . import server, client http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ctx_proxy/client.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/ctx_proxy/client.py b/aria/orchestrator/execution_plugin/ctx_proxy/client.py index f7f56aa..1310c21 100644 --- a/aria/orchestrator/execution_plugin/ctx_proxy/client.py +++ b/aria/orchestrator/execution_plugin/ctx_proxy/client.py @@ -14,6 +14,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +``ctx`` proxy client implementation. +""" + import argparse import json import os http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ctx_proxy/server.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/ctx_proxy/server.py b/aria/orchestrator/execution_plugin/ctx_proxy/server.py index 50d4c3a..0a2a606 100644 --- a/aria/orchestrator/execution_plugin/ctx_proxy/server.py +++ b/aria/orchestrator/execution_plugin/ctx_proxy/server.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +``ctx`` proxy server implementation. +""" + import collections import json import re http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/environment_globals.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/environment_globals.py b/aria/orchestrator/execution_plugin/environment_globals.py index 27311f0..6dec293 100644 --- a/aria/orchestrator/execution_plugin/environment_globals.py +++ b/aria/orchestrator/execution_plugin/environment_globals.py @@ -13,41 +13,38 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Utilities for managing globals for the environment. +""" def create_initial_globals(path): - """ emulates a `globals()` call in a freshly loaded module - - The implementation of this function is likely to raise a couple of - questions. If you read the implementation and nothing bothered you, feel - free to skip the rest of this docstring. - - First, why is this function in its own module and not, say, in the same - module of the other environment-related functions? - Second, why is it implemented in such a way that copies the globals, then - deletes the item that represents this function, and then changes some - other entries? - - Well, these two questions can be answered with one (elaborate) explanation. - If this function was in the same module with the other environment-related - functions, then we would have had to delete more items in globals than just - `create_initial_globals`. That is because all of the other function names - would also be in globals, and since there is no built-in mechanism that - return the name of the user-defined objects, this approach is quite an - overkill. - - - But why do we rely on the copy-existing-globals-and-delete-entries - method, when it seems to force us to put `create_initial_globals` in its - own file? - - Well, because there is no easier method of creating globals of a newly - loaded module. - - - How about hard coding a 'global' dict? It seems that there are very few - entries: __doc__, __file__, __name__, __package__ (but don't forget - __builtins__). - - That would be coupling our implementation to a specific `globals` - implementation. What if `globals` were to change? + """ + Emulates a ``globals()`` call in a freshly loaded module. + + The implementation of this function is likely to raise a couple of questions. If you read the + implementation and nothing bothered you, feel free to skip the rest of this docstring. + + First, why is this function in its own module and not, say, in the same module of the other + environment-related functions? Second, why is it implemented in such a way that copies the + globals, then deletes the item that represents this function, and then changes some other + entries? + + Well, these two questions can be answered with one (elaborate) explanation. If this function was + in the same module with the other environment-related functions, then we would have had to + delete more items in globals than just ``create_initial_globals``. That is because all of the + other function names would also be in globals, and since there is no built-in mechanism that + return the name of the user-defined objects, this approach is quite an overkill. + + *But why do we rely on the copy-existing-globals-and-delete-entries method, when it seems to + force us to put ``create_initial_globals`` in its own file?* + + Well, because there is no easier method of creating globals of a newly loaded module. + + *How about hard coding a ``globals`` dict? It seems that there are very few entries: + ``__doc__``, ``__file__``, ``__name__``, ``__package__`` (but don't forget ``__builtins__``).* + + That would be coupling our implementation to a specific ``globals`` implementation. What if + ``globals`` were to change? """ copied_globals = globals().copy() copied_globals.update({ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/exceptions.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/exceptions.py b/aria/orchestrator/execution_plugin/exceptions.py index 4641c80..f201fae 100644 --- a/aria/orchestrator/execution_plugin/exceptions.py +++ b/aria/orchestrator/execution_plugin/exceptions.py @@ -13,9 +13,14 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Execution plugin exceptions. +""" class ProcessException(Exception): - """Raised when local scripts and remote ssh commands fail""" + """ + Raised when local scripts and remote SSH commands fail. + """ def __init__(self, stderr=None, stdout=None, command=None, exit_code=None): super(ProcessException, self).__init__(stderr) @@ -26,11 +31,15 @@ class ProcessException(Exception): class TaskException(Exception): - """Raised when remote ssh scripts fail""" + """ + Raised when remote ssh scripts fail. + """ class ScriptException(Exception): - """Used by the ctx proxy server when task.retry or task.abort are called by scripts""" + """ + Used by the ``ctx`` proxy server when task.retry or task.abort are called by scripts. + """ def __init__(self, message=None, retry=None, retry_interval=None): super(ScriptException, self).__init__(message) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/instantiation.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/instantiation.py b/aria/orchestrator/execution_plugin/instantiation.py index b067e8c..f55aa50 100644 --- a/aria/orchestrator/execution_plugin/instantiation.py +++ b/aria/orchestrator/execution_plugin/instantiation.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Instantiation of :class:`~aria.modeling.models.Operation` models. +""" + # TODO: this module will eventually be moved to a new "aria.instantiation" package from ...utils.type import full_type_name http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/local.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/local.py b/aria/orchestrator/execution_plugin/local.py index 121e582..04b9ecd 100644 --- a/aria/orchestrator/execution_plugin/local.py +++ b/aria/orchestrator/execution_plugin/local.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Local execution of operations. +""" + import os import subprocess import threading http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/operations.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/operations.py b/aria/orchestrator/execution_plugin/operations.py index 0bc8083..e8de545 100644 --- a/aria/orchestrator/execution_plugin/operations.py +++ b/aria/orchestrator/execution_plugin/operations.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Entry point functions. +""" + from aria.orchestrator import operation from . import local as local_operations http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ssh/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/ssh/__init__.py b/aria/orchestrator/execution_plugin/ssh/__init__.py index ae1e83e..474deef 100644 --- a/aria/orchestrator/execution_plugin/ssh/__init__.py +++ b/aria/orchestrator/execution_plugin/ssh/__init__.py @@ -12,3 +12,7 @@ # 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. + +""" +Remote execution of operations over SSH. +""" http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/execution_plugin/ssh/operations.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/execution_plugin/ssh/operations.py b/aria/orchestrator/execution_plugin/ssh/operations.py index 7147a30..c40e783 100644 --- a/aria/orchestrator/execution_plugin/ssh/operations.py +++ b/aria/orchestrator/execution_plugin/ssh/operations.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Utilities for running commands remotely over SSH. +""" + import os import random import string http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/plugin.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/plugin.py b/aria/orchestrator/plugin.py index 8fbcf5a..756a28e 100644 --- a/aria/orchestrator/plugin.py +++ b/aria/orchestrator/plugin.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Plugin management. +""" + import os import tempfile import subprocess @@ -32,7 +36,7 @@ class PluginManager(object): def __init__(self, model, plugins_dir): """ - :param plugins_dir: Root directory to install plugins in. + :param plugins_dir: root directory in which to install plugins """ self._model = model self._plugins_dir = plugins_dir @@ -72,10 +76,13 @@ class PluginManager(object): def load_plugin(self, plugin, env=None): """ Load the plugin into an environment. + Loading the plugin means the plugin's code and binaries paths will be appended to the - environment's PATH and PYTHONPATH, thereby allowing usage of the plugin. - :param plugin: The plugin to load - :param env: The environment to load the plugin into; If `None`, os.environ will be used. + environment's ``PATH`` and ``PYTHONPATH``, thereby allowing usage of the plugin. + + :param plugin: plugin to load + :param env: environment to load the plugin into; If ``None``, :obj:`os.environ` will be + used """ env = env or os.environ plugin_dir = self.get_plugin_dir(plugin) @@ -106,9 +113,10 @@ class PluginManager(object): @staticmethod def validate_plugin(source): """ - validate a plugin archive. - A valid plugin is a wagon (http://github.com/cloudify-cosmo/wagon) - in the zip format (suffix may also be .wgn). + Validate a plugin archive. + + A valid plugin is a `wagon <http://github.com/cloudify-cosmo/wagon>`__ in the zip format + (suffix may also be ``.wgn``). """ if not zipfile.is_zipfile(source): raise exceptions.InvalidPluginError( http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflow_runner.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflow_runner.py b/aria/orchestrator/workflow_runner.py index 3ccb1ee..f602636 100644 --- a/aria/orchestrator/workflow_runner.py +++ b/aria/orchestrator/workflow_runner.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Workflow runner +Running workflows. """ import os @@ -44,15 +44,16 @@ class WorkflowRunner(object): """ Manages a single workflow execution on a given service. - :param workflow_name: Workflow name - :param service_id: Service ID - :param inputs: A key-value dict of inputs for the execution - :param model_storage: Model storage - :param resource_storage: Resource storage - :param plugin_manager: Plugin manager - :param executor: Executor for tasks. Defaults to a ProcessExecutor instance. - :param task_max_attempts: Maximum attempts of repeating each failing task - :param task_retry_interval: Retry interval in between retry attempts of a failing task + :param workflow_name: workflow name + :param service_id: service ID + :param inputs: key-value dict of inputs for the execution + :param model_storage: model storage API ("MAPI") + :param resource_storage: resource storage API ("RAPI") + :param plugin_manager: plugin manager + :param executor: executor for tasks; defaults to a + :class:`~aria.orchestrator.workflows.executor.process.ProcessExecutor` instance + :param task_max_attempts: maximum attempts of repeating each failing task + :param task_retry_interval: retry interval between retry attempts of a failing task """ if not (execution_id or (workflow_name and service_id)): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/__init__.py b/aria/orchestrator/workflows/__init__.py index e0c979a..1f6c368 100644 --- a/aria/orchestrator/workflows/__init__.py +++ b/aria/orchestrator/workflows/__init__.py @@ -13,5 +13,9 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Workflows package. +""" + # Import required so that logging signals are registered from . import events_logging http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/api/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/api/__init__.py b/aria/orchestrator/workflows/api/__init__.py index a3a17ee..587eee3 100644 --- a/aria/orchestrator/workflows/api/__init__.py +++ b/aria/orchestrator/workflows/api/__init__.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Provides API for building tasks +Workflow API. """ from . import task, task_graph http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/api/task.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/api/task.py b/aria/orchestrator/workflows/api/task.py index c2600b0..4c518fc 100644 --- a/aria/orchestrator/workflows/api/task.py +++ b/aria/orchestrator/workflows/api/task.py @@ -26,7 +26,7 @@ from .. import exceptions class BaseTask(object): """ - Abstract task graph task + Base class for tasks. """ def __init__(self, ctx=None, **kwargs): @@ -39,44 +39,43 @@ class BaseTask(object): @property def id(self): """ - uuid4 generated id - :return: + UUID4 ID. """ return self._id @property def workflow_context(self): """ - the context of the current workflow - :return: + Context of the current workflow. """ return self._workflow_context class OperationTask(BaseTask): """ - Represents an operation task in the task graph. + Executes an operation. :ivar name: formatted name (includes actor type, actor name, and interface/operation names) :vartype name: basestring :ivar actor: node or relationship - :vartype actor: :class:`Node`|:class:`Relationship` + :vartype actor: :class:`~aria.modeling.models.Node` or + :class:`~aria.modeling.models.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:`Plugin` + :vartype plugin: :class:`~aria.modeling.models.Plugin` :ivar function: path to Python function :vartype function: basestring :ivar arguments: arguments to send to Python function - :vartype arguments: {::obj:`basestring`: :class:`Argument`} + :vartype arguments: {:obj:`basestring`: :class:`~aria.modeling.models.Argument`} :ivar ignore_failure: whether to ignore failures :vartype ignore_failure: bool :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 + :vartype retry_interval: float """ NAME_FORMAT = '{interface}:{operation}@{type}:{name}' @@ -91,7 +90,8 @@ class OperationTask(BaseTask): retry_interval=None): """ :param actor: node or relationship - :type actor: :class:`Node`|:class:`Relationship` + :type actor: :class:`~aria.modeling.models.Node` or + :class:`~aria.modeling.models.Relationship` :param interface_name: interface name on actor :type interface_name: basestring :param operation_name: operation name on interface @@ -103,9 +103,9 @@ class OperationTask(BaseTask): :param max_attempts: override maximum number of attempts allowed in case of failure :type max_attempts: int :param retry_interval: override interval between retries (in seconds) - :type retry_interval: int - :raises aria.orchestrator.workflows.exceptions.OperationNotFoundException: if - ``interface_name`` and ``operation_name`` to not refer to an operation on the actor + :type retry_interval: float + :raises ~aria.orchestrator.workflows.exceptions.OperationNotFoundException: if + ``interface_name`` and ``operation_name`` do not refer to an operation on the actor """ # Creating OperationTask directly should raise an error when there is no @@ -160,14 +160,13 @@ class StubTask(BaseTask): class WorkflowTask(BaseTask): """ - Represents a workflow task in the task graph + Executes a complete workflow. """ def __init__(self, workflow_func, **kwargs): """ - Creates a workflow based task using the workflow_func provided, and its kwargs - :param workflow_func: the function to run - :param kwargs: the kwargs that would be passed to the workflow_func + :param workflow_func: function to run + :param kwargs: kwargs that would be passed to the workflow_func """ super(WorkflowTask, self).__init__(**kwargs) kwargs['ctx'] = self.workflow_context @@ -176,8 +175,7 @@ class WorkflowTask(BaseTask): @property def graph(self): """ - The graph constructed by the sub workflow - :return: + Graph constructed by the sub workflow. """ return self._graph @@ -190,13 +188,14 @@ class WorkflowTask(BaseTask): def create_task(actor, interface_name, operation_name, **kwargs): """ - This helper function enables safe creation of OperationTask, if the supplied interface or - operation do not exist, None is returned. - :param actor: the actor for this task - :param interface_name: the name of the interface - :param operation_name: the name of the operation - :param kwargs: any additional kwargs to be passed to the task OperationTask - :return: and OperationTask or None (if the interface/operation does not exists) + Helper function that enables safe creation of :class:`OperationTask`. If the supplied interface + or operation do not exist, ``None`` is returned. + + :param actor: actor for this task + :param interface_name: name of the interface + :param operation_name: name of the operation + :param kwargs: any additional kwargs to be passed to the OperationTask + :return: OperationTask or None (if the interface/operation does not exists) """ try: return OperationTask( @@ -212,13 +211,13 @@ def create_task(actor, interface_name, operation_name, **kwargs): def create_relationships_tasks( node, interface_name, source_operation_name=None, target_operation_name=None, **kwargs): """ - Creates a relationship task (source and target) for all of a node_instance relationships. - :param basestring source_operation_name: the relationship operation name. - :param basestring interface_name: the name of the interface. + Creates a relationship task (source and target) for all of a node relationships. + + :param basestring source_operation_name: relationship operation name + :param basestring interface_name: name of the interface :param source_operation_name: :param target_operation_name: - :param NodeInstance node: the source_node - :return: + :param node: source node """ sub_tasks = [] for relationship in node.outbound_relationships: @@ -235,12 +234,11 @@ def create_relationships_tasks( def create_relationship_tasks(relationship, interface_name, source_operation_name=None, target_operation_name=None, **kwargs): """ - Creates a relationship task source and target. - :param Relationship relationship: the relationship instance itself + Creates a relationship task (source and target). + + :param relationship: relationship instance itself :param source_operation_name: :param target_operation_name: - - :return: """ operations = [] if source_operation_name:
