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/master Commit: 8eef8ed92310416fea9a95d7f548fdbd440d0f36 Parents: 4ff4012 Author: Tal Liron <[email protected]> Authored: Thu Jun 22 21:13:28 2017 -0500 Committer: Ran Ziv <[email protected]> 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
