Skip to content
This repository has been archived by the owner. It is now read-only.
Permalink
Browse files
ARIA-286 Sphinx documentation for code and CLI
  • Loading branch information
tliron authored and Ran Ziv committed Jun 29, 2017
1 parent 4ff4012 commit 2ed2e1c2328221b9a7c28f902ee0b3f70e427248
Showing 200 changed files with 6,007 additions and 3,011 deletions.
@@ -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 @@
'__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,
@@ -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.
"""
@@ -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()
@@ -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,
@@ -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 ...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:
@@ -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 @@
@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))
@@ -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 @@
@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,17 +70,18 @@ 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
@aria.options.verbose()
@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:
@@ -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 @@
@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))

0 comments on commit 2ed2e1c

Please sign in to comment.