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 11:53:06 UTC
[09/10] incubator-ariatosca git commit: ARIA-286 Sphinx documentation
for code and CLI
ARIA-286 Sphinx documentation for code and CLI
Project: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/commit/8eef8ed9
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/8eef8ed9
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/8eef8ed9
Branch: refs/heads/ARIA-286-sphinx-documentation
Commit: 8eef8ed92310416fea9a95d7f548fdbd440d0f36
Parents: 4ff4012
Author: Tal Liron <ta...@gmail.com>
Authored: Thu Jun 22 21:13:28 2017 -0500
Committer: Ran Ziv <ra...@gigaspaces.com>
Committed: Thu Jun 29 14:49:18 2017 +0300
----------------------------------------------------------------------
aria/__init__.py | 14 +-
aria/cli/__init__.py | 4 +
aria/cli/color.py | 8 +-
aria/cli/commands/__init__.py | 4 +
aria/cli/commands/executions.py | 45 +-
aria/cli/commands/logs.py | 22 +-
aria/cli/commands/node_templates.py | 21 +-
aria/cli/commands/nodes.py | 23 +-
aria/cli/commands/plugins.py | 38 +-
aria/cli/commands/reset.py | 13 +-
aria/cli/commands/service_templates.py | 58 +-
aria/cli/commands/services.py | 43 +-
aria/cli/commands/workflows.py | 23 +-
aria/cli/config/__init__.py | 4 +
aria/cli/config/config.py | 3 +
aria/cli/core/__init__.py | 4 +
aria/cli/core/aria.py | 13 +-
aria/cli/csar.py | 7 +
aria/cli/defaults.py | 10 +
aria/cli/env.py | 3 +
aria/cli/exceptions.py | 3 +
aria/cli/execution_logging.py | 5 +
aria/cli/helptexts.py | 19 +-
aria/cli/inputs.py | 24 +-
aria/cli/logger.py | 3 +
aria/cli/main.py | 15 +-
aria/cli/service_template_utils.py | 64 +-
aria/cli/table.py | 56 +-
aria/cli/utils.py | 44 +-
aria/core.py | 4 +
aria/exceptions.py | 10 +-
aria/extension.py | 34 +-
aria/logger.py | 38 +-
aria/modeling/__init__.py | 4 +
aria/modeling/constraints.py | 5 +-
aria/modeling/exceptions.py | 4 +
aria/modeling/functions.py | 23 +-
aria/modeling/mixins.py | 101 +-
aria/modeling/models.py | 113 +-
aria/modeling/orchestration.py | 612 ++++---
aria/modeling/relationship.py | 120 +-
aria/modeling/service_changes.py | 83 +-
aria/modeling/service_common.py | 364 ++--
aria/modeling/service_instance.py | 1527 ++++++++++-------
aria/modeling/service_template.py | 1562 +++++++++++-------
aria/modeling/types.py | 49 +-
aria/modeling/utils.py | 50 +-
aria/orchestrator/__init__.py | 4 +-
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 | 6 +-
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 | 72 +-
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 | 120 ++
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 | 4 +
aria/parser/consumption/__init__.py | 31 +
aria/parser/consumption/consumer.py | 4 +-
aria/parser/consumption/context.py | 28 +-
aria/parser/consumption/presentation.py | 7 +-
aria/parser/exceptions.py | 4 +
aria/parser/loading/__init__.py | 35 +
aria/parser/loading/context.py | 8 +-
aria/parser/loading/literal.py | 2 +-
aria/parser/loading/location.py | 8 +-
aria/parser/loading/source.py | 2 +-
aria/parser/loading/uri.py | 6 +-
aria/parser/modeling/__init__.py | 4 +
aria/parser/modeling/context.py | 22 +-
aria/parser/presentation/__init__.py | 84 +-
aria/parser/presentation/context.py | 28 +-
aria/parser/presentation/field_validators.py | 19 +-
aria/parser/presentation/fields.py | 31 +-
aria/parser/presentation/null.py | 4 +-
aria/parser/presentation/presentation.py | 54 +-
aria/parser/presentation/source.py | 2 +-
aria/parser/presentation/utils.py | 12 +-
aria/parser/reading/__init__.py | 23 +
aria/parser/reading/context.py | 8 +-
aria/parser/reading/locator.py | 4 +-
aria/parser/reading/reader.py | 2 +-
aria/parser/specification.py | 4 +
aria/parser/validation/__init__.py | 4 +
aria/parser/validation/context.py | 15 +-
aria/storage/__init__.py | 24 +-
aria/storage/api.py | 78 +-
aria/storage/collection_instrumentation.py | 50 +-
aria/storage/core.py | 62 +-
aria/storage/exceptions.py | 4 +-
aria/storage/filesystem_rapi.py | 53 +-
aria/storage/sql_mapi.py | 162 +-
aria/utils/__init__.py | 4 +
aria/utils/archive.py | 3 +
aria/utils/argparse.py | 6 +-
aria/utils/caching.py | 9 +-
aria/utils/collections.py | 34 +-
aria/utils/console.py | 4 +
aria/utils/exceptions.py | 4 +
aria/utils/file.py | 9 +-
aria/utils/formatting.py | 33 +-
aria/utils/http.py | 24 +-
aria/utils/imports.py | 12 +-
aria/utils/openclose.py | 6 +-
aria/utils/plugin.py | 4 +
aria/utils/process.py | 4 +
aria/utils/specification.py | 4 +
aria/utils/threading.py | 52 +-
aria/utils/type.py | 16 +-
aria/utils/uris.py | 8 +-
aria/utils/uuid.py | 20 +-
aria/utils/validation.py | 6 +-
aria/utils/versions.py | 13 +-
docs/aria.cli.rst | 100 ++
docs/aria.modeling.models.rst | 21 +
docs/aria.modeling.rst | 56 +
docs/aria.orchestrator.context.rst | 46 +
....orchestrator.execution_plugin.ctx_proxy.rst | 31 +
docs/aria.orchestrator.execution_plugin.rst | 56 +
docs/aria.orchestrator.execution_plugin.ssh.rst | 31 +
docs/aria.orchestrator.rst | 46 +
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 | 51 +
docs/aria.parser.consumption.rst | 21 +
docs/aria.parser.loading.rst | 21 +
docs/aria.parser.modeling.rst | 21 +
docs/aria.parser.presentation.rst | 21 +
docs/aria.parser.reading.rst | 21 +
docs/aria.parser.rst | 31 +
docs/aria.parser.validation.rst | 21 +
docs/aria.rst | 40 +
docs/aria.storage.rst | 51 +
docs/aria.utils.rst | 121 ++
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/cli.rst | 57 +
docs/conf.py | 86 +-
docs/index.rst | 66 +-
docs/parser.rst | 56 -
docs/requirements.txt | 3 +-
docs/rest.rst | 20 +
docs/tosca.rst | 36 -
.../simple_nfv_v1_0/presenter.py | 8 +-
.../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/__init__.py | 2 -
.../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 +-
.../orchestrator/workflows/core/test_events.py | 4 +-
203 files changed, 6187 insertions(+), 3050 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/__init__.py
----------------------------------------------------------------------
diff --git a/aria/__init__.py b/aria/__init__.py
index bed1dc6..76a62ce 100644
--- a/aria/__init__.py
+++ b/aria/__init__.py
@@ -14,7 +14,7 @@
# limitations under the License.
"""
-ARIA top level package
+The ARIA root package provides entry points for extension and storage initialization.
"""
import sys
@@ -45,13 +45,17 @@ __all__ = (
'__version__',
'workflow',
'operation',
+ 'install_aria_extensions',
+ 'application_model_storage',
+ 'application_resource_storage'
)
def install_aria_extensions():
"""
- Iterates all Python packages with names beginning with :code:`aria_extension_` and all
- :code:`aria_extension` entry points and loads them.
+ Iterates all Python packages with names beginning with ``aria_extension_`` and all
+ ``aria_extension`` entry points and loads them.
+
It then invokes all registered extension functions.
"""
for loader, module_name, _ in iter_modules():
@@ -64,7 +68,7 @@ def install_aria_extensions():
def application_model_storage(api, api_kwargs=None, initiator=None, initiator_kwargs=None):
"""
- Initiate model storage
+ Initiate model storage.
"""
return storage.ModelStorage(api_cls=api,
api_kwargs=api_kwargs,
@@ -75,7 +79,7 @@ def application_model_storage(api, api_kwargs=None, initiator=None, initiator_kw
def application_resource_storage(api, api_kwargs=None, initiator=None, initiator_kwargs=None):
"""
- Initiate resource storage
+ Initiate resource storage.
"""
return storage.ResourceStorage(api_cls=api,
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/__init__.py
----------------------------------------------------------------------
diff --git a/aria/cli/__init__.py b/aria/cli/__init__.py
index ae1e83e..c0ef46f 100644
--- a/aria/cli/__init__.py
+++ b/aria/cli/__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.
+
+"""
+CLI package.
+"""
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/color.py
----------------------------------------------------------------------
diff --git a/aria/cli/color.py b/aria/cli/color.py
index 5e0355a..03381ba 100644
--- a/aria/cli/color.py
+++ b/aria/cli/color.py
@@ -12,6 +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.
+
+"""
+Terminal colorization utilities.
+"""
+
from StringIO import StringIO
import re
@@ -75,8 +80,7 @@ class ColorSpec(object):
def __init__(self, fore=None, back=None, style=None):
"""
It is possible to provide fore, back and style arguments. each could be either
- the color is lower case letter, or the actual color from colorama.
-
+ the color is lower case letter, or the actual color from Colorama.
"""
self._kwargs = dict(fore=fore, back=back, style=style)
self._str = StringIO()
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/__init__.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/__init__.py b/aria/cli/commands/__init__.py
index a01a029..ba34a43 100644
--- a/aria/cli/commands/__init__.py
+++ b/aria/cli/commands/__init__.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI commands package.
+"""
+
from . import (
executions,
logs,
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/executions.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/executions.py b/aria/cli/commands/executions.py
index 9f56ccd..ea70af5 100644
--- a/aria/cli/commands/executions.py
+++ b/aria/cli/commands/executions.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI ``executions`` sub-commands.
+"""
+
import os
from .. import helptexts
@@ -27,28 +31,30 @@ from ...orchestrator.workflows.executor.dry import DryExecutor
from ...utils import formatting
from ...utils import threading
-EXECUTION_COLUMNS = ['id', 'workflow_name', 'status', 'service_name',
- 'created_at', 'error']
+EXECUTION_COLUMNS = ('id', 'workflow_name', 'status', 'service_name',
+ 'created_at', 'error')
@aria.group(name='executions')
@aria.options.verbose()
def executions():
- """Handle workflow executions
+ """
+ Manage executions
"""
pass
@executions.command(name='show',
- short_help='Show execution information')
+ short_help='Show information for an execution')
@aria.argument('execution-id')
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def show(execution_id, model_storage, logger):
- """Show information for a specific execution
+ """
+ Show information for an execution
- `EXECUTION_ID` is the execution to get information on.
+ EXECUTION_ID is the unique ID of the execution.
"""
logger.info('Showing execution {0}'.format(execution_id))
execution = model_storage.execution.get(execution_id)
@@ -68,7 +74,7 @@ def show(execution_id, model_storage, logger):
@executions.command(name='list',
- short_help='List service executions')
+ short_help='List executions')
@aria.options.service_name(required=False)
@aria.options.sort_by()
@aria.options.descending
@@ -80,10 +86,11 @@ def list(service_name,
descending,
model_storage,
logger):
- """List executions
+ """
+ List executions
- If `SERVICE_NAME` is provided, list executions for that service.
- Otherwise, list executions for all services.
+ If SERVICE_NAME is provided, list executions on that service. Otherwise, list executions on all
+ services.
"""
if service_name:
logger.info('Listing executions for service {0}...'.format(
@@ -102,7 +109,7 @@ def list(service_name,
@executions.command(name='start',
- short_help='Execute a workflow')
+ short_help='Start a workflow on a service')
@aria.argument('workflow-name')
@aria.options.service_name(required=True)
@aria.options.inputs(help=helptexts.EXECUTION_INPUTS)
@@ -126,9 +133,12 @@ def start(workflow_name,
resource_storage,
plugin_manager,
logger):
- """Execute a workflow
+ """
+ Start a workflow on a service
- `WORKFLOW_NAME` is the name of the workflow to execute (e.g. `uninstall`)
+ SERVICE_NAME is the unique name of the service.
+
+ WORKFLOW_NAME is the unique name of the workflow within the service (e.g. "uninstall").
"""
service = model_storage.service.get_by_name(service_name)
executor = DryExecutor() if dry else None # use WorkflowRunner's default executor
@@ -145,7 +155,7 @@ def start(workflow_name,
@executions.command(name='resume',
- short_help='Resume a workflow')
+ short_help='Resume a stopped execution')
@aria.argument('execution-id')
@aria.options.inputs(help=helptexts.EXECUTION_INPUTS)
@aria.options.dry_execution
@@ -166,6 +176,11 @@ def resume(execution_id,
resource_storage,
plugin_manager,
logger):
+ """
+ Resume a stopped execution
+
+ EXECUTION_ID is the unique ID of the execution.
+ """
executor = DryExecutor() if dry else None # use WorkflowRunner's default executor
execution = model_storage.execution.get(execution_id)
@@ -225,7 +240,7 @@ def _run_execution(workflow_runner, logger, model_storage, dry, mark_pattern):
def _cancel_execution(workflow_runner, execution_thread, logger, log_iterator):
- logger.info('Cancelling execution. Press Ctrl+C again to force-cancel')
+ logger.info('Cancelling execution. Press Ctrl+C again to force-cancel.')
workflow_runner.cancel()
while execution_thread.is_alive():
try:
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/logs.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/logs.py b/aria/cli/commands/logs.py
index 2f7f361..b751b97 100644
--- a/aria/cli/commands/logs.py
+++ b/aria/cli/commands/logs.py
@@ -12,6 +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.
+
+"""
+CLI ``logs`` sub-commands.
+"""
+
from .. import execution_logging
from ..logger import ModelLogIterator
from ..core import aria
@@ -20,20 +25,24 @@ from ..core import aria
@aria.group(name='logs')
@aria.options.verbose()
def logs():
- """Show logs from workflow executions
+ """
+ Manage logs of workflow executions
"""
pass
@logs.command(name='list',
- short_help='List execution logs')
+ short_help='List logs for an execution')
@aria.argument('execution-id')
@aria.options.verbose()
@aria.options.mark_pattern()
@aria.pass_model_storage
@aria.pass_logger
def list(execution_id, mark_pattern, model_storage, logger):
- """Display logs for an execution
+ """
+ List logs for an execution
+
+ EXECUTION_ID is the unique ID of the execution.
"""
logger.info('Listing logs for execution id {0}'.format(execution_id))
log_iterator = ModelLogIterator(model_storage, execution_id)
@@ -45,15 +54,16 @@ def list(execution_id, mark_pattern, model_storage, logger):
@logs.command(name='delete',
- short_help='Delete execution logs')
+ short_help='Delete logs of an execution')
@aria.argument('execution-id')
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def delete(execution_id, model_storage, logger):
- """Delete logs of an execution
+ """
+ Delete logs of an execution
- `EXECUTION_ID` is the execution logs to delete.
+ EXECUTION_ID is the unique ID of the execution.
"""
logger.info('Deleting logs for execution id {0}'.format(execution_id))
logs_list = model_storage.log.list(filters=dict(execution_fk=execution_id))
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/node_templates.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/node_templates.py b/aria/cli/commands/node_templates.py
index 50c755e..ec160d2 100644
--- a/aria/cli/commands/node_templates.py
+++ b/aria/cli/commands/node_templates.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI ``node-templates`` sub-commands.
+"""
+
from .. import table
from .. import utils
from ..core import aria
@@ -24,22 +28,24 @@ NODE_TEMPLATE_COLUMNS = ['id', 'name', 'description', 'service_template_name', '
@aria.group(name='node-templates')
@aria.options.verbose()
def node_templates():
- """Handle a service template's node templates
+ """
+ Manages stored service templates' node templates
"""
pass
@node_templates.command(name='show',
- short_help='Show node information')
+ short_help='Show information for a stored node template')
@aria.argument('node-template-id')
# @aria.options.service_template_name(required=True)
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def show(node_template_id, model_storage, logger):
- """Show information for a specific node of a specific service template
+ """
+ Show information for a stored node template
- `NODE_TEMPLATE_ID` is the node id to get information on.
+ NODE_TEMPLATE_ID is the unique node template ID.
"""
logger.info('Showing node template {0}'.format(node_template_id))
node_template = model_storage.node_template.get(node_template_id)
@@ -64,7 +70,7 @@ def show(node_template_id, model_storage, logger):
@node_templates.command(name='list',
- short_help='List node templates for a service template')
+ short_help='List stored node templates')
@aria.options.service_template_name()
@aria.options.sort_by('service_template_name')
@aria.options.descending
@@ -72,9 +78,10 @@ def show(node_template_id, model_storage, logger):
@aria.pass_model_storage
@aria.pass_logger
def list(service_template_name, sort_by, descending, model_storage, logger):
- """List node templates
+ """
+ List stored node templates
- If `SERVICE_TEMPLATE_NAME` is provided, list nodes for that service template.
+ If SERVICE_TEMPLATE_NAME is provided, list node templates for that stored service template.
Otherwise, list node templates for all service templates.
"""
if service_template_name:
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/nodes.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/nodes.py b/aria/cli/commands/nodes.py
index 1bbefe6..30f1dd4 100644
--- a/aria/cli/commands/nodes.py
+++ b/aria/cli/commands/nodes.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI ``nodes`` sub-commands.
+"""
+
from .. import table
from .. import utils
from ..core import aria
@@ -24,21 +28,23 @@ NODE_COLUMNS = ['id', 'name', 'service_name', 'node_template_name', 'state']
@aria.group(name='nodes')
@aria.options.verbose()
def nodes():
- """Handle a service's nodes
+ """
+ Manage services' nodes
"""
pass
@nodes.command(name='show',
- short_help='Show node information')
+ short_help='Show information for a node')
@aria.argument('node_id')
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def show(node_id, model_storage, logger):
- """Showing information for a specific node
+ """
+ Show information for a node
- `NODE_ID` is the id of the node to get information on.
+ NODE_ID is the unique node ID.
"""
logger.info('Showing node {0}'.format(node_id))
node = model_storage.node.get(node_id)
@@ -55,7 +61,7 @@ def show(node_id, model_storage, logger):
@nodes.command(name='list',
- short_help='List node for a service')
+ short_help='List node')
@aria.options.service_name(required=False)
@aria.options.sort_by('service_name')
@aria.options.descending
@@ -67,10 +73,11 @@ def list(service_name,
descending,
model_storage,
logger):
- """List nodes
+ """
+ List nodes
- If `SERVICE_NAME` is provided, list nodes for that service.
- Otherwise, list nodes for all services.
+ If SERVICE_NAME is provided, list nodes for that service. Otherwise, list nodes for all
+ services.
"""
if service_name:
logger.info('Listing nodes for service {0}...'.format(service_name))
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/plugins.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/plugins.py b/aria/cli/commands/plugins.py
index 670288e..b5d68a2 100644
--- a/aria/cli/commands/plugins.py
+++ b/aria/cli/commands/plugins.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI ``plugins`` sub-commands.
+"""
+
from .. import table
from .. import utils
from ..core import aria
@@ -25,24 +29,26 @@ PLUGIN_COLUMNS = ['id', 'package_name', 'package_version', 'supported_platform',
@aria.group(name='plugins')
@aria.options.verbose()
def plugins():
- """Handle plugins
+ """
+ Manage plugins
"""
pass
@plugins.command(name='validate',
- short_help='Validate a plugin')
+ short_help='Validate a plugin archive')
@aria.argument('plugin-path')
@aria.options.verbose()
@aria.pass_plugin_manager
@aria.pass_logger
def validate(plugin_path, plugin_manager, logger):
- """Validate a plugin archive
+ """
+ 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).
+ A valid plugin is a wagon (`http://github.com/cloudify-cosmo/wagon`) in the ZIP format (suffix
+ may also be `.wgn`).
- `PLUGIN_PATH` is the path to wagon archive to validate.
+ PLUGIN_PATH is the path to the wagon archive.
"""
logger.info('Validating plugin {0}...'.format(plugin_path))
plugin_manager.validate_plugin(plugin_path)
@@ -57,9 +63,13 @@ def validate(plugin_path, plugin_manager, logger):
@aria.pass_plugin_manager
@aria.pass_logger
def install(ctx, plugin_path, plugin_manager, logger):
- """Install a plugin
+ """
+ Install a plugin
- `PLUGIN_PATH` is the path to wagon archive to install.
+ A valid plugin is a wagon (`http://github.com/cloudify-cosmo/wagon`) in the ZIP format (suffix
+ may also be `.wgn`).
+
+ PLUGIN_PATH is the path to the wagon archive.
"""
ctx.invoke(validate, plugin_path=plugin_path)
logger.info('Installing plugin {0}...'.format(plugin_path))
@@ -68,15 +78,16 @@ def install(ctx, plugin_path, plugin_manager, logger):
@plugins.command(name='show',
- short_help='show plugin information')
+ short_help='Show information for an installed plugin')
@aria.argument('plugin-id')
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def show(plugin_id, model_storage, logger):
- """Show information for a specific plugin
+ """
+ Show information for an installed plugin
- `PLUGIN_ID` is the id of the plugin to show information on.
+ PLUGIN_ID is the unique installed plugin ID in this ARIA instance.
"""
logger.info('Showing plugin {0}...'.format(plugin_id))
plugin = model_storage.plugin.get(plugin_id)
@@ -84,14 +95,15 @@ def show(plugin_id, model_storage, logger):
@plugins.command(name='list',
- short_help='List plugins')
+ short_help='List all installed plugins')
@aria.options.sort_by('uploaded_at')
@aria.options.descending
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def list(sort_by, descending, model_storage, logger):
- """List all plugins on the manager
+ """
+ List all installed plugins
"""
logger.info('Listing all plugins...')
plugins_list = model_storage.plugin.list(
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/reset.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/reset.py b/aria/cli/commands/reset.py
index 1fe0714..c82c707 100644
--- a/aria/cli/commands/reset.py
+++ b/aria/cli/commands/reset.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI ``reset`` command.
+"""
+
from .. import helptexts
from ..core import aria
from ..env import env
@@ -20,7 +24,7 @@ from ..exceptions import AriaCliError
@aria.command(name='reset',
- short_help="Reset ARIA's working directory")
+ short_help="Reset ARIA working directory")
@aria.options.force(help=helptexts.FORCE_RESET)
@aria.options.reset_config
@aria.pass_logger
@@ -28,9 +32,10 @@ from ..exceptions import AriaCliError
def reset(force, reset_config, logger):
"""
Reset ARIA working directory
- Resetting the working directory will result in the deletion of all state in ARIA; The user
- configuration will remain intact, unless the `reset_config` flag has been set as well, in
- which case the entire ARIA working directory shall be removed.
+
+ Deletes installed plugins, service templates, services, executions, and logs. The user
+ configuration will remain intact unless the `--reset_config` flag has been set as well, in
+ which case the entire ARIA working directory shall be removed.
"""
if not force:
raise AriaCliError("To reset the ARIA's working directory, you must also provide the force"
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/service_templates.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/service_templates.py b/aria/cli/commands/service_templates.py
index d139195..f567aa8 100644
--- a/aria/cli/commands/service_templates.py
+++ b/aria/cli/commands/service_templates.py
@@ -13,6 +13,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI ``service-templates`` sub-commands.
+"""
import os
@@ -35,13 +38,14 @@ SERVICE_TEMPLATE_COLUMNS = \
@aria.group(name='service-templates')
@aria.options.verbose()
def service_templates():
- """Handle service templates on the manager
+ """
+ Manage service templates
"""
pass
@service_templates.command(name='show',
- short_help='Show service template information')
+ short_help='Show information for a stored service template')
@aria.argument('service-template-name')
@aria.options.verbose()
@aria.pass_model_storage
@@ -52,9 +56,10 @@ def service_templates():
@aria.pass_logger
def show(service_template_name, model_storage, mode_full, mode_types, format_json, format_yaml,
logger):
- """Show information for a specific service template
+ """
+ Show information for a stored service template
- `SERVICE_TEMPLATE_NAME` is the name of the service template to show information on.
+ SERVICE_TEMPLATE_NAME is the unique name of the stored service template.
"""
service_template = model_storage.service_template.get_by_name(service_template_name)
@@ -94,14 +99,15 @@ def show(service_template_name, model_storage, mode_full, mode_types, format_jso
@service_templates.command(name='list',
- short_help='List service templates')
+ short_help='List all stored service templates')
@aria.options.sort_by()
@aria.options.descending
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def list(sort_by, descending, model_storage, logger):
- """List all service templates
+ """
+ List all stored service templates
"""
logger.info('Listing all service templates...')
@@ -115,7 +121,7 @@ def list(sort_by, descending, model_storage, logger):
@service_templates.command(name='store',
- short_help='Store a service template')
+ short_help='Parse and store a service template archive')
@aria.argument('service-template-path')
@aria.argument('service-template-name')
@aria.options.service_template_filename
@@ -126,11 +132,12 @@ def list(sort_by, descending, model_storage, logger):
@aria.pass_logger
def store(service_template_path, service_template_name, service_template_filename,
model_storage, resource_storage, plugin_manager, logger):
- """Store a service template
+ """
+ Parse and store a service template archive
- `SERVICE_TEMPLATE_PATH` is the path of the service template to store.
+ SERVICE_TEMPLATE_PATH is the path to the service template archive.
- `SERVICE_TEMPLATE_NAME` is the name of the service template to store.
+ SERVICE_TEMPLATE_NAME is the unique name to give to the service template in storage.
"""
logger.info('Storing service template {0}...'.format(service_template_name))
@@ -148,7 +155,7 @@ def store(service_template_path, service_template_name, service_template_filenam
@service_templates.command(name='delete',
- short_help='Delete a service template')
+ short_help='Delete a stored service template')
@aria.argument('service-template-name')
@aria.options.verbose()
@aria.pass_model_storage
@@ -156,9 +163,10 @@ def store(service_template_path, service_template_name, service_template_filenam
@aria.pass_plugin_manager
@aria.pass_logger
def delete(service_template_name, model_storage, resource_storage, plugin_manager, logger):
- """Delete a service template
+ """
+ Delete a stored service template
- `SERVICE_TEMPLATE_NAME` is the name of the service template to delete.
+ SERVICE_TEMPLATE_NAME is the unique name of the stored service template.
"""
logger.info('Deleting service template {0}...'.format(service_template_name))
service_template = model_storage.service_template.get_by_name(service_template_name)
@@ -168,22 +176,23 @@ def delete(service_template_name, model_storage, resource_storage, plugin_manage
@service_templates.command(name='inputs',
- short_help='Show service template inputs')
+ short_help='Show stored service template inputs')
@aria.argument('service-template-name')
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def inputs(service_template_name, model_storage, logger):
- """Show inputs for a specific service template
+ """
+ Show stored service template inputs
- `SERVICE_TEMPLATE_NAME` is the name of the service template to show inputs for.
+ SERVICE_TEMPLATE_NAME is the unique name of the stored service template.
"""
logger.info('Showing inputs for service template {0}...'.format(service_template_name))
print_service_template_inputs(model_storage, service_template_name, logger)
@service_templates.command(name='validate',
- short_help='Validate a service template')
+ short_help='Validate a service template archive')
@aria.argument('service-template')
@aria.options.service_template_filename
@aria.options.verbose()
@@ -193,9 +202,10 @@ def inputs(service_template_name, model_storage, logger):
@aria.pass_logger
def validate(service_template, service_template_filename,
model_storage, resource_storage, plugin_manager, logger):
- """Validate a service template
+ """
+ Validate a service template archive
- `SERVICE_TEMPLATE` is the path or URL of the service template or archive to validate.
+ SERVICE_TEMPLATE_PATH is the path to the service template archive.
"""
logger.info('Validating service template: {0}'.format(service_template))
service_template_path = service_template_utils.get(service_template, service_template_filename)
@@ -205,16 +215,18 @@ def validate(service_template, service_template_filename,
@service_templates.command(name='create-archive',
- short_help='Create a CSAR archive')
+ short_help='Create a CSAR archive from a service template source')
@aria.argument('service-template-path')
@aria.argument('destination')
@aria.options.verbose()
@aria.pass_logger
def create_archive(service_template_path, destination, logger):
- """Create a CSAR archive
+ """
+ Create a CSAR archive from a service template source
+
+ SERVICE_TEMPLATE_PATH is the path to the service template source.
- `service_template_path` is the path of the service template to create the archive from
- `destination` is the path of the output CSAR archive
+ DESTINATION is the path to the created CSAR archive.
"""
logger.info('Creating a CSAR archive')
if not destination.endswith(csar.CSAR_FILE_EXTENSION):
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/services.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/services.py b/aria/cli/commands/services.py
index ae5895a..a99f5b3 100644
--- a/aria/cli/commands/services.py
+++ b/aria/cli/commands/services.py
@@ -13,6 +13,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI ``services`` sub-commands.
+"""
import os
from StringIO import StringIO
@@ -36,13 +39,14 @@ SERVICE_COLUMNS = ('id', 'name', 'description', 'service_template_name', 'create
@aria.group(name='services')
@aria.options.verbose()
def services():
- """Handle services
+ """
+ Manage services
"""
pass
@services.command(name='show',
- short_help='Display service information')
+ short_help='Show information for a service')
@aria.argument('service-name')
@aria.options.verbose()
@aria.options.service_mode_full
@@ -52,9 +56,10 @@ def services():
@aria.pass_model_storage
@aria.pass_logger
def show(service_name, model_storage, mode_full, mode_graph, format_json, format_yaml, logger):
- """Show information for a specific service template
+ """
+ Show information for a service
- `SERVICE_NAME` is the name of the service to display information on.
+ SERVICE_NAME is the unique name of the service.
"""
service = model_storage.service.get_by_name(service_name)
@@ -99,10 +104,11 @@ def list(service_template_name,
descending,
model_storage,
logger):
- """List services
+ """
+ List services
- If `--service-template-name` is provided, list services for that service template.
- Otherwise, list services for all service templates.
+ If `--service-template-name` is provided, list services based on that service template.
+ Otherwise, list all services.
"""
if service_template_name:
logger.info('Listing services for service template {0}...'.format(
@@ -120,7 +126,7 @@ def list(service_template_name,
@services.command(name='create',
- short_help='Create a services')
+ short_help='Create a service')
@aria.argument('service-name', required=False)
@aria.options.service_template_name(required=True)
@aria.options.inputs(help=helptexts.SERVICE_INPUTS)
@@ -136,10 +142,10 @@ def create(service_template_name,
resource_storage,
plugin_manager,
logger):
- """Create a service
-
- `SERVICE_NAME` is the name of the service you'd like to create.
+ """
+ Create a service
+ SERVICE_NAME is the unique name to give to the service.
"""
logger.info('Creating new service from service template {0}...'.format(
service_template_name))
@@ -168,9 +174,10 @@ def create(service_template_name,
@aria.pass_plugin_manager
@aria.pass_logger
def delete(service_name, force, model_storage, resource_storage, plugin_manager, logger):
- """Delete a service
+ """
+ Delete a service
- `SERVICE_NAME` is the name of the service to delete.
+ SERVICE_NAME is the unique name of the service.
"""
logger.info('Deleting service {0}...'.format(service_name))
service = model_storage.service.get_by_name(service_name)
@@ -186,9 +193,10 @@ def delete(service_name, force, model_storage, resource_storage, plugin_manager,
@aria.pass_model_storage
@aria.pass_logger
def outputs(service_name, model_storage, logger):
- """Show outputs for a specific service
+ """
+ Show service outputs
- `SERVICE_NAME` is the name of the service to print outputs for.
+ SERVICE_NAME is the unique name of the service.
"""
logger.info('Showing outputs for service {0}...'.format(service_name))
service = model_storage.service.get_by_name(service_name)
@@ -211,9 +219,10 @@ def outputs(service_name, model_storage, logger):
@aria.pass_model_storage
@aria.pass_logger
def inputs(service_name, model_storage, logger):
- """Show inputs for a specific service
+ """
+ Show service inputs
- `SERVICE_NAME` is the id of the service to print inputs for.
+ SERVICE_NAME is the unique name of the service.
"""
logger.info('Showing inputs for service {0}...'.format(service_name))
service = model_storage.service.get_by_name(service_name)
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/commands/workflows.py
----------------------------------------------------------------------
diff --git a/aria/cli/commands/workflows.py b/aria/cli/commands/workflows.py
index 221dbc4..03cf00e 100644
--- a/aria/cli/commands/workflows.py
+++ b/aria/cli/commands/workflows.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI ``worfklows`` sub-commands.
+"""
+
from .. import table
from ..core import aria
from ..exceptions import AriaCliError
@@ -22,22 +26,26 @@ WORKFLOW_COLUMNS = ['name', 'service_template_name', 'service_name']
@aria.group(name='workflows')
def workflows():
- """Handle service workflows
+ """
+ Manage service workflows
"""
pass
@workflows.command(name='show',
- short_help='Show workflow information')
+ short_help='Show information for a service workflow')
@aria.argument('workflow-name')
@aria.options.service_name(required=True)
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def show(workflow_name, service_name, model_storage, logger):
- """Show information for a specific workflow of a specific service
+ """
+ Show information for a service workflow
- `WORKFLOW_NAME` is the name of the workflow to get information on.
+ SERVICE_NAME is the unique name of the service.
+
+ WORKFLOW_NAME is the unique name of the workflow within the service (e.g. "uninstall").
"""
logger.info('Retrieving workflow {0} for service {1}'.format(
workflow_name, service_name))
@@ -81,13 +89,16 @@ def show(workflow_name, service_name, model_storage, logger):
@workflows.command(name='list',
- short_help='List workflows for a service')
+ short_help='List service workflows')
@aria.options.service_name(required=True)
@aria.options.verbose()
@aria.pass_model_storage
@aria.pass_logger
def list(service_name, model_storage, logger):
- """List all workflows of a specific service
+ """
+ List service workflows
+
+ SERVICE_NAME is the unique name of the service.
"""
logger.info('Listing workflows for service {0}...'.format(service_name))
service = model_storage.service.get_by_name(service_name)
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/config/__init__.py
----------------------------------------------------------------------
diff --git a/aria/cli/config/__init__.py b/aria/cli/config/__init__.py
index ae1e83e..738e8ed 100644
--- a/aria/cli/config/__init__.py
+++ b/aria/cli/config/__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.
+
+"""
+CLI configuration package.
+"""
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/config/config.py
----------------------------------------------------------------------
diff --git a/aria/cli/config/config.py b/aria/cli/config/config.py
index d584fad..bbece80 100644
--- a/aria/cli/config/config.py
+++ b/aria/cli/config/config.py
@@ -13,6 +13,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI configuration mechanism.
+"""
import os
import pkg_resources
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/core/__init__.py
----------------------------------------------------------------------
diff --git a/aria/cli/core/__init__.py b/aria/cli/core/__init__.py
index ae1e83e..88a9801 100644
--- a/aria/cli/core/__init__.py
+++ b/aria/cli/core/__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.
+
+"""
+CLI core package.
+"""
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/core/aria.py
----------------------------------------------------------------------
diff --git a/aria/cli/core/aria.py b/aria/cli/core/aria.py
index e5b3eb2..515c06a 100644
--- a/aria/cli/core/aria.py
+++ b/aria/cli/core/aria.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Enhancements and ARIA-specific conveniences for `Click <http://click.pocoo.org>`__.
+"""
+
import os
import sys
import difflib
@@ -227,9 +231,8 @@ class AliasedGroup(click.Group):
def resolve_command(self, ctx, args):
"""
- Override clicks ``resolve_command`` method
- and appends *Did you mean ...* suggestions
- to the raised exception message.
+ Override clicks ``resolve_command`` method and appends *Did you mean ...* suggestions to the
+ raised exception message.
"""
try:
return super(AliasedGroup, self).resolve_command(ctx, args)
@@ -250,7 +253,7 @@ class AliasedGroup(click.Group):
def group(name):
"""
- Allow to create a group with a default click context and a cls for click's ``didyoueamn``
+ Allow to create a group with a default click context and a class for Click's ``didyoueamn``
without having to repeat it for every group.
"""
return click.group(
@@ -271,7 +274,7 @@ def command(*args, **kwargs):
def argument(*args, **kwargs):
"""
- Make Click arguments ARIA specific.
+ Make Click arguments specific to ARIA.
This exists purely for aesthetic reasons, otherwise some decorators are called
``@click.something`` instead of ``@aria.something``
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/csar.py
----------------------------------------------------------------------
diff --git a/aria/cli/csar.py b/aria/cli/csar.py
index 8f44557..40b1699 100644
--- a/aria/cli/csar.py
+++ b/aria/cli/csar.py
@@ -13,6 +13,13 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Support for the CSAR (Cloud Service ARchive) packaging specification.
+
+See the `TOSCA Simple Profile v1.0 cos01 specification <http://docs.oasis-open.org/tosca
+/TOSCA-Simple-Profile-YAML/v1.0/cos01/TOSCA-Simple-Profile-YAML-v1.0-cos01.html#_Toc461787381>`__
+"""
+
import os
import logging
import pprint
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/defaults.py
----------------------------------------------------------------------
diff --git a/aria/cli/defaults.py b/aria/cli/defaults.py
index 5c16938..e84abc0 100644
--- a/aria/cli/defaults.py
+++ b/aria/cli/defaults.py
@@ -13,8 +13,18 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Various CLI default values.
+"""
+#: Default service template filename
SERVICE_TEMPLATE_FILENAME = 'service_template.yaml'
+
+#: Default task max attempts
TASK_MAX_ATTEMPTS = 30
+
+#: Default task retry interval
TASK_RETRY_INTERVAL = 30
+
+#: Default sort descending
SORT_DESCENDING = False
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/env.py
----------------------------------------------------------------------
diff --git a/aria/cli/env.py b/aria/cli/env.py
index 52a4ec6..84bdebe 100644
--- a/aria/cli/env.py
+++ b/aria/cli/env.py
@@ -13,6 +13,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Environment (private)
+"""
import os
import shutil
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/cli/exceptions.py b/aria/cli/exceptions.py
index 89cfacd..7da9836 100644
--- a/aria/cli/exceptions.py
+++ b/aria/cli/exceptions.py
@@ -13,6 +13,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+CLI exceptions.
+"""
from ..exceptions import AriaError
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/execution_logging.py
----------------------------------------------------------------------
diff --git a/aria/cli/execution_logging.py b/aria/cli/execution_logging.py
index 248ff7c..af40e01 100644
--- a/aria/cli/execution_logging.py
+++ b/aria/cli/execution_logging.py
@@ -12,6 +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.
+
+"""
+Formatting for ``executions`` sub-commands.
+"""
+
import os
import re
from StringIO import StringIO
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/helptexts.py
----------------------------------------------------------------------
diff --git a/aria/cli/helptexts.py b/aria/cli/helptexts.py
index 74934db..a5d41e8 100644
--- a/aria/cli/helptexts.py
+++ b/aria/cli/helptexts.py
@@ -13,10 +13,13 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Gathers all CLI command help texts in one place.
+"""
DEFAULT_MUTUALITY_ERROR_MESSAGE = 'mutually exclusive'
VERBOSE = \
- "Show verbose output. You can supply this up to three times (i.e. -vvv)"
+ "Show verbose output; you can supply this up to three times (i.e. -vvv)"
VERSION = "Display the version and exit"
FORCE_RESET = "Confirmation for resetting ARIA's working directory"
@@ -28,12 +31,12 @@ EXECUTION_ID = "The unique identifier for the execution"
SERVICE_TEMPLATE_PATH = "The path to the application's service template file"
SERVICE_TEMPLATE_FILENAME = (
- "The name of the archive's main service template file. "
- "This is only relevant if uploading a (non-CSAR) archive")
+ "The name of the archive's main service template file "
+ "(only relevant if uploading a non-CSAR archive)")
INPUTS_PARAMS_USAGE = (
- '(Can be provided as wildcard based paths '
- '(*.yaml, /my_inputs/, etc..) to YAML files, a JSON string or as '
- 'key1=value1;key2=value2). This argument can be used multiple times')
+ '(can be provided as wildcard based paths '
+ '("inp?.yaml", "/my_inputs/", etc.) to YAML files, a JSON string or as '
+ '"key1=value1;key2=value2"); this argument can be used multiple times')
SERVICE_INPUTS = "Inputs for the service {0}".format(INPUTS_PARAMS_USAGE)
EXECUTION_INPUTS = "Inputs for the execution {0}".format(INPUTS_PARAMS_USAGE)
@@ -46,8 +49,8 @@ DRY_EXECUTION = "Execute a workflow dry run (prints operations information witho
IGNORE_AVAILABLE_NODES = "Delete the service even if it has available nodes"
SORT_BY = "Key for sorting the list"
DESCENDING = "Sort list in descending order [default: False]"
-JSON_OUTPUT = "Output logs in a consumable JSON format"
-MARK_PATTERN = "Mark a regex pattern in the logs"
+JSON_OUTPUT = "Output logs in JSON format"
+MARK_PATTERN = "Mark a regular expression pattern in the logs"
SHOW_FULL = "Show full information"
SHOW_JSON = "Show in JSON format (implies --full)"
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/inputs.py
----------------------------------------------------------------------
diff --git a/aria/cli/inputs.py b/aria/cli/inputs.py
index 4d46ebb..bea3e1a 100644
--- a/aria/cli/inputs.py
+++ b/aria/cli/inputs.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Helpers for validating and coercing service template inputs.
+"""
+
import os
import glob
from ruamel import yaml
@@ -22,15 +26,17 @@ from .exceptions import AriaCliError
def inputs_to_dict(resources):
- """Returns a dictionary of inputs
-
- `resources` can be:
- - A list of files.
- - A single file
- - A directory containing multiple input files
- - A key1=value1;key2=value2 pairs string.
- - A string formatted as JSON/YAML.
- - Wildcard based string (e.g. *-inputs.yaml)
+ """
+ Returns a dictionary of inputs
+
+ :param resources: can be:
+
+ * list of files
+ * single file
+ * directory containing multiple input files
+ * ``key1=value1;key2=value2`` pairs string.
+ * string formatted as JSON/YAML
+ * wildcard based string (e.g. ``*-inputs.yaml``)
"""
if not resources:
return dict()
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/logger.py
----------------------------------------------------------------------
diff --git a/aria/cli/logger.py b/aria/cli/logger.py
index 96f3fb3..14baae0 100644
--- a/aria/cli/logger.py
+++ b/aria/cli/logger.py
@@ -13,6 +13,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Centralized logging configuration and formatting.
+"""
import os
import copy
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/main.py
----------------------------------------------------------------------
diff --git a/aria/cli/main.py b/aria/cli/main.py
index 02cf095..640360b 100644
--- a/aria/cli/main.py
+++ b/aria/cli/main.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Executable entry point into the CLI.
+"""
+
from aria import install_aria_extensions
from aria.cli import commands
from aria.cli.core import aria
@@ -22,12 +26,15 @@ from aria.cli.core import aria
@aria.options.verbose()
@aria.options.version
def _aria():
- """ARIA's Command Line Interface
+ """
+ ARIA's Command Line Interface.
+
+ To activate bash-completion run::
- To activate bash-completion. Run: `eval "$(_ARIA_COMPLETE=source aria)"`
+ eval "$(_ARIA_COMPLETE=source aria)"
- ARIA's working directory resides by default in ~/.aria. To change it, set
- the environment variable `ARIA_WORKDIR` to something else (e.g. /tmp/).
+ ARIA's working directory resides by default in "~/.aria". To change it, set the environment
+ variable ARIA_WORKDIR to something else (e.g. "/tmp/").
"""
aria.set_cli_except_hook()
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/service_template_utils.py
----------------------------------------------------------------------
diff --git a/aria/cli/service_template_utils.py b/aria/cli/service_template_utils.py
index c953c02..5312522 100644
--- a/aria/cli/service_template_utils.py
+++ b/aria/cli/service_template_utils.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Loading mechanism for service templates.
+"""
+
import os
from urlparse import urlparse
@@ -23,26 +27,24 @@ from ..utils import archive as archive_utils
def get(source, service_template_filename):
- """Get a source and return a path to the main service template file
+ """
+ Get a source and return a path to the main service template file
The behavior based on then source argument content is:
- - local yaml file: return the file
- - local archive:
- extract it locally and return path service template file
- - URL:
- - download and get service template from downloaded archive
- - github repo:
- - download and get service template from downloaded archive
-
- Supported archive types are: csar, zip, tar, tar.gz and tar.bz2
-
- :param source: Path/URL/github repo to archive/service-template file
- :type source: str
- :param service_template_filename: Path to service template (if source is an archive [but
- not a csar archive - with csars archives, this is read from the metadata file])
- :type service_template_filename: str
- :return: Path to main service template file
- :rtype: str
+
+ * local ``.yaml`` file: return the file
+ * local archive (``.csar``, ``.zip``, ``.tar``, ``.tar.gz``, and ``.tar.bz2``): extract it
+ locally and return path service template file
+ * URL: download and get service template from downloaded archive
+ * GitHub repo: download and get service template from downloaded archive
+
+ :param source: path/URL/GitHub repo to archive/service-template file
+ :type source: basestring
+ :param service_template_filename: path to service template if source is a non-CSAR archive
+ with CSAR archives, this is read from the metadata file)
+ :type service_template_filename: basestring
+ :return: path to main service template file
+ :rtype: basestring
"""
if urlparse(source).scheme:
downloaded_file = utils.download_file(source)
@@ -66,14 +68,15 @@ def get(source, service_template_filename):
def _get_service_template_file_from_archive(archive, service_template_filename):
- """Extract archive to temporary location and get path to service template file.
+ """
+ Extract archive to temporary location and get path to service template file.
- :param archive: Path to archive file
- :type archive: str
- :param service_template_filename: Path to service template file relative to archive
- :type service_template_filename: str
- :return: Absolute path to service template file
- :rtype: str
+ :param archive: path to archive file
+ :type archive: basestring
+ :param service_template_filename: path to service template file relative to archive
+ :type service_template_filename: basestring
+ :return: absolute path to service template file
+ :rtype: basestring
"""
if csar.is_csar_archive(archive):
@@ -95,12 +98,13 @@ def _get_service_template_file_from_archive(archive, service_template_filename):
def _map_to_github_url(source):
- """Returns a path to a downloaded github archive.
+ """
+ Returns a path to a downloaded GitHub archive.
- :param source: github repo in the format of `org/repo[:tag/branch]`.
- :type source: str
- :return: URL to the archive file for the given repo in github
- :rtype: str
+ :param source: GitHub repo: ``org/repo[:tag/branch]``
+ :type source: basestring
+ :return: URL to the archive file for the given repo in GitHub
+ :rtype: basestring
"""
source_parts = source.split(':', 1)
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/table.py
----------------------------------------------------------------------
diff --git a/aria/cli/table.py b/aria/cli/table.py
index d984c87..74487ae 100644
--- a/aria/cli/table.py
+++ b/aria/cli/table.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Tabular formatting utilities.
+"""
+
import os
from datetime import datetime
@@ -23,6 +27,23 @@ from .env import logger
def print_data(columns, items, header_text,
column_formatters=None, col_max_width=None, defaults=None):
+ """
+ Prints data in a tabular form.
+
+ :param columns: columns of the table, e.g. ``['id','name']``
+ :type columns: iterable of basestring
+ :param items: each element must have keys or attributes corresponding to the ``columns`` items,
+ e.g. ``[{'id':'123', 'name':'Pete'}]``
+ :type data: [{:obj:`basestring`: :obj:`basestring`}]
+ :param column_formatters: maps column name to formatter, a function that may manipulate the
+ string values printed for this column, e.g. ``{'created_at': timestamp_formatter}``
+ :type column_formatters: {:obj:`basestring`: :obj:`function`}
+ :param col_max_width: maximum width of table
+ :type col_max_width: int
+ :param defaults: default values for keys that don't exist in the data itself, e.g.
+ ``{'serviceId':'123'}``
+ :type defaults: {:obj:`basestring`: :obj:`basestring`}
+ """
if items is None:
items = []
elif not isinstance(items, list):
@@ -43,30 +64,17 @@ def _generate(cols, data, column_formatters=None, defaults=None):
"""
Return a new PrettyTable instance representing the list.
- Arguments:
-
- cols - An iterable of strings that specify what
- are the columns of the table.
-
- for example: ['id','name']
-
- data - An iterable of dictionaries or objects, each element must
- have keys or attributes corresponding to the cols items.
-
- for example: [{'id':'123', 'name':'Pete'}]
-
- column_formatters - A dictionary from a column name to a formatter - a function that
- may manipulate the string values printed for this column.
- (See below for a few built-in formatter examples)
-
- for example: {'created_at': timestamp_formatter}
-
- defaults - A dictionary specifying default values for
- key's that don't exist in the data itself.
-
- for example: {'serviceId':'123'} will set the
- serviceId value for all rows to '123'.
-
+ :param cols: columns of the table, e.g. ``['id','name']``
+ :type cols: iterable of :obj:`basestring`
+ :param data: each element must have keys or attributes corresponding to the ``cols`` items,
+ e.g. ``[{'id':'123', 'name':'Pete'}]``
+ :type data: [{:obj:`basestring`: :obj:`basestring`}]
+ :param column_formatters: maps column name to formatter, a function that may manipulate the
+ string values printed for this column, e.g. ``{'created_at': timestamp_formatter}``
+ :type column_formatters: {:obj:`basestring`: :obj:`function`}
+ :param defaults: default values for keys that don't exist in the data itself, e.g.
+ ``{'serviceId':'123'}``
+ :type defaults: {:obj:`basestring`: :obj:`basestring`}
"""
def get_values_per_column(column, row_data):
if hasattr(row_data, column) or (isinstance(row_data, dict) and column in row_data):
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/cli/utils.py
----------------------------------------------------------------------
diff --git a/aria/cli/utils.py b/aria/cli/utils.py
index 852f24d..697ff37 100644
--- a/aria/cli/utils.py
+++ b/aria/cli/utils.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Miscellaneous CLI utilities.
+"""
+
import os
import sys
from StringIO import StringIO
@@ -44,8 +48,8 @@ def get_parameter_templates_as_string(parameter_templates):
def check_overriding_storage_exceptions(e, model_class, name):
"""
- This method checks whether the storage exception is a known type where we'd like to override
- the exception message; If so, it raises a new error. Otherwise it simply returns.
+ Checks whether the storage exception is a known type where we'd like to override the exception
+ message; If so, it raises a new error. Otherwise it simply returns.
"""
assert isinstance(e, BaseException)
if 'UNIQUE constraint failed' in e.message:
@@ -68,15 +72,16 @@ def download_file(url):
def generate_progress_handler(file_path, action='', max_bar_length=80):
- """Returns a function that prints a progress bar in the terminal
+ """
+ Returns a function that prints a progress bar in the terminal.
- :param file_path: The name of the file being transferred
- :param action: Uploading/Downloading
- :param max_bar_length: Maximum allowed length of the bar. Default: 80
- :return: The configured print_progress function
+ :param file_path: the name of the file being transferred
+ :param action: uploading/downloading
+ :param max_bar_length: maximum allowed length of the bar
+ :return: configured ``print_progress`` function
"""
- # We want to limit the maximum line length to 80, but allow for a smaller
- # terminal size. We also include the action string, and some extra chars
+ # We want to limit the maximum line length to 80, but allow for a smaller terminal size. We also
+ # include the action string, and some extra chars
terminal_width = get_terminal_size().columns
# This takes care of the case where there is no terminal (e.g. unittest)
@@ -91,24 +96,21 @@ def generate_progress_handler(file_path, action='', max_bar_length=80):
bar_length -= len(file_name)
def print_progress(read_bytes, total_bytes):
- """Print upload/download progress on a single line
+ """
+ Print upload/download progress on a single line.
- Call this function in a loop to create a progress bar in the terminal
+ Call this function in a loop to create a progress bar in the terminal.
- :param read_bytes: Number of bytes already processed
- :param total_bytes: Total number of bytes in the file
+ :param read_bytes: number of bytes already processed
+ :param total_bytes: total number of bytes in the file
"""
- filled_length = min(bar_length, int(round(bar_length * read_bytes /
- float(total_bytes))))
- percents = min(100.00, round(
- 100.00 * (read_bytes / float(total_bytes)), 2))
+ filled_length = min(bar_length, int(round(bar_length * read_bytes / float(total_bytes))))
+ percents = min(100.00, round(100.00 * (read_bytes / float(total_bytes)), 2))
bar = '#' * filled_length + '-' * (bar_length - filled_length) # pylint: disable=blacklisted-name
- # The \r caret makes sure the cursor moves back to the beginning of
- # the line
- sys.stdout.write('\r{0} {1} |{2}| {3}%'.format(
- action, file_name, bar, percents))
+ # The \r caret makes sure the cursor moves back to the beginning of the line
+ sys.stdout.write('\r{0} {1} |{2}| {3}%'.format(action, file_name, bar, percents))
if read_bytes >= total_bytes:
sys.stdout.write(os.linesep)
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/core.py
----------------------------------------------------------------------
diff --git a/aria/core.py b/aria/core.py
index f660167..a8d5245 100644
--- a/aria/core.py
+++ b/aria/core.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+ARIA core module.
+"""
+
from . import exceptions
from .parser import consumption
from .parser.loading.location import UriLocation
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/exceptions.py b/aria/exceptions.py
index 93987dc..5d3e21d 100644
--- a/aria/exceptions.py
+++ b/aria/exceptions.py
@@ -14,9 +14,7 @@
# limitations under the License.
"""
-ARIA exceptions module
-Every sub-package in ARIA has a module with its exceptions.
-aria.exceptions module conveniently collects all these exceptions for easier imports.
+Base exception classes and other common exceptions used throughout ARIA.
"""
import sys
@@ -48,21 +46,21 @@ class AriaException(Exception):
class DependentServicesError(AriaError):
"""
- Raised when attempting to delete a service template which has existing services
+ Raised when attempting to delete a service template which has existing services.
"""
pass
class DependentActiveExecutionsError(AriaError):
"""
- Raised when attempting to delete a service which has active executions
+ Raised when attempting to delete a service which has active executions.
"""
pass
class DependentAvailableNodesError(AriaError):
"""
- Raised when attempting to delete a service which has available nodes
+ Raised when attempting to delete a service which has available nodes.
"""
pass
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/extension.py
----------------------------------------------------------------------
diff --git a/aria/extension.py b/aria/extension.py
index 4dba74f..e90750d 100644
--- a/aria/extension.py
+++ b/aria/extension.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Mechanism for registering and loading ARIA extensions.
+"""
+
# pylint: disable=no-self-use
from .utils import collections
@@ -49,7 +53,9 @@ def _registrar(function):
class _ExtensionRegistration(object):
- """Base class for extension class decorators"""
+ """
+ Base class for extension class decorators.
+ """
def __init__(self):
self._registrars = {}
@@ -70,7 +76,7 @@ class _ExtensionRegistration(object):
def init(self):
"""
- Initialize all registrars by calling all registered functions
+ Initialize all registrars by calling all registered functions.
"""
registered_instances = [cls() for cls in self._registered_classes]
for name, registrar in self._registrars.items():
@@ -81,13 +87,16 @@ class _ExtensionRegistration(object):
class _ParserExtensionRegistration(_ExtensionRegistration):
- """Parser extensions class decorator"""
+ """
+ Parser extensions class decorator.
+ """
@_registrar
def presenter_class(self):
"""
Presentation class registration.
- Implementing functions can return a single class or a list/tuple of classes
+
+ Implementing functions can return a single class or a list/tuple of classes.
"""
return []
@@ -95,7 +104,8 @@ class _ParserExtensionRegistration(_ExtensionRegistration):
def specification_package(self):
"""
Specification package registration.
- Implementing functions can return a package name or a list/tuple of names
+
+ Implementing functions can return a package name or a list/tuple of names.
"""
return []
@@ -103,7 +113,8 @@ class _ParserExtensionRegistration(_ExtensionRegistration):
def specification_url(self):
"""
Specification URL registration.
- Implementing functions should return a dictionary from names to URLs
+
+ Implementing functions should return a dictionary from names to URLs.
"""
return {}
@@ -111,7 +122,8 @@ class _ParserExtensionRegistration(_ExtensionRegistration):
def uri_loader_prefix(self):
"""
URI loader prefix registration.
- Implementing functions can return a single prefix or a list/tuple of prefixes
+
+ Implementing functions can return a single prefix or a list/tuple of prefixes.
"""
return collections.StrictList(value_class=basestring)
@@ -119,13 +131,15 @@ parser = _ParserExtensionRegistration()
class _ProcessExecutorExtensionRegistration(_ExtensionRegistration):
- """Process executor extension class decorator"""
+ """
+ Process executor extension class decorator.
+ """
@_registrar
def decorate(self):
"""
The operation function executed by the process executor will be decorated with the function
- returned from decorate().
+ returned from ``decorate()``.
"""
return []
@@ -134,7 +148,7 @@ process_executor = _ProcessExecutorExtensionRegistration()
def init():
"""
- Initialize all registrars by calling all registered functions
+ Initialize all registrars by calling all registered functions.
"""
parser.init()
process_executor.init()
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/logger.py
----------------------------------------------------------------------
diff --git a/aria/logger.py b/aria/logger.py
index bd7ed4e..f4f6ec9 100644
--- a/aria/logger.py
+++ b/aria/logger.py
@@ -14,7 +14,8 @@
# limitations under the License.
"""
-Logging related mixins and functions
+Mix-ins and functions for logging, supporting multiple backends (such as SQL) and consistent
+formatting.
"""
import logging
@@ -38,12 +39,11 @@ _base_logger = logging.getLogger('aria')
class LoggerMixin(object):
"""
- Mixin Logger Class
- configuration (class members):
- logger_name: logger name [default: <class_name>]
- logger_level: logger level [default: logging.DEBUG]
- base_logger: This Mixing will create child logger from this base_logger
- [default: root logger]
+ 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 base_logger: child loggers are created from this; defaults to the root logger
"""
logger_name = None
logger_level = logging.DEBUG
@@ -66,7 +66,7 @@ class LoggerMixin(object):
base_logger=logging.getLogger(),
**kwargs):
"""
- Set the logger used by the consuming class
+ Set the logger used by the consuming class.
"""
cls.logger_name = logger_name
cls.logger_level = logger_level
@@ -86,10 +86,12 @@ class LoggerMixin(object):
def create_logger(logger=_base_logger, handlers=(), **configs):
"""
-
- :param logging.Logger logger: The logger name [default: aria logger]
- :param list handlers: The logger handlers
- :param configs: The logger configurations
+ :param logger: logger name; defaults to ARIA logger
+ :type logger: logging.Logger
+ :param handlers: logger handlers
+ :type handlers: []
+ :param configs: logger configurations
+ :type configs: []
:return: logger
"""
logger.handlers = []
@@ -103,10 +105,8 @@ def create_logger(logger=_base_logger, handlers=(), **configs):
def create_console_log_handler(level=logging.DEBUG, formatter=None):
"""
-
:param level:
:param formatter:
- :return:
"""
console = logging.StreamHandler()
console.setLevel(level)
@@ -123,10 +123,9 @@ def create_sqla_log_handler(model, log_cls, execution_id, level=logging.DEBUG):
class _DefaultConsoleFormat(logging.Formatter):
"""
- _DefaultConsoleFormat class
- Console logger formatter
- info level logs format: '%(message)s'
- every other log level are formatted: '%(levelname)s: %(message)s'
+ Info level log format: ``%(message)s``.
+
+ Every other log level is formatted: ``%(levelname)s: %(message)s``.
"""
def format(self, record):
try:
@@ -147,7 +146,7 @@ def create_file_log_handler(
backup_count=10,
formatter=None):
"""
- Create a logging.handlers.RotatingFileHandler
+ Create a :class:`logging.handlers.RotatingFileHandler`.
"""
rotating_file = logging_handlers.RotatingFileHandler(
filename=file_path,
@@ -161,7 +160,6 @@ def create_file_log_handler(
class _SQLAlchemyHandler(logging.Handler):
-
def __init__(self, model, log_cls, execution_id, **kwargs):
logging.Handler.__init__(self, **kwargs)
self._model = model
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/modeling/__init__.py
----------------------------------------------------------------------
diff --git a/aria/modeling/__init__.py b/aria/modeling/__init__.py
index 4ac79e7..57bc188 100644
--- a/aria/modeling/__init__.py
+++ b/aria/modeling/__init__.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+This package provides an API for modeling ARIA's state and serializing it to storage.
+"""
+
from collections import namedtuple
from . import (
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/modeling/constraints.py
----------------------------------------------------------------------
diff --git a/aria/modeling/constraints.py b/aria/modeling/constraints.py
index 107b010..8ed33d5 100644
--- a/aria/modeling/constraints.py
+++ b/aria/modeling/constraints.py
@@ -13,6 +13,9 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Constraints for the requirements-and-capabilities matching mechanism.
+"""
class NodeTemplateConstraint(object):
"""
@@ -23,6 +26,6 @@ class NodeTemplateConstraint(object):
def matches(self, source_node_template, target_node_template):
"""
- Returns true is the target matches the constraint for the source.
+ Returns ``True`` if the target matches the constraint for the source.
"""
raise NotImplementedError
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/modeling/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/modeling/exceptions.py b/aria/modeling/exceptions.py
index d0e3e22..573efaf 100644
--- a/aria/modeling/exceptions.py
+++ b/aria/modeling/exceptions.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Modeling exceptions.
+"""
+
from ..exceptions import AriaException
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/8eef8ed9/aria/modeling/functions.py
----------------------------------------------------------------------
diff --git a/aria/modeling/functions.py b/aria/modeling/functions.py
index 06fd19f..6544adf 100644
--- a/aria/modeling/functions.py
+++ b/aria/modeling/functions.py
@@ -13,6 +13,10 @@
# See the License for the specific language governing permissions and
# limitations under the License.
+"""
+Mechanism for evaluating intrinsic functions.
+"""
+
from ..parser.consumption import ConsumptionContext
from ..parser.exceptions import InvalidValueError
from ..utils.collections import OrderedDict
@@ -34,10 +38,11 @@ class Function(object):
def __evaluate__(self, container_holder):
"""
- Evaluates the function if possible. If impossible, raises
- :class:`CannotEvaluateFunctionException` (do not just return None).
+ Evaluates the function if possible.
- :rtype: Evaluation (or any object with ``value`` and ``final`` properties)
+ :rtype: :class:`Evaluation` (or any object with ``value`` and ``final`` properties)
+ :raises CannotEvaluateFunctionException: if cannot be evaluated at this time (do *not* just
+ return ``None``)
"""
raise NotImplementedError
@@ -50,6 +55,10 @@ class Function(object):
class Evaluation(object):
"""
An evaluated :class:`Function` return value.
+
+ :ivar value: evaluated value
+ :ivar final: whether the value is final
+ :vartype final: boolean
"""
def __init__(self, value, final=False):
@@ -60,13 +69,13 @@ class Evaluation(object):
def evaluate(value, container_holder, report_issues=False): # pylint: disable=too-many-branches
"""
Recursively attempts to call ``__evaluate__``. If an evaluation occurred will return an
- :class:`Evaluation`, otherwise it will be None. If any evaluation is non-final, then the entire
- evaluation will also be non-final.
+ :class:`Evaluation`, otherwise it will be ``None``. If any evaluation is non-final, then the
+ entire evaluation will also be non-final.
The ``container_holder`` argument should have three properties: ``container`` should return
the model that contains the value, ``service`` should return the containing
- :class:`aria.modeling.models.Service` model or None, and ``service_template`` should return the
- containing :class:`aria.modeling.models.ServiceTemplate` model or None.
+ :class:`~aria.modeling.models.Service` model or None, and ``service_template`` should return the
+ containing :class:`~aria.modeling.models.ServiceTemplate` model or ``None``.
"""
evaluated = False