You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ariatosca.apache.org by ra...@apache.org on 2017/06/29 12:57:34 UTC
[4/8] incubator-ariatosca git commit: ARIA-286 Sphinx documentation
for code and CLI
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/aria/orchestrator/context/workflow.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/context/workflow.py b/aria/orchestrator/context/workflow.py
index 18334f3..738d2fd 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
@@ -26,7 +26,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,
@@ -57,21 +57,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())
@@ -84,7 +84,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(
@@ -102,7 +102,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):
@@ -114,9 +114,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
@@ -125,9 +123,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/2ed2e1c2/aria/orchestrator/decorators.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/decorators.py b/aria/orchestrator/decorators.py
index 389bfb8..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
@@ -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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/aria/orchestrator/workflow_runner.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflow_runner.py b/aria/orchestrator/workflow_runner.py
index 3d58386..df1725f 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/2ed2e1c2/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/2ed2e1c2/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/2ed2e1c2/aria/orchestrator/workflows/api/task.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/api/task.py b/aria/orchestrator/workflows/api/task.py
index f7d2c66..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:`aria.modeling.models.Node`|:class:`aria.modeling.models.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:`aria.modeling.models.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: {basestring, :class:`aria.modeling.models.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,21 +90,22 @@ 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:`~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
: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
: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:
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/api/task_graph.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/api/task_graph.py b/aria/orchestrator/workflows/api/task_graph.py
index 9f0d13b..900a0d1 100644
--- a/aria/orchestrator/workflows/api/task_graph.py
+++ b/aria/orchestrator/workflows/api/task_graph.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Task graph. Used by users to build workflows
+Task graph.
"""
from collections import Iterable
@@ -27,7 +27,7 @@ from . import task as api_task
class TaskNotInGraphError(Exception):
"""
- An error representing a scenario where a given task is not in the graph as expected
+ An error representing a scenario where a given task is not in the graph as expected.
"""
pass
@@ -43,8 +43,7 @@ def _filter_out_empty_tasks(func=None):
class TaskGraph(object):
"""
- A tasks graph builder.
- Build an operations flow graph
+ Task graph builder.
"""
def __init__(self, name):
@@ -59,8 +58,7 @@ class TaskGraph(object):
@property
def id(self):
"""
- Represents the id of the graph
- :return: graph id
+ ID of the graph
"""
return self._id
@@ -69,27 +67,28 @@ class TaskGraph(object):
@property
def tasks(self):
"""
- An iterator on tasks added to the graph
- :yields: Iterator over all tasks in the graph
+ Iterator over tasks in the graph.
"""
for _, data in self._graph.nodes_iter(data=True):
yield data['task']
def topological_order(self, reverse=False):
"""
- Returns topological sort on the graph
+ Topological sort of the graph.
+
:param reverse: whether to reverse the sort
- :return: a list which represents the topological sort
+ :return: list which represents the topological sort
"""
for task_id in topological_sort(self._graph, reverse=reverse):
yield self.get_task(task_id)
def get_dependencies(self, dependent_task):
"""
- Iterates over the task's dependencies
- :param BaseTask dependent_task: The task whose dependencies are requested
- :yields: Iterator over all tasks which dependency_task depends on
- :raise: TaskNotInGraphError if dependent_task is not in the graph
+ Iterates over the task's dependencies.
+
+ :param dependent_task: task whose dependencies are requested
+ :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if
+ ``dependent_task`` is not in the graph
"""
if not self.has_tasks(dependent_task):
raise TaskNotInGraphError('Task id: {0}'.format(dependent_task.id))
@@ -98,10 +97,11 @@ class TaskGraph(object):
def get_dependents(self, dependency_task):
"""
- Iterates over the task's dependents
- :param BaseTask dependency_task: The task whose dependents are requested
- :yields: Iterator over all tasks which depend on dependency_task
- :raise: TaskNotInGraphError if dependency_task is not in the graph
+ Iterates over the task's dependents.
+
+ :param dependency_task: task whose dependents are requested
+ :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if
+ ``dependency_task`` is not in the graph
"""
if not self.has_tasks(dependency_task):
raise TaskNotInGraphError('Task id: {0}'.format(dependency_task.id))
@@ -112,11 +112,11 @@ class TaskGraph(object):
def get_task(self, task_id):
"""
- Get a task instance that's been inserted to the graph by the task's id
- :param basestring task_id: The task's id
- :return: Requested task
- :rtype: BaseTask
- :raise: TaskNotInGraphError if no task found in the graph with the given id
+ Get a task instance that's been inserted to the graph by the task's ID.
+
+ :param basestring task_id: task ID
+ :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if no task found in
+ the graph with the given ID
"""
if not self._graph.has_node(task_id):
raise TaskNotInGraphError('Task id: {0}'.format(task_id))
@@ -126,9 +126,10 @@ class TaskGraph(object):
@_filter_out_empty_tasks
def add_tasks(self, *tasks):
"""
- Add a task to the graph
- :param BaseTask task: The task
- :return: A list of added tasks
+ Adds a task to the graph.
+
+ :param task: task
+ :return: list of added tasks
:rtype: list
"""
assert all([isinstance(task, (api_task.BaseTask, Iterable)) for task in tasks])
@@ -146,9 +147,10 @@ class TaskGraph(object):
@_filter_out_empty_tasks
def remove_tasks(self, *tasks):
"""
- Remove the provided task from the graph
- :param BaseTask task: The task
- :return: A list of removed tasks
+ Removes the provided task from the graph.
+
+ :param task: task
+ :return: list of removed tasks
:rtype: list
"""
return_tasks = []
@@ -165,9 +167,10 @@ class TaskGraph(object):
@_filter_out_empty_tasks
def has_tasks(self, *tasks):
"""
- Check whether a task is in the graph or not
- :param BaseTask task: The task
- :return: True if all tasks are in the graph, otherwise True
+ Checks whether a task is in the graph.
+
+ :param task: task
+ :return: ``True`` if all tasks are in the graph, otherwise ``False``
:rtype: list
"""
assert all(isinstance(t, (api_task.BaseTask, Iterable)) for t in tasks)
@@ -183,16 +186,18 @@ class TaskGraph(object):
def add_dependency(self, dependent, dependency):
"""
- Add a dependency for one item (task, sequence or parallel) on another
- The dependent will only be executed after the dependency terminates
- If either of the items is either a sequence or a parallel,
- multiple dependencies may be added
- :param BaseTask|_TasksArrangement dependent: The dependent (task, sequence or parallel)
- :param BaseTask|_TasksArrangement dependency: The dependency (task, sequence or parallel)
- :return: True if the dependency between the two hadn't already existed, otherwise False
+ Adds a dependency for one item (task, sequence or parallel) on another.
+
+ The dependent will only be executed after the dependency terminates. If either of the items
+ is either a sequence or a parallel, multiple dependencies may be added.
+
+ :param dependent: dependent (task, sequence or parallel)
+ :param dependency: dependency (task, sequence or parallel)
+ :return: ``True`` if the dependency between the two hadn't already existed, otherwise
+ ``False``
:rtype: bool
- :raise TaskNotInGraphError if either the dependent or dependency are tasks which
- are not in the graph
+ :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if either the
+ dependent or dependency are tasks which are not in the graph
"""
if not (self.has_tasks(dependent) and self.has_tasks(dependency)):
raise TaskNotInGraphError()
@@ -212,18 +217,17 @@ class TaskGraph(object):
def has_dependency(self, dependent, dependency):
"""
- Check whether one item (task, sequence or parallel) depends on another
+ Checks whether one item (task, sequence or parallel) depends on another.
- Note that if either of the items is either a sequence or a parallel,
- and some of the dependencies exist in the graph but not all of them,
- this method will return False
+ Note that if either of the items is either a sequence or a parallel, and some of the
+ dependencies exist in the graph but not all of them, this method will return ``False``.
- :param BaseTask|_TasksArrangement dependent: The dependent (task, sequence or parallel)
- :param BaseTask|_TasksArrangement dependency: The dependency (task, sequence or parallel)
- :return: True if the dependency between the two exists, otherwise False
+ :param dependent: dependent (task, sequence or parallel)
+ :param dependency: dependency (task, sequence or parallel)
+ :return: ``True`` if the dependency between the two exists, otherwise ``False``
:rtype: bool
- :raise TaskNotInGraphError if either the dependent or dependency are tasks
- which are not in the graph
+ :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if either the
+ dependent or dependency are tasks which are not in the graph
"""
if not (dependent and dependency):
return False
@@ -246,18 +250,18 @@ class TaskGraph(object):
def remove_dependency(self, dependent, dependency):
"""
- Remove a dependency for one item (task, sequence or parallel) on another
+ Removes a dependency for one item (task, sequence or parallel) on another.
- Note that if either of the items is either a sequence or a parallel, and some of
- the dependencies exist in the graph but not all of them, this method will not remove
- any of the dependencies and return False
+ Note that if either of the items is either a sequence or a parallel, and some of the
+ dependencies exist in the graph but not all of them, this method will not remove any of the
+ dependencies and return ``False``.
- :param BaseTask|_TasksArrangement dependent: The dependent (task, sequence or parallel)
- :param BaseTask|_TasksArrangement dependency: The dependency (task, sequence or parallel)
- :return: False if the dependency between the two hadn't existed, otherwise True
+ :param dependent: dependent (task, sequence or parallel)
+ :param dependency: dependency (task, sequence or parallel)
+ :return: ``False`` if the dependency between the two hadn't existed, otherwise ``True``
:rtype: bool
- :raise TaskNotInGraphError if either the dependent or dependency are tasks
- which are not in the graph
+ :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if either the
+ dependent or dependency are tasks which are not in the graph
"""
if not (self.has_tasks(dependent) and self.has_tasks(dependency)):
raise TaskNotInGraphError()
@@ -277,9 +281,10 @@ class TaskGraph(object):
@_filter_out_empty_tasks
def sequence(self, *tasks):
"""
- Create and insert a sequence into the graph, effectively each task i depends on i-1
- :param tasks: an iterable of dependencies
- :return: the provided tasks
+ Creates and inserts a sequence into the graph, effectively each task i depends on i-1.
+
+ :param tasks: iterable of dependencies
+ :return: provided tasks
"""
if tasks:
self.add_tasks(*tasks)
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/builtin/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/builtin/__init__.py b/aria/orchestrator/workflows/builtin/__init__.py
index 8b13c62..1b2f390 100644
--- a/aria/orchestrator/workflows/builtin/__init__.py
+++ b/aria/orchestrator/workflows/builtin/__init__.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-A set of builtin workflows
+Built-in workflows.
"""
from .install import install
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/builtin/execute_operation.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/builtin/execute_operation.py b/aria/orchestrator/workflows/builtin/execute_operation.py
index 437e584..949f864 100644
--- a/aria/orchestrator/workflows/builtin/execute_operation.py
+++ b/aria/orchestrator/workflows/builtin/execute_operation.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Builtin execute_operation workflow
+Built-in operation execution Workflow.
"""
from ... import workflow
@@ -34,13 +34,13 @@ def execute_operation(
node_ids,
**kwargs):
"""
- The execute_operation workflow
+ Built-in operation execution Workflow.
- :param WorkflowContext workflow_context: the workflow context
- :param TaskGraph graph: the graph which will describe the workflow.
- :param basestring operation: the operation name to execute
- :param dict operation_kwargs:
- :param bool run_by_dependency_order:
+ :param workflow_context: workflow context
+ :param graph: graph which will describe the workflow
+ :param operation: operation name to execute
+ :param operation_kwargs:
+ :param run_by_dependency_order:
:param type_names:
:param node_template_ids:
:param node_ids:
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/builtin/heal.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/builtin/heal.py b/aria/orchestrator/workflows/builtin/heal.py
index ca382e8..07e27b1 100644
--- a/aria/orchestrator/workflows/builtin/heal.py
+++ b/aria/orchestrator/workflows/builtin/heal.py
@@ -16,7 +16,7 @@
# pylint: skip-file
"""
-Builtin heal workflow
+Built-in heal workflow.
"""
from aria import workflow
@@ -28,11 +28,11 @@ from ..api import task
@workflow
def heal(ctx, graph, node_id):
"""
- The heal workflow
+ Built-in heal workflow..
- :param WorkflowContext ctx: the workflow context
- :param TaskGraph graph: the graph which will describe the workflow.
- :param node_id: the id of the node to heal
+ :param ctx: workflow context
+ :param graph: graph which will describe the workflow.
+ :param node_id: ID of the node to heal
:return:
"""
failing_node = ctx.model.node.get(node_id)
@@ -60,13 +60,12 @@ def heal(ctx, graph, node_id):
@workflow(suffix_template='{failing_nodes}')
def heal_uninstall(ctx, graph, failing_nodes, targeted_nodes):
"""
- the uninstall part of the heal mechanism
- :param WorkflowContext ctx: the workflow context
- :param TaskGraph graph: the task graph to edit.
- :param failing_nodes: the failing nodes to heal.
- :param targeted_nodes: the targets of the relationships where the failing node are
- source
- :return:
+ Uninstall phase of the heal mechanism.
+
+ :param ctx: workflow context
+ :param graph: task graph to edit
+ :param failing_nodes: failing nodes to heal
+ :param targeted_nodes: targets of the relationships where the failing node are
"""
node_sub_workflows = {}
@@ -113,13 +112,12 @@ def heal_uninstall(ctx, graph, failing_nodes, targeted_nodes):
@workflow(suffix_template='{failing_nodes}')
def heal_install(ctx, graph, failing_nodes, targeted_nodes):
"""
- the install part of the heal mechanism
- :param WorkflowContext ctx: the workflow context
- :param TaskGraph graph: the task graph to edit.
- :param failing_nodes: the failing nodes to heal.
- :param targeted_nodes: the targets of the relationships where the failing node are
- source
- :return:
+ Install phase of the heal mechanism.
+
+ :param ctx: workflow context
+ :param graph: task graph to edit.
+ :param failing_nodes: failing nodes to heal
+ :param targeted_nodes: targets of the relationships where the failing node are
"""
node_sub_workflows = {}
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/builtin/install.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/builtin/install.py b/aria/orchestrator/workflows/builtin/install.py
index 821b190..1e7c531 100644
--- a/aria/orchestrator/workflows/builtin/install.py
+++ b/aria/orchestrator/workflows/builtin/install.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Builtin install workflow
+Built-in install workflow.
"""
from ... import workflow
@@ -24,6 +24,9 @@ from . import workflows
@workflow
def install(ctx, graph):
+ """
+ Built-in install workflow.
+ """
tasks_and_nodes = []
for node in ctx.nodes:
tasks_and_nodes.append((api_task.WorkflowTask(workflows.install_node, node=node), node))
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/builtin/start.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/builtin/start.py b/aria/orchestrator/workflows/builtin/start.py
index 1946143..c02a26d 100644
--- a/aria/orchestrator/workflows/builtin/start.py
+++ b/aria/orchestrator/workflows/builtin/start.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Builtin start workflow
+Built-in start workflow.
"""
from .workflows import start_node
@@ -24,5 +24,8 @@ from ..api import task as api_task
@workflow
def start(ctx, graph):
+ """
+ Built-in start workflow.
+ """
for node in ctx.model.node.iter():
graph.add_tasks(api_task.WorkflowTask(start_node, node=node))
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/builtin/stop.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/builtin/stop.py b/aria/orchestrator/workflows/builtin/stop.py
index c1b60ae..6f9930b 100644
--- a/aria/orchestrator/workflows/builtin/stop.py
+++ b/aria/orchestrator/workflows/builtin/stop.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Builtin stop workflow
+Built-in stop workflow.
"""
from .workflows import stop_node
@@ -24,5 +24,8 @@ from ... import workflow
@workflow
def stop(ctx, graph):
+ """
+ Built-in stop workflow.
+ """
for node in ctx.model.node.iter():
graph.add_tasks(api_task.WorkflowTask(stop_node, node=node))
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/builtin/uninstall.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/builtin/uninstall.py b/aria/orchestrator/workflows/builtin/uninstall.py
index c35117e..7925f4b 100644
--- a/aria/orchestrator/workflows/builtin/uninstall.py
+++ b/aria/orchestrator/workflows/builtin/uninstall.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Builtin uninstall workflow
+Built-in uninstall workflow.
"""
from ... import workflow
@@ -24,6 +24,9 @@ from . import workflows
@workflow
def uninstall(ctx, graph):
+ """
+ Built-in uninstall workflow.
+ """
tasks_and_nodes = []
for node in ctx.nodes:
tasks_and_nodes.append((api_task.WorkflowTask(workflows.uninstall_node, node=node), node))
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/core/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/core/__init__.py b/aria/orchestrator/workflows/core/__init__.py
index 81db43f..3f28136 100644
--- a/aria/orchestrator/workflows/core/__init__.py
+++ b/aria/orchestrator/workflows/core/__init__.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Core for the workflow execution mechanism
+Workflow core.
"""
from . import engine
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/core/engine.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/core/engine.py b/aria/orchestrator/workflows/core/engine.py
index 5a94df8..d9c77e9 100644
--- a/aria/orchestrator/workflows/core/engine.py
+++ b/aria/orchestrator/workflows/core/engine.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-The workflow engine. Executes workflows
+Workflow execution.
"""
import time
@@ -33,7 +33,7 @@ from . import events_handler # pylint: disable=unused-import
class Engine(logger.LoggerMixin):
"""
- The workflow engine. Executes workflows
+ Executes workflows.
"""
def __init__(self, executors, **kwargs):
@@ -43,7 +43,7 @@ class Engine(logger.LoggerMixin):
def execute(self, ctx, resuming=False):
"""
- execute the workflow
+ Executes the workflow.
"""
if resuming:
events.on_resume_workflow_signal.send(ctx)
@@ -87,8 +87,8 @@ class Engine(logger.LoggerMixin):
def cancel_execution(ctx):
"""
Send a cancel request to the engine. If execution already started, execution status
- will be modified to 'cancelling' status. If execution is in pending mode, execution status
- will be modified to 'cancelled' directly.
+ will be modified to ``cancelling`` status. If execution is in pending mode, execution status
+ will be modified to ``cancelled`` directly.
"""
events.on_cancelling_workflow_signal.send(ctx)
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/core/events_handler.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/core/events_handler.py b/aria/orchestrator/workflows/core/events_handler.py
index 7380db8..769c1a8 100644
--- a/aria/orchestrator/workflows/core/events_handler.py
+++ b/aria/orchestrator/workflows/core/events_handler.py
@@ -14,10 +14,7 @@
# limitations under the License.
"""
-ARIA's events Sub-Package
-Path: aria.events.storage_event_handler
-
-Implementation of storage handlers for workflow and operation events.
+Workflow event handling.
"""
from datetime import (
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/events_logging.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/events_logging.py b/aria/orchestrator/workflows/events_logging.py
index 4cee867..9eee1e1 100644
--- a/aria/orchestrator/workflows/events_logging.py
+++ b/aria/orchestrator/workflows/events_logging.py
@@ -15,10 +15,7 @@
"""
-ARIA's events Sub-Package
-Path: aria.events.storage_event_handler
-
-Implementation of logger handlers for workflow and operation events.
+Workflow event logging.
"""
from .. import events
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/exceptions.py b/aria/orchestrator/workflows/exceptions.py
index b5ae496..2a1d6b1 100644
--- a/aria/orchestrator/workflows/exceptions.py
+++ b/aria/orchestrator/workflows/exceptions.py
@@ -14,8 +14,9 @@
# limitations under the License.
"""
-Workflow related Exception classes
+Workflow exceptions.
"""
+
import os
from .. import exceptions
@@ -23,14 +24,14 @@ from .. import exceptions
class ExecutorException(exceptions.AriaError):
"""
- General executor exception
+ General executor exception.
"""
pass
class ProcessException(ExecutorException):
"""
- Raised when subprocess execution fails
+ Raised when subprocess execution fails.
"""
def __init__(self, command, stderr=None, stdout=None, return_code=None):
@@ -62,13 +63,13 @@ class ProcessException(ExecutorException):
class AriaEngineError(exceptions.AriaError):
"""
- Raised by the workflow engine
+ Raised by the workflow engine.
"""
class TaskException(exceptions.AriaError):
"""
- Raised by the task
+ Raised by the task.
"""
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/executor/__init__.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/executor/__init__.py b/aria/orchestrator/workflows/executor/__init__.py
index 414a740..cafab74 100644
--- a/aria/orchestrator/workflows/executor/__init__.py
+++ b/aria/orchestrator/workflows/executor/__init__.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Executors for task execution
+Task executors.
"""
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/executor/base.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/executor/base.py b/aria/orchestrator/workflows/executor/base.py
index 4cc4503..ec1a0c7 100644
--- a/aria/orchestrator/workflows/executor/base.py
+++ b/aria/orchestrator/workflows/executor/base.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Base executor module
+Base class for task executors.
"""
from aria import logger
@@ -23,14 +23,15 @@ from aria.orchestrator import events
class BaseExecutor(logger.LoggerMixin):
"""
- Base class for executors for running tasks
+ Base class for task executors.
"""
def _execute(self, ctx):
raise NotImplementedError
def execute(self, ctx):
"""
- Execute a task
+ Executes a task.
+
:param task: task to execute
"""
if ctx.task.function:
@@ -44,7 +45,7 @@ class BaseExecutor(logger.LoggerMixin):
def close(self):
"""
- Close the executor
+ Closes the executor.
"""
pass
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/executor/celery.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/executor/celery.py b/aria/orchestrator/workflows/executor/celery.py
index 46b15fd..0716e5b 100644
--- a/aria/orchestrator/workflows/executor/celery.py
+++ b/aria/orchestrator/workflows/executor/celery.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Celery based executor
+Celery task executor.
"""
import threading
@@ -25,7 +25,7 @@ from aria.orchestrator.workflows.executor import BaseExecutor
class CeleryExecutor(BaseExecutor):
"""
- Executor which runs tasks using aria_celery
+ Celery task executor.
"""
def __init__(self, app, *args, **kwargs):
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/executor/dry.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/executor/dry.py b/aria/orchestrator/workflows/executor/dry.py
index 9d86125..9314e5d 100644
--- a/aria/orchestrator/workflows/executor/dry.py
+++ b/aria/orchestrator/workflows/executor/dry.py
@@ -14,8 +14,9 @@
# limitations under the License.
"""
-Dry executor
+Dry task executor.
"""
+
from datetime import datetime
from . import base
@@ -23,7 +24,7 @@ from . import base
class DryExecutor(base.BaseExecutor): # pylint: disable=abstract-method
"""
- Executor which dry runs tasks - prints task information without causing any side effects
+ Dry task executor: prints task information without causing any side effects.
"""
def execute(self, ctx):
with ctx.persist_changes:
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/executor/process.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/executor/process.py b/aria/orchestrator/workflows/executor/process.py
index 11e3cfd..69288ea 100644
--- a/aria/orchestrator/workflows/executor/process.py
+++ b/aria/orchestrator/workflows/executor/process.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Subprocess based executor
+Sub-process task executor.
"""
# pylint: disable=wrong-import-position
@@ -67,7 +67,7 @@ _Task = namedtuple('_Task', 'proc, ctx')
class ProcessExecutor(base.BaseExecutor):
"""
- Executor which runs tasks in a subprocess environment
+ Sub-process task executor.
"""
def __init__(self, plugin_manager=None, python_path=None, *args, **kwargs):
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/orchestrator/workflows/executor/thread.py
----------------------------------------------------------------------
diff --git a/aria/orchestrator/workflows/executor/thread.py b/aria/orchestrator/workflows/executor/thread.py
index 8c447b6..d9dcdf8 100644
--- a/aria/orchestrator/workflows/executor/thread.py
+++ b/aria/orchestrator/workflows/executor/thread.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-Thread based executor
+Thread task executor.
"""
import Queue
@@ -29,9 +29,11 @@ from .base import BaseExecutor
class ThreadExecutor(BaseExecutor):
"""
- Executor which runs tasks in a separate thread. It's easier writing tests
- using this executor rather than the full blown subprocess executor.
- Note: This executor is not capable of running plugin operations.
+ Thread task executor.
+
+ It's easier writing tests using this executor rather than the full-blown sub-process executor.
+
+ Note: This executor is incapable of running plugin operations.
"""
def __init__(self, pool_size=1, *args, **kwargs):
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/__init__.py
----------------------------------------------------------------------
diff --git a/aria/parser/__init__.py b/aria/parser/__init__.py
index 64df88a..7903b52 100644
--- a/aria/parser/__init__.py
+++ b/aria/parser/__init__.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Parser package.
+"""
+
from .specification import implements_specification, iter_specifications
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/consumption/__init__.py
----------------------------------------------------------------------
diff --git a/aria/parser/consumption/__init__.py b/aria/parser/consumption/__init__.py
index 76e73be..bd4b29c 100644
--- a/aria/parser/consumption/__init__.py
+++ b/aria/parser/consumption/__init__.py
@@ -13,6 +13,37 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Consumption package.
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.consumption.ConsumptionContext
+ aria.parser.consumption.Style
+
+Consumers
+---------
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.consumption.Consumer
+ aria.parser.consumption.ConsumerChain
+ aria.parser.consumption.ConsumerException
+ aria.parser.consumption.Inputs
+ aria.parser.consumption.ServiceTemplate
+ aria.parser.consumption.Types
+ aria.parser.consumption.CoerceServiceInstanceValues
+ aria.parser.consumption.ValidateServiceInstance
+ aria.parser.consumption.SatisfyRequirements
+ aria.parser.consumption.ValidateCapabilities
+ aria.parser.consumption.FindHosts
+ aria.parser.consumption.ConfigureOperations
+ aria.parser.consumption.ServiceInstance
+ aria.parser.consumption.Read
+ aria.parser.consumption.Validate
+"""
from .exceptions import ConsumerException
from .context import ConsumptionContext
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/consumption/consumer.py
----------------------------------------------------------------------
diff --git a/aria/parser/consumption/consumer.py b/aria/parser/consumption/consumer.py
index f9c2f2e..4f4c614 100644
--- a/aria/parser/consumption/consumer.py
+++ b/aria/parser/consumption/consumer.py
@@ -48,8 +48,8 @@ class ConsumerChain(Consumer):
"""
ARIA consumer chain.
- Calls consumers in order, handling exception by calling `_handle_exception` on them,
- and stops the chain if there are any validation issues.
+ Calls consumers in order, handling exception by calling ``_handle_exception`` on them, and stops
+ the chain if there are any validation issues.
"""
def __init__(self, context, consumer_classes=None, handle_exceptions=True):
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/consumption/context.py
----------------------------------------------------------------------
diff --git a/aria/parser/consumption/context.py b/aria/parser/consumption/context.py
index a8b75df..6fa61f4 100644
--- a/aria/parser/consumption/context.py
+++ b/aria/parser/consumption/context.py
@@ -29,16 +29,22 @@ _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`
+ Consumption context.
+
+ :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 +77,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/2ed2e1c2/aria/parser/consumption/presentation.py
----------------------------------------------------------------------
diff --git a/aria/parser/consumption/presentation.py b/aria/parser/consumption/presentation.py
index 7766473..542b3f0 100644
--- a/aria/parser/consumption/presentation.py
+++ b/aria/parser/consumption/presentation.py
@@ -26,11 +26,12 @@ 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.loading.Loader`,
+ :class:`~aria.parser.reading.Reader`, and :class:`~aria.parser.presentation.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/2ed2e1c2/aria/parser/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/parser/exceptions.py b/aria/parser/exceptions.py
index 5d1a55c..a1f7012 100644
--- a/aria/parser/exceptions.py
+++ b/aria/parser/exceptions.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Parser exceptions.
+"""
+
from ..exceptions import AriaException
from .validation import Issue
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/loading/__init__.py
----------------------------------------------------------------------
diff --git a/aria/parser/loading/__init__.py b/aria/parser/loading/__init__.py
index 006f164..834675e 100644
--- a/aria/parser/loading/__init__.py
+++ b/aria/parser/loading/__init__.py
@@ -13,6 +13,41 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Loading package.
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.loading.LoadingContext
+ aria.parser.loading.LoaderException
+ aria.parser.loading.LoaderNotFoundError
+ aria.parser.loading.DocumentNotFoundException
+ aria.parser.loading.LoaderSource
+ aria.parser.loading.DefaultLoaderSource
+
+Loaders
+-------
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.loading.Loader
+ aria.parser.loading.FileTextLoader
+ aria.parser.loading.LiteralLoader
+ aria.parser.loading.RequestLoader
+ aria.parser.loading.RequestTextLoader
+ aria.parser.loading.UriTextLoader
+
+Locations
+---------
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.loading.Location
+ aria.parser.loading.UriLocation
+"""
from .exceptions import LoaderException, LoaderNotFoundError, DocumentNotFoundException
from .context import LoadingContext
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/loading/context.py
----------------------------------------------------------------------
diff --git a/aria/parser/loading/context.py b/aria/parser/loading/context.py
index 44e3fd1..59727c9 100644
--- a/aria/parser/loading/context.py
+++ b/aria/parser/loading/context.py
@@ -20,10 +20,12 @@ from .source import DefaultLoaderSource
class LoadingContext(object):
"""
- Properties:
+ Loading context.
- * :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: ~aria.parser.loading.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/2ed2e1c2/aria/parser/loading/literal.py
----------------------------------------------------------------------
diff --git a/aria/parser/loading/literal.py b/aria/parser/loading/literal.py
index 1b99fd8..7865008 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/2ed2e1c2/aria/parser/loading/location.py
----------------------------------------------------------------------
diff --git a/aria/parser/loading/location.py b/aria/parser/loading/location.py
index 5bc6fab..902e856 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/2ed2e1c2/aria/parser/loading/source.py
----------------------------------------------------------------------
diff --git a/aria/parser/loading/source.py b/aria/parser/loading/source.py
index 7acf813..bcd6dd1 100644
--- a/aria/parser/loading/source.py
+++ b/aria/parser/loading/source.py
@@ -32,7 +32,7 @@ class LoaderSource(object):
class DefaultLoaderSource(LoaderSource):
"""
The default ARIA loader source will generate a :class:`UriTextLoader` for
- :class:`UriLocation' and a :class:`LiteralLoader` for a :class:`LiteralLocation`.
+ :class:`UriLocation` and a :class:`LiteralLoader` for a :class:`LiteralLocation`.
"""
def get_loader(self, context, location, origin_location):
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/loading/uri.py
----------------------------------------------------------------------
diff --git a/aria/parser/loading/uri.py b/aria/parser/loading/uri.py
index 1b23bf6..a5a18e6 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 parser can supply a ``uri_loader_prefix`` function with extra prefixes.
"""
def __init__(self, context, location, origin_location=None):
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/modeling/__init__.py
----------------------------------------------------------------------
diff --git a/aria/parser/modeling/__init__.py b/aria/parser/modeling/__init__.py
index df127cd..4b1c995 100644
--- a/aria/parser/modeling/__init__.py
+++ b/aria/parser/modeling/__init__.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Modeling package.
+"""
+
from .context import IdType, ModelingContext
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/modeling/context.py
----------------------------------------------------------------------
diff --git a/aria/parser/modeling/context.py b/aria/parser/modeling/context.py
index 4a53641..3d75617 100644
--- a/aria/parser/modeling/context.py
+++ b/aria/parser/modeling/context.py
@@ -38,14 +38,20 @@ 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
+ Modeling context.
+
+ :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: {:obj:`basestring`, object}
"""
def __init__(self):
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/presentation/__init__.py
----------------------------------------------------------------------
diff --git a/aria/parser/presentation/__init__.py b/aria/parser/presentation/__init__.py
index a681695..5633e7b 100644
--- a/aria/parser/presentation/__init__.py
+++ b/aria/parser/presentation/__init__.py
@@ -13,6 +13,85 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Presentation package.
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.presentation.PresentationContext
+ aria.parser.presentation.PresenterException
+ aria.parser.presentation.PresenterNotFoundError
+ aria.parser.presentation.Field
+ aria.parser.presentation.NULL
+ aria.parser.presentation.none_to_null
+ aria.parser.presentation.null_to_none
+ aria.parser.presentation.Value
+ aria.parser.presentation.Presenter
+ aria.parser.presentation.PresenterSource
+ aria.parser.presentation.DefaultPresenterSource
+
+Presentations
+-------------
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.presentation.PresentationBase
+ aria.parser.presentation.Presentation
+ aria.parser.presentation.AsIsPresentation
+
+Field decorators
+----------------
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.presentation.has_fields
+ aria.parser.presentation.short_form_field
+ aria.parser.presentation.allow_unknown_fields
+ aria.parser.presentation.primitive_field
+ aria.parser.presentation.primitive_list_field
+ aria.parser.presentation.primitive_dict_field
+ aria.parser.presentation.primitive_dict_unknown_fields
+ aria.parser.presentation.object_field
+ aria.parser.presentation.object_list_field
+ aria.parser.presentation.object_dict_field
+ aria.parser.presentation.object_sequenced_list_field
+ aria.parser.presentation.object_dict_unknown_fields
+ aria.parser.presentation.field_getter
+ aria.parser.presentation.field_setter
+ aria.parser.presentation.field_validator
+
+Field validators
+----------------
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.presentation.type_validator
+ aria.parser.presentation.list_type_validator
+ aria.parser.presentation.list_length_validator
+ aria.parser.presentation.derived_from_validator
+
+Utilities
+---------
+
+.. autosummary::
+ :nosignatures:
+
+ aria.parser.presentation.get_locator
+ aria.parser.presentation.parse_types_dict_names
+ aria.parser.presentation.validate_primitive
+ aria.parser.presentation.validate_no_short_form
+ aria.parser.presentation.validate_no_unknown_fields
+ aria.parser.presentation.validate_known_fields
+ aria.parser.presentation.get_parent_presentation
+ aria.parser.presentation.report_issue_for_unknown_type
+ aria.parser.presentation.report_issue_for_parent_is_self
+ aria.parser.presentation.report_issue_for_unknown_parent_type
+ aria.parser.presentation.report_issue_for_circular_type_hierarchy
+"""
from .exceptions import PresenterException, PresenterNotFoundError
from .context import PresentationContext
@@ -29,8 +108,8 @@ from .field_validators import (type_validator, list_type_validator, list_length_
derived_from_validator)
from .utils import (get_locator, parse_types_dict_names, validate_primitive, validate_no_short_form,
validate_no_unknown_fields, validate_known_fields, get_parent_presentation,
- report_issue_for_unknown_type, report_issue_for_parent_is_self,
- report_issue_for_circular_type_hierarchy)
+ report_issue_for_unknown_type, report_issue_for_unknown_parent_type,
+ report_issue_for_parent_is_self, report_issue_for_circular_type_hierarchy)
__all__ = (
'PresenterException',
@@ -74,5 +153,6 @@ __all__ = (
'validate_known_fields',
'get_parent_presentation',
'report_issue_for_unknown_type',
+ 'report_issue_for_unknown_parent_type',
'report_issue_for_parent_is_self',
'report_issue_for_circular_type_hierarchy')
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/2ed2e1c2/aria/parser/presentation/context.py
----------------------------------------------------------------------
diff --git a/aria/parser/presentation/context.py b/aria/parser/presentation/context.py
index 26dcb39..44a6f82 100644
--- a/aria/parser/presentation/context.py
+++ b/aria/parser/presentation/context.py
@@ -19,16 +19,24 @@ 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
+ Presentation context.
+
+ :ivar presenter: the generated presenter instance
+ :vartype presenter: ~aria.parser.presentation.Presenter
+ :ivar location: from where we will generate the presenter
+ :vartype location: ~aria.parser.loading.Location
+ :ivar presenter_source: for finding presenter classes
+ :vartype presenter_source: ~aria.parser.presentation.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/2ed2e1c2/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.
"""