http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/api/task_graph.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/api/task_graph.py b/aria/orchestrator/workflows/api/task_graph.py index 9f0d13b..900a0d1 100644 --- a/aria/orchestrator/workflows/api/task_graph.py +++ b/aria/orchestrator/workflows/api/task_graph.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Task graph. Used by users to build workflows +Task graph. """ from collections import Iterable @@ -27,7 +27,7 @@ from . import task as api_task class TaskNotInGraphError(Exception): """ - An error representing a scenario where a given task is not in the graph as expected + An error representing a scenario where a given task is not in the graph as expected. """ pass @@ -43,8 +43,7 @@ def _filter_out_empty_tasks(func=None): class TaskGraph(object): """ - A tasks graph builder. - Build an operations flow graph + Task graph builder. """ def __init__(self, name): @@ -59,8 +58,7 @@ class TaskGraph(object): @property def id(self): """ - Represents the id of the graph - :return: graph id + ID of the graph """ return self._id @@ -69,27 +67,28 @@ class TaskGraph(object): @property def tasks(self): """ - An iterator on tasks added to the graph - :yields: Iterator over all tasks in the graph + Iterator over tasks in the graph. """ for _, data in self._graph.nodes_iter(data=True): yield data['task'] def topological_order(self, reverse=False): """ - Returns topological sort on the graph + Topological sort of the graph. + :param reverse: whether to reverse the sort - :return: a list which represents the topological sort + :return: list which represents the topological sort """ for task_id in topological_sort(self._graph, reverse=reverse): yield self.get_task(task_id) def get_dependencies(self, dependent_task): """ - Iterates over the task's dependencies - :param BaseTask dependent_task: The task whose dependencies are requested - :yields: Iterator over all tasks which dependency_task depends on - :raise: TaskNotInGraphError if dependent_task is not in the graph + Iterates over the task's dependencies. + + :param dependent_task: task whose dependencies are requested + :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if + ``dependent_task`` is not in the graph """ if not self.has_tasks(dependent_task): raise TaskNotInGraphError('Task id: {0}'.format(dependent_task.id)) @@ -98,10 +97,11 @@ class TaskGraph(object): def get_dependents(self, dependency_task): """ - Iterates over the task's dependents - :param BaseTask dependency_task: The task whose dependents are requested - :yields: Iterator over all tasks which depend on dependency_task - :raise: TaskNotInGraphError if dependency_task is not in the graph + Iterates over the task's dependents. + + :param dependency_task: task whose dependents are requested + :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if + ``dependency_task`` is not in the graph """ if not self.has_tasks(dependency_task): raise TaskNotInGraphError('Task id: {0}'.format(dependency_task.id)) @@ -112,11 +112,11 @@ class TaskGraph(object): def get_task(self, task_id): """ - Get a task instance that's been inserted to the graph by the task's id - :param basestring task_id: The task's id - :return: Requested task - :rtype: BaseTask - :raise: TaskNotInGraphError if no task found in the graph with the given id + Get a task instance that's been inserted to the graph by the task's ID. + + :param basestring task_id: task ID + :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if no task found in + the graph with the given ID """ if not self._graph.has_node(task_id): raise TaskNotInGraphError('Task id: {0}'.format(task_id)) @@ -126,9 +126,10 @@ class TaskGraph(object): @_filter_out_empty_tasks def add_tasks(self, *tasks): """ - Add a task to the graph - :param BaseTask task: The task - :return: A list of added tasks + Adds a task to the graph. + + :param task: task + :return: list of added tasks :rtype: list """ assert all([isinstance(task, (api_task.BaseTask, Iterable)) for task in tasks]) @@ -146,9 +147,10 @@ class TaskGraph(object): @_filter_out_empty_tasks def remove_tasks(self, *tasks): """ - Remove the provided task from the graph - :param BaseTask task: The task - :return: A list of removed tasks + Removes the provided task from the graph. + + :param task: task + :return: list of removed tasks :rtype: list """ return_tasks = [] @@ -165,9 +167,10 @@ class TaskGraph(object): @_filter_out_empty_tasks def has_tasks(self, *tasks): """ - Check whether a task is in the graph or not - :param BaseTask task: The task - :return: True if all tasks are in the graph, otherwise True + Checks whether a task is in the graph. + + :param task: task + :return: ``True`` if all tasks are in the graph, otherwise ``False`` :rtype: list """ assert all(isinstance(t, (api_task.BaseTask, Iterable)) for t in tasks) @@ -183,16 +186,18 @@ class TaskGraph(object): def add_dependency(self, dependent, dependency): """ - Add a dependency for one item (task, sequence or parallel) on another - The dependent will only be executed after the dependency terminates - If either of the items is either a sequence or a parallel, - multiple dependencies may be added - :param BaseTask|_TasksArrangement dependent: The dependent (task, sequence or parallel) - :param BaseTask|_TasksArrangement dependency: The dependency (task, sequence or parallel) - :return: True if the dependency between the two hadn't already existed, otherwise False + Adds a dependency for one item (task, sequence or parallel) on another. + + The dependent will only be executed after the dependency terminates. If either of the items + is either a sequence or a parallel, multiple dependencies may be added. + + :param dependent: dependent (task, sequence or parallel) + :param dependency: dependency (task, sequence or parallel) + :return: ``True`` if the dependency between the two hadn't already existed, otherwise + ``False`` :rtype: bool - :raise TaskNotInGraphError if either the dependent or dependency are tasks which - are not in the graph + :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if either the + dependent or dependency are tasks which are not in the graph """ if not (self.has_tasks(dependent) and self.has_tasks(dependency)): raise TaskNotInGraphError() @@ -212,18 +217,17 @@ class TaskGraph(object): def has_dependency(self, dependent, dependency): """ - Check whether one item (task, sequence or parallel) depends on another + Checks whether one item (task, sequence or parallel) depends on another. - Note that if either of the items is either a sequence or a parallel, - and some of the dependencies exist in the graph but not all of them, - this method will return False + Note that if either of the items is either a sequence or a parallel, and some of the + dependencies exist in the graph but not all of them, this method will return ``False``. - :param BaseTask|_TasksArrangement dependent: The dependent (task, sequence or parallel) - :param BaseTask|_TasksArrangement dependency: The dependency (task, sequence or parallel) - :return: True if the dependency between the two exists, otherwise False + :param dependent: dependent (task, sequence or parallel) + :param dependency: dependency (task, sequence or parallel) + :return: ``True`` if the dependency between the two exists, otherwise ``False`` :rtype: bool - :raise TaskNotInGraphError if either the dependent or dependency are tasks - which are not in the graph + :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if either the + dependent or dependency are tasks which are not in the graph """ if not (dependent and dependency): return False @@ -246,18 +250,18 @@ class TaskGraph(object): def remove_dependency(self, dependent, dependency): """ - Remove a dependency for one item (task, sequence or parallel) on another + Removes a dependency for one item (task, sequence or parallel) on another. - Note that if either of the items is either a sequence or a parallel, and some of - the dependencies exist in the graph but not all of them, this method will not remove - any of the dependencies and return False + Note that if either of the items is either a sequence or a parallel, and some of the + dependencies exist in the graph but not all of them, this method will not remove any of the + dependencies and return ``False``. - :param BaseTask|_TasksArrangement dependent: The dependent (task, sequence or parallel) - :param BaseTask|_TasksArrangement dependency: The dependency (task, sequence or parallel) - :return: False if the dependency between the two hadn't existed, otherwise True + :param dependent: dependent (task, sequence or parallel) + :param dependency: dependency (task, sequence or parallel) + :return: ``False`` if the dependency between the two hadn't existed, otherwise ``True`` :rtype: bool - :raise TaskNotInGraphError if either the dependent or dependency are tasks - which are not in the graph + :raises ~aria.orchestrator.workflows.api.task_graph.TaskNotInGraphError: if either the + dependent or dependency are tasks which are not in the graph """ if not (self.has_tasks(dependent) and self.has_tasks(dependency)): raise TaskNotInGraphError() @@ -277,9 +281,10 @@ class TaskGraph(object): @_filter_out_empty_tasks def sequence(self, *tasks): """ - Create and insert a sequence into the graph, effectively each task i depends on i-1 - :param tasks: an iterable of dependencies - :return: the provided tasks + Creates and inserts a sequence into the graph, effectively each task i depends on i-1. + + :param tasks: iterable of dependencies + :return: provided tasks """ if tasks: self.add_tasks(*tasks)
http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/builtin/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/builtin/__init__.py b/aria/orchestrator/workflows/builtin/__init__.py index 8b13c62..1b2f390 100644 --- a/aria/orchestrator/workflows/builtin/__init__.py +++ b/aria/orchestrator/workflows/builtin/__init__.py @@ -14,7 +14,7 @@ # limitations under the License. """ -A set of builtin workflows +Built-in workflows. """ from .install import install http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/builtin/execute_operation.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/builtin/execute_operation.py b/aria/orchestrator/workflows/builtin/execute_operation.py index 437e584..949f864 100644 --- a/aria/orchestrator/workflows/builtin/execute_operation.py +++ b/aria/orchestrator/workflows/builtin/execute_operation.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Builtin execute_operation workflow +Built-in operation execution Workflow. """ from ... import workflow @@ -34,13 +34,13 @@ def execute_operation( node_ids, **kwargs): """ - The execute_operation workflow + Built-in operation execution Workflow. - :param WorkflowContext workflow_context: the workflow context - :param TaskGraph graph: the graph which will describe the workflow. - :param basestring operation: the operation name to execute - :param dict operation_kwargs: - :param bool run_by_dependency_order: + :param workflow_context: workflow context + :param graph: graph which will describe the workflow + :param operation: operation name to execute + :param operation_kwargs: + :param run_by_dependency_order: :param type_names: :param node_template_ids: :param node_ids: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/builtin/heal.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/builtin/heal.py b/aria/orchestrator/workflows/builtin/heal.py index ca382e8..07e27b1 100644 --- a/aria/orchestrator/workflows/builtin/heal.py +++ b/aria/orchestrator/workflows/builtin/heal.py @@ -16,7 +16,7 @@ # pylint: skip-file """ -Builtin heal workflow +Built-in heal workflow. """ from aria import workflow @@ -28,11 +28,11 @@ from ..api import task @workflow def heal(ctx, graph, node_id): """ - The heal workflow + Built-in heal workflow.. - :param WorkflowContext ctx: the workflow context - :param TaskGraph graph: the graph which will describe the workflow. - :param node_id: the id of the node to heal + :param ctx: workflow context + :param graph: graph which will describe the workflow. + :param node_id: ID of the node to heal :return: """ failing_node = ctx.model.node.get(node_id) @@ -60,13 +60,12 @@ def heal(ctx, graph, node_id): @workflow(suffix_template='{failing_nodes}') def heal_uninstall(ctx, graph, failing_nodes, targeted_nodes): """ - the uninstall part of the heal mechanism - :param WorkflowContext ctx: the workflow context - :param TaskGraph graph: the task graph to edit. - :param failing_nodes: the failing nodes to heal. - :param targeted_nodes: the targets of the relationships where the failing node are - source - :return: + Uninstall phase of the heal mechanism. + + :param ctx: workflow context + :param graph: task graph to edit + :param failing_nodes: failing nodes to heal + :param targeted_nodes: targets of the relationships where the failing node are """ node_sub_workflows = {} @@ -113,13 +112,12 @@ def heal_uninstall(ctx, graph, failing_nodes, targeted_nodes): @workflow(suffix_template='{failing_nodes}') def heal_install(ctx, graph, failing_nodes, targeted_nodes): """ - the install part of the heal mechanism - :param WorkflowContext ctx: the workflow context - :param TaskGraph graph: the task graph to edit. - :param failing_nodes: the failing nodes to heal. - :param targeted_nodes: the targets of the relationships where the failing node are - source - :return: + Install phase of the heal mechanism. + + :param ctx: workflow context + :param graph: task graph to edit. + :param failing_nodes: failing nodes to heal + :param targeted_nodes: targets of the relationships where the failing node are """ node_sub_workflows = {} http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/builtin/install.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/builtin/install.py b/aria/orchestrator/workflows/builtin/install.py index 821b190..1e7c531 100644 --- a/aria/orchestrator/workflows/builtin/install.py +++ b/aria/orchestrator/workflows/builtin/install.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Builtin install workflow +Built-in install workflow. """ from ... import workflow @@ -24,6 +24,9 @@ from . import workflows @workflow def install(ctx, graph): + """ + Built-in install workflow. + """ tasks_and_nodes = [] for node in ctx.nodes: tasks_and_nodes.append((api_task.WorkflowTask(workflows.install_node, node=node), node)) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/builtin/start.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/builtin/start.py b/aria/orchestrator/workflows/builtin/start.py index 1946143..c02a26d 100644 --- a/aria/orchestrator/workflows/builtin/start.py +++ b/aria/orchestrator/workflows/builtin/start.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Builtin start workflow +Built-in start workflow. """ from .workflows import start_node @@ -24,5 +24,8 @@ from ..api import task as api_task @workflow def start(ctx, graph): + """ + Built-in start workflow. + """ for node in ctx.model.node.iter(): graph.add_tasks(api_task.WorkflowTask(start_node, node=node)) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/builtin/stop.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/builtin/stop.py b/aria/orchestrator/workflows/builtin/stop.py index c1b60ae..6f9930b 100644 --- a/aria/orchestrator/workflows/builtin/stop.py +++ b/aria/orchestrator/workflows/builtin/stop.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Builtin stop workflow +Built-in stop workflow. """ from .workflows import stop_node @@ -24,5 +24,8 @@ from ... import workflow @workflow def stop(ctx, graph): + """ + Built-in stop workflow. + """ for node in ctx.model.node.iter(): graph.add_tasks(api_task.WorkflowTask(stop_node, node=node)) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/builtin/uninstall.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/builtin/uninstall.py b/aria/orchestrator/workflows/builtin/uninstall.py index c35117e..7925f4b 100644 --- a/aria/orchestrator/workflows/builtin/uninstall.py +++ b/aria/orchestrator/workflows/builtin/uninstall.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Builtin uninstall workflow +Built-in uninstall workflow. """ from ... import workflow @@ -24,6 +24,9 @@ from . import workflows @workflow def uninstall(ctx, graph): + """ + Built-in uninstall workflow. + """ tasks_and_nodes = [] for node in ctx.nodes: tasks_and_nodes.append((api_task.WorkflowTask(workflows.uninstall_node, node=node), node)) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/core/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/core/__init__.py b/aria/orchestrator/workflows/core/__init__.py index 81db43f..3f28136 100644 --- a/aria/orchestrator/workflows/core/__init__.py +++ b/aria/orchestrator/workflows/core/__init__.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Core for the workflow execution mechanism +Workflow core. """ from . import engine http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/core/compile.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/core/compile.py b/aria/orchestrator/workflows/core/compile.py index 932268a..e405715 100644 --- a/aria/orchestrator/workflows/core/compile.py +++ b/aria/orchestrator/workflows/core/compile.py @@ -13,6 +13,9 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Workflow compilation. +""" from ....modeling import models from .. import executor, api @@ -33,8 +36,9 @@ def _construct_execution_tasks(execution, end_stub_type=models.Task.END_WORKFLOW, depends_on=()): """ - Translates the user graph to the execution graph - :param task_graph: The user's graph + Translates the user graph to the execution graph. + + :param task_graph: user graph :param start_stub_type: internal use :param end_stub_type: internal use :param depends_on: internal use http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/core/engine.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/core/engine.py b/aria/orchestrator/workflows/core/engine.py index d5a6e70..1912a3e 100644 --- a/aria/orchestrator/workflows/core/engine.py +++ b/aria/orchestrator/workflows/core/engine.py @@ -14,7 +14,7 @@ # limitations under the License. """ -The workflow engine. Executes workflows +Workflow execution. """ import time @@ -33,7 +33,7 @@ from . import events_handler # pylint: disable=unused-import class Engine(logger.LoggerMixin): """ - The workflow engine. Executes workflows + Executes workflows. """ def __init__(self, executors, **kwargs): @@ -43,7 +43,7 @@ class Engine(logger.LoggerMixin): def execute(self, ctx, resuming=False): """ - execute the workflow + Executes the workflow. """ executing_tasks = [] @@ -76,8 +76,8 @@ class Engine(logger.LoggerMixin): def cancel_execution(ctx): """ Send a cancel request to the engine. If execution already started, execution status - will be modified to 'cancelling' status. If execution is in pending mode, execution status - will be modified to 'cancelled' directly. + will be modified to ``cancelling`` status. If execution is in pending mode, execution status + will be modified to ``cancelled`` directly. """ events.on_cancelling_workflow_signal.send(ctx) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/core/events_handler.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/core/events_handler.py b/aria/orchestrator/workflows/core/events_handler.py index 7380db8..769c1a8 100644 --- a/aria/orchestrator/workflows/core/events_handler.py +++ b/aria/orchestrator/workflows/core/events_handler.py @@ -14,10 +14,7 @@ # limitations under the License. """ -ARIA's events Sub-Package -Path: aria.events.storage_event_handler - -Implementation of storage handlers for workflow and operation events. +Workflow event handling. """ from datetime import ( http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/events_logging.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/events_logging.py b/aria/orchestrator/workflows/events_logging.py index 4cee867..9eee1e1 100644 --- a/aria/orchestrator/workflows/events_logging.py +++ b/aria/orchestrator/workflows/events_logging.py @@ -15,10 +15,7 @@ """ -ARIA's events Sub-Package -Path: aria.events.storage_event_handler - -Implementation of logger handlers for workflow and operation events. +Workflow event logging. """ from .. import events http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/exceptions.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/exceptions.py b/aria/orchestrator/workflows/exceptions.py index b5ae496..2a1d6b1 100644 --- a/aria/orchestrator/workflows/exceptions.py +++ b/aria/orchestrator/workflows/exceptions.py @@ -14,8 +14,9 @@ # limitations under the License. """ -Workflow related Exception classes +Workflow exceptions. """ + import os from .. import exceptions @@ -23,14 +24,14 @@ from .. import exceptions class ExecutorException(exceptions.AriaError): """ - General executor exception + General executor exception. """ pass class ProcessException(ExecutorException): """ - Raised when subprocess execution fails + Raised when subprocess execution fails. """ def __init__(self, command, stderr=None, stdout=None, return_code=None): @@ -62,13 +63,13 @@ class ProcessException(ExecutorException): class AriaEngineError(exceptions.AriaError): """ - Raised by the workflow engine + Raised by the workflow engine. """ class TaskException(exceptions.AriaError): """ - Raised by the task + Raised by the task. """ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/executor/__init__.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/executor/__init__.py b/aria/orchestrator/workflows/executor/__init__.py index 414a740..cafab74 100644 --- a/aria/orchestrator/workflows/executor/__init__.py +++ b/aria/orchestrator/workflows/executor/__init__.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Executors for task execution +Task executors. """ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/executor/base.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/executor/base.py b/aria/orchestrator/workflows/executor/base.py index 6a3c9d2..4bb2abc 100644 --- a/aria/orchestrator/workflows/executor/base.py +++ b/aria/orchestrator/workflows/executor/base.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Base executor module +Base class for task executors. """ from aria import logger @@ -23,14 +23,15 @@ from aria.orchestrator import events class BaseExecutor(logger.LoggerMixin): """ - Base class for executors for running tasks + Base class for task executors. """ def _execute(self, task): raise NotImplementedError def execute(self, ctx): """ - Execute a task + Executes a task. + :param task: task to execute """ if ctx.task.function: @@ -44,7 +45,7 @@ class BaseExecutor(logger.LoggerMixin): def close(self): """ - Close the executor + Closes the executor. """ pass http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/executor/celery.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/executor/celery.py b/aria/orchestrator/workflows/executor/celery.py index 9d66d26..6f7e9ca 100644 --- a/aria/orchestrator/workflows/executor/celery.py +++ b/aria/orchestrator/workflows/executor/celery.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Celery based executor +Celery task executor. """ import threading @@ -25,7 +25,7 @@ from aria.orchestrator.workflows.executor import BaseExecutor class CeleryExecutor(BaseExecutor): """ - Executor which runs tasks using aria_celery + Celery task executor. """ def __init__(self, app, *args, **kwargs): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/executor/dry.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/executor/dry.py b/aria/orchestrator/workflows/executor/dry.py index 9d86125..9314e5d 100644 --- a/aria/orchestrator/workflows/executor/dry.py +++ b/aria/orchestrator/workflows/executor/dry.py @@ -14,8 +14,9 @@ # limitations under the License. """ -Dry executor +Dry task executor. """ + from datetime import datetime from . import base @@ -23,7 +24,7 @@ from . import base class DryExecutor(base.BaseExecutor): # pylint: disable=abstract-method """ - Executor which dry runs tasks - prints task information without causing any side effects + Dry task executor: prints task information without causing any side effects. """ def execute(self, ctx): with ctx.persist_changes: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/executor/process.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/executor/process.py b/aria/orchestrator/workflows/executor/process.py index 8518b33..4949187 100644 --- a/aria/orchestrator/workflows/executor/process.py +++ b/aria/orchestrator/workflows/executor/process.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Subprocess based executor +Sub-process task executor. """ # pylint: disable=wrong-import-position @@ -59,7 +59,7 @@ UPDATE_TRACKED_CHANGES_FAILED_STR = \ class ProcessExecutor(base.BaseExecutor): """ - Executor which runs tasks in a subprocess environment + Sub-process task executor. """ def __init__(self, plugin_manager=None, python_path=None, *args, **kwargs): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/orchestrator/workflows/executor/thread.py ---------------------------------------------------------------------- diff --git a/aria/orchestrator/workflows/executor/thread.py b/aria/orchestrator/workflows/executor/thread.py index 8c447b6..d9dcdf8 100644 --- a/aria/orchestrator/workflows/executor/thread.py +++ b/aria/orchestrator/workflows/executor/thread.py @@ -14,7 +14,7 @@ # limitations under the License. """ -Thread based executor +Thread task executor. """ import Queue @@ -29,9 +29,11 @@ from .base import BaseExecutor class ThreadExecutor(BaseExecutor): """ - Executor which runs tasks in a separate thread. It's easier writing tests - using this executor rather than the full blown subprocess executor. - Note: This executor is not capable of running plugin operations. + Thread task executor. + + It's easier writing tests using this executor rather than the full-blown sub-process executor. + + Note: This executor is incapable of running plugin operations. """ def __init__(self, pool_size=1, *args, **kwargs): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/__init__.py ---------------------------------------------------------------------- diff --git a/aria/parser/__init__.py b/aria/parser/__init__.py index c25f468..7903b52 100644 --- a/aria/parser/__init__.py +++ b/aria/parser/__init__.py @@ -14,7 +14,7 @@ # limitations under the License. """ -ARIA parser package +Parser package. """ from .specification import implements_specification, iter_specifications http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/consumption/__init__.py ---------------------------------------------------------------------- diff --git a/aria/parser/consumption/__init__.py b/aria/parser/consumption/__init__.py index 76e73be..32d5eed 100644 --- a/aria/parser/consumption/__init__.py +++ b/aria/parser/consumption/__init__.py @@ -13,6 +13,38 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Consumption package. + +.. autosummary:: + :nosignatures: + + aria.parser.consumption.handle_exception + aria.parser.consumption.ConsumptionContext + aria.parser.consumption.Style + +Consumers +--------- + +.. autosummary:: + :nosignatures: + + aria.parser.consumption.Consumer + aria.parser.consumption.ConsumerChain + aria.parser.consumption.ConsumerException + aria.parser.consumption.Inputs + aria.parser.consumption.ServiceTemplate + aria.parser.consumption.Types + aria.parser.consumption.CoerceServiceInstanceValues + aria.parser.consumption.ValidateServiceInstance + aria.parser.consumption.SatisfyRequirements + aria.parser.consumption.ValidateCapabilities + aria.parser.consumption.FindHosts + aria.parser.consumption.ConfigureOperations + aria.parser.consumption.ServiceInstance + aria.parser.consumption.Read + aria.parser.consumption.Validate +""" from .exceptions import ConsumerException from .context import ConsumptionContext http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/consumption/consumer.py ---------------------------------------------------------------------- diff --git a/aria/parser/consumption/consumer.py b/aria/parser/consumption/consumer.py index f9c2f2e..4f4c614 100644 --- a/aria/parser/consumption/consumer.py +++ b/aria/parser/consumption/consumer.py @@ -48,8 +48,8 @@ class ConsumerChain(Consumer): """ ARIA consumer chain. - Calls consumers in order, handling exception by calling `_handle_exception` on them, - and stops the chain if there are any validation issues. + Calls consumers in order, handling exception by calling ``_handle_exception`` on them, and stops + the chain if there are any validation issues. """ def __init__(self, context, consumer_classes=None, handle_exceptions=True): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/consumption/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/consumption/context.py b/aria/parser/consumption/context.py index e73a8ab..6fa61f4 100644 --- a/aria/parser/consumption/context.py +++ b/aria/parser/consumption/context.py @@ -29,6 +29,8 @@ _thread_locals = threading.local() class ConsumptionContext(object): """ + Consumption context. + :ivar args: runtime arguments (usually provided on the command line) :ivar out: message output stream (defaults to stdout) :ivar style: message output style http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/consumption/presentation.py ---------------------------------------------------------------------- diff --git a/aria/parser/consumption/presentation.py b/aria/parser/consumption/presentation.py index fc41614..542b3f0 100644 --- a/aria/parser/consumption/presentation.py +++ b/aria/parser/consumption/presentation.py @@ -26,8 +26,9 @@ class Read(Consumer): """ Reads the presentation, handling imports recursively. - It works by consuming a data source via appropriate :class:`aria.parser.loader.Loader`, - :class:`aria.parser.reader.Reader`, and :class:`aria.parser.presenter.Presenter` instances. + It works by consuming a data source via appropriate :class:`~aria.parser.loading.Loader`, + :class:`~aria.parser.reading.Reader`, and :class:`~aria.parser.presentation.Presenter` + instances. It supports agnostic raw data composition for presenters that have ``_get_import_locations`` and ``_merge_import``. http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/exceptions.py ---------------------------------------------------------------------- diff --git a/aria/parser/exceptions.py b/aria/parser/exceptions.py index 5d1a55c..a1f7012 100644 --- a/aria/parser/exceptions.py +++ b/aria/parser/exceptions.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Parser exceptions. +""" + from ..exceptions import AriaException from .validation import Issue http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/loading/__init__.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/__init__.py b/aria/parser/loading/__init__.py index 006f164..834675e 100644 --- a/aria/parser/loading/__init__.py +++ b/aria/parser/loading/__init__.py @@ -13,6 +13,41 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Loading package. + +.. autosummary:: + :nosignatures: + + aria.parser.loading.LoadingContext + aria.parser.loading.LoaderException + aria.parser.loading.LoaderNotFoundError + aria.parser.loading.DocumentNotFoundException + aria.parser.loading.LoaderSource + aria.parser.loading.DefaultLoaderSource + +Loaders +------- + +.. autosummary:: + :nosignatures: + + aria.parser.loading.Loader + aria.parser.loading.FileTextLoader + aria.parser.loading.LiteralLoader + aria.parser.loading.RequestLoader + aria.parser.loading.RequestTextLoader + aria.parser.loading.UriTextLoader + +Locations +--------- + +.. autosummary:: + :nosignatures: + + aria.parser.loading.Location + aria.parser.loading.UriLocation +""" from .exceptions import LoaderException, LoaderNotFoundError, DocumentNotFoundException from .context import LoadingContext http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/loading/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/context.py b/aria/parser/loading/context.py index 1d1aaf6..59727c9 100644 --- a/aria/parser/loading/context.py +++ b/aria/parser/loading/context.py @@ -20,10 +20,10 @@ from .source import DefaultLoaderSource class LoadingContext(object): """ - Properties: + Loading context. :ivar loader_source: for finding loader instances - :vartype loader_source: LoaderSource + :vartype loader_source: ~aria.parser.loading.LoaderSource :ivar prefixes: additional prefixes for :class:`UriTextLoader` :vartype prefixes: [:obj:`basestring`] """ http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/loading/literal.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/literal.py b/aria/parser/loading/literal.py index c9a4335..7865008 100644 --- a/aria/parser/loading/literal.py +++ b/aria/parser/loading/literal.py @@ -21,7 +21,7 @@ class LiteralLoader(Loader): """ ARIA literal loader. - See :class:`aria.parser.loading.LiteralLocation`. + See :class:`~aria.parser.loading.LiteralLocation`. """ def __init__(self, location): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/loading/location.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/location.py b/aria/parser/loading/location.py index f31c330..902e856 100644 --- a/aria/parser/loading/location.py +++ b/aria/parser/loading/location.py @@ -23,8 +23,8 @@ class Location(object): """ Base class for ARIA locations. - Locations are used by :class:`aria.parser.loading.LoaderSource` to delegate to - an appropriate :class:`aria.parser.loading.Loader`. + Locations are used by :class:`~aria.parser.loading.LoaderSource` to delegate to + an appropriate :class:`~aria.parser.loading.Loader`. """ def is_equivalent(self, location): @@ -41,7 +41,7 @@ class UriLocation(Location): If no scheme is included, it should be treated as a filesystem path. - See :class:`aria.parser.loading.UriTextLoader`. + See :class:`~aria.parser.loading.UriTextLoader`. """ def __init__(self, uri): @@ -68,7 +68,7 @@ class LiteralLocation(Location): """ A location that embeds content. - See :class:`aria.parser.loading.LiteralLoader`. + See :class:`~aria.parser.loading.LiteralLoader`. """ def __init__(self, content, name='literal'): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/loading/source.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/source.py b/aria/parser/loading/source.py index 7acf813..bcd6dd1 100644 --- a/aria/parser/loading/source.py +++ b/aria/parser/loading/source.py @@ -32,7 +32,7 @@ class LoaderSource(object): class DefaultLoaderSource(LoaderSource): """ The default ARIA loader source will generate a :class:`UriTextLoader` for - :class:`UriLocation' and a :class:`LiteralLoader` for a :class:`LiteralLocation`. + :class:`UriLocation` and a :class:`LiteralLoader` for a :class:`LiteralLocation`. """ def get_loader(self, context, location, origin_location): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/loading/uri.py ---------------------------------------------------------------------- diff --git a/aria/parser/loading/uri.py b/aria/parser/loading/uri.py index 30f4e44..a5a18e6 100644 --- a/aria/parser/loading/uri.py +++ b/aria/parser/loading/uri.py @@ -29,14 +29,14 @@ class UriTextLoader(Loader): """ Base class for ARIA URI loaders. - See :class:`aria.parser.loading.UriLocation`. + See :class:`~aria.parser.loading.UriLocation`. Supports a list of search prefixes that are tried in order if the URI cannot be found. They will be: * If ``origin_location`` is provided its prefix will come first. * Then the prefixes in the :class:`LoadingContext` will be added. - * Finally, the global prefixes specified in ``URI_LOADER_PREFIXES`` will be added. + * Finally, the parser can supply a ``uri_loader_prefix`` function with extra prefixes. """ def __init__(self, context, location, origin_location=None): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/modeling/__init__.py ---------------------------------------------------------------------- diff --git a/aria/parser/modeling/__init__.py b/aria/parser/modeling/__init__.py index df127cd..4b1c995 100644 --- a/aria/parser/modeling/__init__.py +++ b/aria/parser/modeling/__init__.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Modeling package. +""" + from .context import IdType, ModelingContext http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/modeling/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/modeling/context.py b/aria/parser/modeling/context.py index d482a10..3d75617 100644 --- a/aria/parser/modeling/context.py +++ b/aria/parser/modeling/context.py @@ -38,6 +38,8 @@ class IdType(object): class ModelingContext(object): """ + Modeling context. + :ivar template: generated service template :vartype template: aria.modeling.models.ServiceTemplate :ivar instance: generated service instance @@ -49,7 +51,7 @@ class ModelingContext(object): :ivar id_max_length: maximum allowed instance ID length :vartype id_max_length: int :ivar inputs: inputs values - :vartype inputs: {basestring, object} + :vartype inputs: {:obj:`basestring`, object} """ def __init__(self): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/presentation/__init__.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/__init__.py b/aria/parser/presentation/__init__.py index a681695..5633e7b 100644 --- a/aria/parser/presentation/__init__.py +++ b/aria/parser/presentation/__init__.py @@ -13,6 +13,85 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Presentation package. + +.. autosummary:: + :nosignatures: + + aria.parser.presentation.PresentationContext + aria.parser.presentation.PresenterException + aria.parser.presentation.PresenterNotFoundError + aria.parser.presentation.Field + aria.parser.presentation.NULL + aria.parser.presentation.none_to_null + aria.parser.presentation.null_to_none + aria.parser.presentation.Value + aria.parser.presentation.Presenter + aria.parser.presentation.PresenterSource + aria.parser.presentation.DefaultPresenterSource + +Presentations +------------- + +.. autosummary:: + :nosignatures: + + aria.parser.presentation.PresentationBase + aria.parser.presentation.Presentation + aria.parser.presentation.AsIsPresentation + +Field decorators +---------------- + +.. autosummary:: + :nosignatures: + + aria.parser.presentation.has_fields + aria.parser.presentation.short_form_field + aria.parser.presentation.allow_unknown_fields + aria.parser.presentation.primitive_field + aria.parser.presentation.primitive_list_field + aria.parser.presentation.primitive_dict_field + aria.parser.presentation.primitive_dict_unknown_fields + aria.parser.presentation.object_field + aria.parser.presentation.object_list_field + aria.parser.presentation.object_dict_field + aria.parser.presentation.object_sequenced_list_field + aria.parser.presentation.object_dict_unknown_fields + aria.parser.presentation.field_getter + aria.parser.presentation.field_setter + aria.parser.presentation.field_validator + +Field validators +---------------- + +.. autosummary:: + :nosignatures: + + aria.parser.presentation.type_validator + aria.parser.presentation.list_type_validator + aria.parser.presentation.list_length_validator + aria.parser.presentation.derived_from_validator + +Utilities +--------- + +.. autosummary:: + :nosignatures: + + aria.parser.presentation.get_locator + aria.parser.presentation.parse_types_dict_names + aria.parser.presentation.validate_primitive + aria.parser.presentation.validate_no_short_form + aria.parser.presentation.validate_no_unknown_fields + aria.parser.presentation.validate_known_fields + aria.parser.presentation.get_parent_presentation + aria.parser.presentation.report_issue_for_unknown_type + aria.parser.presentation.report_issue_for_parent_is_self + aria.parser.presentation.report_issue_for_unknown_parent_type + aria.parser.presentation.report_issue_for_circular_type_hierarchy +""" from .exceptions import PresenterException, PresenterNotFoundError from .context import PresentationContext @@ -29,8 +108,8 @@ from .field_validators import (type_validator, list_type_validator, list_length_ derived_from_validator) from .utils import (get_locator, parse_types_dict_names, validate_primitive, validate_no_short_form, validate_no_unknown_fields, validate_known_fields, get_parent_presentation, - report_issue_for_unknown_type, report_issue_for_parent_is_self, - report_issue_for_circular_type_hierarchy) + report_issue_for_unknown_type, report_issue_for_unknown_parent_type, + report_issue_for_parent_is_self, report_issue_for_circular_type_hierarchy) __all__ = ( 'PresenterException', @@ -74,5 +153,6 @@ __all__ = ( 'validate_known_fields', 'get_parent_presentation', 'report_issue_for_unknown_type', + 'report_issue_for_unknown_parent_type', 'report_issue_for_parent_is_self', 'report_issue_for_circular_type_hierarchy') http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/presentation/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/context.py b/aria/parser/presentation/context.py index eaa2103..44a6f82 100644 --- a/aria/parser/presentation/context.py +++ b/aria/parser/presentation/context.py @@ -19,12 +19,14 @@ from .source import DefaultPresenterSource class PresentationContext(object): """ + Presentation context. + :ivar presenter: the generated presenter instance - :vartype presenter: Presenter + :vartype presenter: ~aria.parser.presentation.Presenter :ivar location: from where we will generate the presenter - :vartype location: Location + :vartype location: ~aria.parser.loading.Location :ivar presenter_source: for finding presenter classes - :vartype presenter_source: PresenterSource + :vartype presenter_source: ~aria.parser.presentation.PresenterSource :ivar presenter_class: overrides ``presenter_source`` with a specific class :vartype presenter_class: type :ivar import_profile: whether to import the profile by default (defaults to ``True``) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/presentation/presentation.py ---------------------------------------------------------------------- diff --git a/aria/parser/presentation/presentation.py b/aria/parser/presentation/presentation.py index 0fcb9e4..7292562 100644 --- a/aria/parser/presentation/presentation.py +++ b/aria/parser/presentation/presentation.py @@ -180,7 +180,7 @@ class Presentation(PresentationBase): Base class for ARIA presentations. A presentation is a Pythonic wrapper around agnostic raw data, adding the ability to read and modify the data with proper validation. - ARIA presentation classes will often be decorated with ``@has_fields``, as that mechanism + ARIA presentation classes will often be decorated with :func:`has_fields`, as that mechanism automates a lot of field-specific validation. However, that is not a requirement. Make sure that your utility property and method names begin with a ``_``, because those names http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/reading/__init__.py ---------------------------------------------------------------------- diff --git a/aria/parser/reading/__init__.py b/aria/parser/reading/__init__.py index b5c0709..065ca56 100644 --- a/aria/parser/reading/__init__.py +++ b/aria/parser/reading/__init__.py @@ -10,6 +10,29 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Reading package. + +.. autosummary:: + :nosignatures: + + aria.parser.reading.ReadingContext + ReaderException + ReaderNotFoundError + ReaderSyntaxError + AlreadyReadException + JinjaReader + JsonReader + Locator + deepcopy_with_locators + copy_locators + RawReader + Reader + ReaderSource + DefaultReaderSource + YamlReader +""" + from .raw import RawReader from .reader import Reader from .yaml import YamlReader http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/reading/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/reading/context.py b/aria/parser/reading/context.py index 12f27e8..233e407 100644 --- a/aria/parser/reading/context.py +++ b/aria/parser/reading/context.py @@ -16,6 +16,8 @@ from .source import DefaultReaderSource class ReadingContext(object): """ + Reading context. + :ivar reader_source: for finding reader instances :vartype reader_source: ReaderSource :ivar reader: overrides ``reader_source`` with a specific class http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/specification.py ---------------------------------------------------------------------- diff --git a/aria/parser/specification.py b/aria/parser/specification.py index 714bed1..4f452b8 100644 --- a/aria/parser/specification.py +++ b/aria/parser/specification.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Utilities for cross-referencing code with specification documents. +""" + import re from ..extension import parser http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/validation/__init__.py ---------------------------------------------------------------------- diff --git a/aria/parser/validation/__init__.py b/aria/parser/validation/__init__.py index fead43b..21632ba 100644 --- a/aria/parser/validation/__init__.py +++ b/aria/parser/validation/__init__.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Validation package. +""" + from .issue import Issue from .context import ValidationContext http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/parser/validation/context.py ---------------------------------------------------------------------- diff --git a/aria/parser/validation/context.py b/aria/parser/validation/context.py index cc87973..ef641bd 100644 --- a/aria/parser/validation/context.py +++ b/aria/parser/validation/context.py @@ -23,11 +23,13 @@ from ...utils.formatting import as_raw class ValidationContext(object): """ + Validation context. + :ivar allow_unknown_fields: when ``False`` (the default) will report an issue if an unknown - field is used + field is used :vartype allow_unknown_fields: bool :ivar allow_primitive_coersion`: when ``False`` (the default) will not attempt to coerce - primitive field types + primitive field types :vartype allow_primitive_coersion: bool :ivar max_level: maximum validation level to report (default is all) :vartype max_level: int http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/storage/__init__.py ---------------------------------------------------------------------- diff --git a/aria/storage/__init__.py b/aria/storage/__init__.py index 6e16450..a553ca7 100644 --- a/aria/storage/__init__.py +++ b/aria/storage/__init__.py @@ -14,28 +14,7 @@ # limitations under the License. """ -ARIA storage package - -A generic abstraction over different storage types. We define this abstraction with the following -components: - -1. storage: simple MAPI to use -2. driver: implementation of the database client MAPI -3. model: defines the structure of the table/document. -4. field: defines a field/item in the model. - -API: - -* application_storage_factory - function, default ARIA storage factory. -* Storage - class, simple storage mapi. -* models - module, default ARIA standard models. -* structures - module, default ARIA structures - holds the base model, - and different fields types. -* Model - class, abstract model implementation. -* Field - class, base field implementation. -* IterField - class, base iterable field implementation. -* drivers - module, a pool of ARIA standard drivers. -* StorageDriver - class, abstract model implementation. +Storage package. """ from .core import ( http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/storage/api.py ---------------------------------------------------------------------- diff --git a/aria/storage/api.py b/aria/storage/api.py index 3304721..a337743 100644 --- a/aria/storage/api.py +++ b/aria/storage/api.py @@ -12,15 +12,17 @@ # 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. + """ -General storage API +Storage APIs. """ + import threading class StorageAPI(object): """ - General storage Base API + Base class for storage APIs. """ def create(self, **kwargs): """ @@ -33,15 +35,12 @@ class StorageAPI(object): class ModelAPI(StorageAPI): """ - A Base object for the model. + Base class for model APIs ("MAPI"). """ def __init__(self, model_cls, name=None, **kwargs): """ - Base model API - - :param model_cls: the representing class of the model - :param str name: the name of the model - :param kwargs: + :param model_cls: representing class of the model + :param name: name of the model """ super(ModelAPI, self).__init__(**kwargs) self._model_cls = model_cls @@ -59,46 +58,42 @@ class ModelAPI(StorageAPI): @property def name(self): """ - The name of the class - :return: name of the class + Name of the class. + + :type: :obj:`basestring` """ return self._name @property def model_cls(self): """ - The class represting the model - :return: + Class representing the model + + :type: :obj:`Type` """ return self._model_cls def get(self, entry_id, filters=None, **kwargs): """ - Get entry from storage. + Gets a model from storage. :param entry_id: - :param kwargs: - :return: """ raise NotImplementedError('Subclass must implement abstract get method') def put(self, entry, **kwargs): """ - Store entry in storage + Puts a model in storage. :param entry: - :param kwargs: - :return: """ raise NotImplementedError('Subclass must implement abstract store method') def delete(self, entry_id, **kwargs): """ - Delete entry from storage. + Deletes a model from storage. :param entry_id: - :param kwargs: - :return: """ raise NotImplementedError('Subclass must implement abstract delete method') @@ -107,32 +102,27 @@ class ModelAPI(StorageAPI): def iter(self, **kwargs): """ - Iter over the entries in storage. - - :param kwargs: - :return: + Iterate over all models in storage. """ raise NotImplementedError('Subclass must implement abstract iter method') def update(self, entry, **kwargs): """ - Update entry in storage. + Update a model in storage. :param entry: :param kwargs: - :return: """ raise NotImplementedError('Subclass must implement abstract update method') class ResourceAPI(StorageAPI): """ - A Base object for the resource. + Base class for resource APIs ("RAPI"). """ def __init__(self, name, **kwargs): """ - Base resource API - :param str name: the resource type + :param name: resource type """ super(ResourceAPI, self).__init__(**kwargs) self._name = name @@ -140,63 +130,57 @@ class ResourceAPI(StorageAPI): @property def name(self): """ - The name of the resource - :return: + Name of resource. + + :type: :obj:`basestring` """ return self._name def read(self, entry_id, path, **kwargs): """ - Get a bytesteam from the storage. + Get a bytesteam for a resource from storage. :param entry_id: :param path: - :param kwargs: - :return: """ raise NotImplementedError('Subclass must implement abstract read method') def delete(self, entry_id, path, **kwargs): """ - Delete a resource from the storage. + Delete a resource from storage. :param entry_id: :param path: - :param kwargs: - :return: """ raise NotImplementedError('Subclass must implement abstract delete method') def download(self, entry_id, destination, path=None, **kwargs): """ - Download a resource from the storage. + Download a resource from storage. :param entry_id: :param destination: :param path: - :param kwargs: - :return: """ raise NotImplementedError('Subclass must implement abstract download method') def upload(self, entry_id, source, path=None, **kwargs): """ - Upload a resource to the storage. + Upload a resource to storage. :param entry_id: :param source: :param path: - :param kwargs: - :return: """ raise NotImplementedError('Subclass must implement abstract upload method') def generate_lower_name(model_cls): """ - Generates the name of the class from the class object. e.g. SomeClass -> some_class - :param model_cls: the class to evaluate. - :return: lower name + Generates the name of the class from the class object, e.g. ``SomeClass`` -> ``some_class`` + + :param model_cls: class to evaluate + :return: lowercase name :rtype: basestring """ return getattr(model_cls, '__mapiname__', model_cls.__tablename__) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/storage/collection_instrumentation.py ---------------------------------------------------------------------- diff --git a/aria/storage/collection_instrumentation.py b/aria/storage/collection_instrumentation.py index 454f97a..c90cb18 100644 --- a/aria/storage/collection_instrumentation.py +++ b/aria/storage/collection_instrumentation.py @@ -13,6 +13,10 @@ # See the License for the specific language governing permissions and # limitations under the License. +""" +Utilities for instrumenting collections of models in storage. +""" + from . import exceptions @@ -42,17 +46,15 @@ class _InstrumentedCollection(object): Instantiates the object from existing seq. :param seq: the original sequence to load from - :return: """ raise NotImplementedError def _set(self, key, value): """ - set the changes for the current object (not in the db) + Sets the changes for the current object (not in the database). :param key: :param value: - :return: """ raise NotImplementedError @@ -61,10 +63,10 @@ class _InstrumentedCollection(object): def _instrument(self, key, value): """ - Instruments any collection to track changes (and ease of access) + Instruments any collection to track changes (and ease of access). + :param key: :param value: - :return: """ if isinstance(value, _InstrumentedCollection): return value @@ -79,9 +81,9 @@ class _InstrumentedCollection(object): def _raw_value(self, value): """ - Get the raw value. + Gets the raw value. + :param value: - :return: """ if isinstance(value, self._field_cls): return value.value @@ -89,10 +91,10 @@ class _InstrumentedCollection(object): def _encapsulate_value(self, key, value): """ - Create a new item cls if needed. + Creates a new item class if needed. + :param key: :param value: - :return: """ if isinstance(value, self._field_cls): return value @@ -101,10 +103,10 @@ class _InstrumentedCollection(object): def __setitem__(self, key, value): """ - Update the values in both the local and the db locations. + Updates the values in both the local and the database locations. + :param key: :param value: - :return: """ self._set(key, value) if self._is_top_level: @@ -119,11 +121,11 @@ class _InstrumentedCollection(object): def _set_field(self, collection, key, value): """ - enables updating the current change in the ancestors - :param collection: the collection to change - :param key: the key for the specific field - :param value: the new value - :return: + Enables updating the current change in the ancestors. + + :param collection: collection to change + :param key: key for the specific field + :param value: new value """ if isinstance(value, _InstrumentedCollection): value = value._raw @@ -209,9 +211,10 @@ class _InstrumentedModel(_WrappedBase): def __init__(self, mapi, *args, **kwargs): """ - The original model - :param wrapped: the model to be instrumented - :param mapi: the mapi for that model + The original model. + + :param wrapped: model to be instrumented + :param mapi: MAPI for the wrapped model """ super(_InstrumentedModel, self).__init__(*args, **kwargs) self._mapi = mapi @@ -261,11 +264,10 @@ class _WrappedModel(_WrappedBase): def __init__(self, instrumentation_kwargs, *args, **kwargs): """ - - :param instrumented_cls: The class to be instrumented - :param instrumentation_cls: the instrumentation cls - :param wrapped: the currently wrapped instance - :param kwargs: and kwargs to the passed to the instrumented class. + :param instrumented_cls: class to be instrumented + :param instrumentation_cls: instrumentation cls + :param wrapped: currently wrapped instance + :param kwargs: passed to the instrumented class """ super(_WrappedModel, self).__init__(*args, **kwargs) self._kwargs = instrumentation_kwargs http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/storage/core.py ---------------------------------------------------------------------- diff --git a/aria/storage/core.py b/aria/storage/core.py index 4b0a38f..74b1147 100644 --- a/aria/storage/core.py +++ b/aria/storage/core.py @@ -14,30 +14,9 @@ # limitations under the License. """ -ARIA's storage Sub-Package -Path: aria.storage - -Storage package is a generic abstraction over different storage types. -We define this abstraction with the following components: - -1. storage: simple mapi to use -2. driver: implementation of the database client mapi. -3. model: defines the structure of the table/document. -4. field: defines a field/item in the model. - -API: - -* application_storage_factory - function, default ARIA storage factory. -* Storage - class, simple storage mapi. -* models - module, default ARIA standard models. -* structures - module, default ARIA structures - holds the base model, - and different fields types. -* Model - class, abstract model implementation. -* Field - class, base field implementation. -* IterField - class, base iterable field implementation. -* drivers - module, a pool of ARIA standard drivers. -* StorageDriver - class, abstract model implementation. +Storage API management. """ + import copy from contextlib import contextmanager @@ -53,7 +32,7 @@ __all__ = ( class Storage(LoggerMixin): """ - Represents the storage + Base class for storage managers. """ def __init__(self, api_cls, @@ -63,13 +42,12 @@ class Storage(LoggerMixin): initiator_kwargs=None, **kwargs): """ - - :param api_cls: API cls for each model + :param api_cls: API class for each entry :param api_kwargs: - :param items: the items to register - :param initiator: a func which initializes the storage before the first use; this function - should return a dict, this dict would be passed in addition to the API - kwargs; this enables the creation of non-serializable objects + :param items: items to register + :param initiator: function which initializes the storage before the first use; this function + should return a dict, this dict would be passed in addition to the API kwargs; this enables + the creation of non-serializable objects :param initiator_kwargs: :param kwargs: """ @@ -113,24 +91,22 @@ class Storage(LoggerMixin): def register(self, entry): """ - Register the entry to the storage + Register an API. :param entry: - :return: """ raise NotImplementedError('Subclass must implement abstract register method') class ResourceStorage(Storage): """ - Represents resource storage. + Manages storage resource APIs ("RAPIs"). """ def register(self, name): """ - Register the resource type to resource storage. + Register a storage resource API ("RAPI"). :param name: name - :return: """ self.registered[name] = self.api(name=name, **self._all_api_kwargs) self.registered[name].create() @@ -139,7 +115,7 @@ class ResourceStorage(Storage): class ModelStorage(Storage): """ - Represents model storage. + Manages storage model APIs ("MAPIs"). """ def __init__(self, *args, **kwargs): if kwargs.get('initiator', None) is None: @@ -148,10 +124,9 @@ class ModelStorage(Storage): def register(self, model_cls): """ - Register the model into the model storage. + Register a storage model API ("MAPI"). - :param model_cls: the model to register. - :return: + :param model_cls: model API to register """ model_name = model_cls.__modelname__ if model_name in self.registered: @@ -166,9 +141,7 @@ class ModelStorage(Storage): def drop(self): """ - Drop all the tables from the model. - - :return: + Drop all the tables. """ for mapi in self.registered.values(): mapi.drop() http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/storage/exceptions.py ---------------------------------------------------------------------- diff --git a/aria/storage/exceptions.py b/aria/storage/exceptions.py index 3f0ecec..c538876 100644 --- a/aria/storage/exceptions.py +++ b/aria/storage/exceptions.py @@ -12,9 +12,11 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. + """ -Storage based exceptions +Storage exceptions. """ + from .. import exceptions http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/storage/filesystem_rapi.py ---------------------------------------------------------------------- diff --git a/aria/storage/filesystem_rapi.py b/aria/storage/filesystem_rapi.py index 3ddc520..b425fa2 100644 --- a/aria/storage/filesystem_rapi.py +++ b/aria/storage/filesystem_rapi.py @@ -12,9 +12,11 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. + """ -File system based RAPI +File system implementation of the storage resource API ("RAPI"). """ + import os import shutil from multiprocessing import RLock @@ -30,13 +32,12 @@ from aria.storage import ( class FileSystemResourceAPI(api.ResourceAPI): """ - File system resource storage. + File system implementation of the storage resource API ("RAPI"). """ def __init__(self, directory, **kwargs): """ - File system implementation for storage api. - :param str directory: root dir for storage. + :param directory: root dir for storage """ super(FileSystemResourceAPI, self).__init__(**kwargs) self.directory = directory @@ -47,8 +48,7 @@ class FileSystemResourceAPI(api.ResourceAPI): @contextmanager def connect(self): """ - Established a connection and destroys it after use. - :return: + Establishes a connection and destroys it after use. """ try: self._establish_connection() @@ -60,16 +60,13 @@ class FileSystemResourceAPI(api.ResourceAPI): def _establish_connection(self): """ - Establish a conenction. used in the 'connect' contextmanager. - :return: + Establishes a connection. Used in the ``connect`` context manager. """ self._lock.acquire() - def _destroy_connection(self): """ - Destroy a connection. used in the 'connect' contextmanager. - :return: + Destroys a connection. Used in the ``connect`` context manager. """ self._lock.release() @@ -79,9 +76,9 @@ class FileSystemResourceAPI(api.ResourceAPI): def create(self, **kwargs): """ - Create directory in storage by path. - tries to create the root directory as well. - :param str name: path of file in storage. + Creates a directory in by path. Tries to create the root directory as well. + + :param name: path of directory """ try: os.makedirs(self.directory) @@ -94,11 +91,11 @@ class FileSystemResourceAPI(api.ResourceAPI): def read(self, entry_id, path, **_): """ - Retrieve the content of a file system storage resource. + Retrieves the contents of a file. - :param str entry_id: the id of the entry. - :param str path: a path to the specific resource to read. - :return: the content of the file. + :param entry_id: entry ID + :param path: path to resource + :return: contents of the file :rtype: bytes """ resource_relative_path = os.path.join(self.name, entry_id, path or '') @@ -118,11 +115,11 @@ class FileSystemResourceAPI(api.ResourceAPI): def download(self, entry_id, destination, path=None, **_): """ - Download a specific file or dir from the file system resource storage. + Downloads a file or directory. - :param str entry_id: the id of the entry. - :param str destination: the destination to download to - :param str path: the path to download relative to the root of the entry (otherwise all). + :param entry_id: entry ID + :param destination: download destination + :param path: path to download relative to the root of the entry (otherwise all) """ resource_relative_path = os.path.join(self.name, entry_id, path or '') resource = os.path.join(self.directory, resource_relative_path) @@ -136,10 +133,10 @@ class FileSystemResourceAPI(api.ResourceAPI): def upload(self, entry_id, source, path=None, **_): """ - Uploads a specific file or dir to the file system resource storage. + Uploads a file or directory. - :param str entry_id: the id of the entry. - :param source: the source of the files to upload. + :param entry_id: entry ID + :param source: source of the files to upload :param path: the destination of the file/s relative to the entry root dir. """ resource_directory = os.path.join(self.directory, self.name, entry_id) @@ -153,10 +150,10 @@ class FileSystemResourceAPI(api.ResourceAPI): def delete(self, entry_id, path=None, **_): """ - Deletes a file system storage resource. + Deletes a file or directory. - :param str entry_id: the id of the entry. - :param str path: a path to delete relative to the root of the entry (otherwise all). + :param entry_id: entry ID + :param path: path to delete relative to the root of the entry (otherwise all) """ destination = os.path.join(self.directory, self.name, entry_id, path or '') if os.path.exists(destination): http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/storage/sql_mapi.py ---------------------------------------------------------------------- diff --git a/aria/storage/sql_mapi.py b/aria/storage/sql_mapi.py index f044bd6..975ada7 100644 --- a/aria/storage/sql_mapi.py +++ b/aria/storage/sql_mapi.py @@ -12,9 +12,11 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. + """ -SQLAlchemy based MAPI +SQLAlchemy implementation of the storage model API ("MAPI"). """ + import os import platform @@ -42,7 +44,7 @@ _predicates = {'ge': '__ge__', class SQLAlchemyModelAPI(api.ModelAPI): """ - SQL based MAPI. + SQLAlchemy implementation of the storage model API ("MAPI"). """ def __init__(self, @@ -55,7 +57,7 @@ class SQLAlchemyModelAPI(api.ModelAPI): def get(self, entry_id, include=None, **kwargs): """ - Return a single result based on the model class and element ID + Returns a single result based on the model class and element ID """ query = self._get_query(include, {'id': entry_id}) result = query.first() @@ -104,18 +106,18 @@ class SQLAlchemyModelAPI(api.ModelAPI): sort=None, **kwargs): """ - Return a (possibly empty) list of ``model_class`` results. + Returns a (possibly empty) list of ``model_class`` results. """ for result in self._get_query(include, filters, sort): yield self._instrument(result) def put(self, entry, **kwargs): """ - Create a ``model_class`` instance from a serializable ``model`` object + Creatse a ``model_class`` instance from a serializable ``model`` object. :param entry: dict with relevant kwargs, or an instance of a class that has a ``to_dict`` - method, and whose attributes match the columns of ``model_class`` (might also - be just an instance of ``model_class``) + method, and whose attributes match the columns of ``model_class`` (might also be just an + instance of ``model_class``) :return: an instance of ``model_class`` """ self._session.add(entry) @@ -124,7 +126,7 @@ class SQLAlchemyModelAPI(api.ModelAPI): def delete(self, entry, **kwargs): """ - Delete a single result based on the model class and element ID + Deletes a single result based on the model class and element ID. """ self._load_relationships(entry) self._session.delete(entry) @@ -133,7 +135,7 @@ class SQLAlchemyModelAPI(api.ModelAPI): def update(self, entry, **kwargs): """ - Add ``instance`` to the database session, and attempt to commit + Adds ``instance`` to the database session, and attempts to commit. :return: updated instance """ @@ -141,7 +143,7 @@ class SQLAlchemyModelAPI(api.ModelAPI): def refresh(self, entry): """ - Reload the instance with fresh information from the database + Reloads the instance with fresh information from the database. :param entry: instance to be re-loaded from the database :return: refreshed instance @@ -166,14 +168,14 @@ class SQLAlchemyModelAPI(api.ModelAPI): def drop(self): """ - Drop the table from the storage. + Drops the table. """ self.model_cls.__table__.drop(self._engine) def _safe_commit(self): """ Try to commit changes in the session. Roll back if exception raised SQLAlchemy errors and - rollbacks if they're caught. + rolls back if they're caught. """ try: self._session.commit() @@ -186,7 +188,7 @@ class SQLAlchemyModelAPI(api.ModelAPI): def _get_base_query(self, include, joins): """ - Create the initial query from the model class and included columns + Create the initial query from the model class and included columns. :param include: (possibly empty) list of columns to include in the query :return: SQLAlchemy AppenderQuery object @@ -206,7 +208,7 @@ class SQLAlchemyModelAPI(api.ModelAPI): @staticmethod def _get_joins(model_class, columns): """ - Get a list of all the tables on which we need to join + Gets a list of all the tables on which we need to join. :param columns: set of all attributes involved in the query """ @@ -230,11 +232,11 @@ class SQLAlchemyModelAPI(api.ModelAPI): @staticmethod def _sort_query(query, sort=None): """ - Add sorting clauses to the query + Adds sorting clauses to the query. :param query: base SQL query :param sort: optional dictionary where keys are column names to sort by, and values are - the order (asc/desc) + the order (asc/desc) :return: SQLAlchemy AppenderQuery object """ if sort: @@ -246,11 +248,11 @@ class SQLAlchemyModelAPI(api.ModelAPI): def _filter_query(self, query, filters): """ - Add filter clauses to the query + Adds filter clauses to the query. - :param query: Base SQL query + :param query: base SQL query :param filters: optional dictionary where keys are column names to filter by, and values - are values applicable for those columns (or lists of such values) + are values applicable for those columns (or lists of such values) :return: SQLAlchemy AppenderQuery object """ return self._add_value_filter(query, filters) @@ -273,14 +275,14 @@ class SQLAlchemyModelAPI(api.ModelAPI): filters=None, sort=None): """ - Get an SQL query object based on the params passed + Gets a SQL query object based on the params passed. - :param model_class: SQL DB table class + :param model_class: SQL database table class :param include: optional list of columns to include in the query :param filters: optional dictionary where keys are column names to filter by, and values - are values applicable for those columns (or lists of such values) + are values applicable for those columns (or lists of such values) :param sort: optional dictionary where keys are column names to sort by, and values are the - order (asc/desc) + order (asc/desc) :return: sorted and filtered query with only the relevant columns """ include, filters, sort, joins = self._get_joins_and_converted_columns( @@ -313,9 +315,9 @@ class SQLAlchemyModelAPI(api.ModelAPI): filters, sort): """ - Get a list of tables on which we need to join and the converted ``include``, ``filters`` and - ```sort`` arguments (converted to actual SQLAlchemy column/label objects instead of column - names). + Gets a list of tables on which we need to join and the converted ``include``, ``filters`` + and ```sort`` arguments (converted to actual SQLAlchemy column/label objects instead of + column names). """ include = include or [] filters = filters or dict() @@ -334,7 +336,7 @@ class SQLAlchemyModelAPI(api.ModelAPI): filters, sort): """ - Go over the optional parameters (include, filters, sort), and replace column names with + Gooes over the optional parameters (include, filters, sort), and replace column names with actual SQLAlechmy column objects. """ include = [self._get_column(c) for c in include] @@ -345,7 +347,7 @@ class SQLAlchemyModelAPI(api.ModelAPI): def _get_column(self, column_name): """ - Return the column on which an action (filtering, sorting, etc.) would need to be performed. + Returns the column on which an action (filtering, sorting, etc.) would need to be performed. Can be either an attribute of the class, or an association proxy linked to a relationship in the class. """ @@ -362,15 +364,16 @@ class SQLAlchemyModelAPI(api.ModelAPI): @staticmethod def _paginate(query, pagination): - """Paginate the query by size and offset + """ + Paginates the query by size and offset. :param query: current SQLAlchemy query object :param pagination: optional dict with size and offset keys :return: tuple with four elements: - * results: ``size`` items starting from ``offset`` - * the total count of items - * ``size`` [default: 0] - * ``offset`` [default: 0] + * results: ``size`` items starting from ``offset`` + * the total count of items + * ``size`` [default: 0] + * ``offset`` [default: 0] """ if pagination: size = pagination.get('size', 0) @@ -385,7 +388,7 @@ class SQLAlchemyModelAPI(api.ModelAPI): @staticmethod def _load_relationships(instance): """ - A helper method used to overcome a problem where the relationships that rely on joins aren't + Helper method used to overcome a problem where the relationships that rely on joins aren't being loaded automatically. """ for rel in instance.__mapper__.relationships: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/utils/archive.py ---------------------------------------------------------------------- diff --git a/aria/utils/archive.py b/aria/utils/archive.py index 3dfb204..29efcb1 100644 --- a/aria/utils/archive.py +++ b/aria/utils/archive.py @@ -11,7 +11,7 @@ # limitations under the License. """ -ARIA utilities archive module +Archive utilities. """ import os http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/utils/argparse.py ---------------------------------------------------------------------- diff --git a/aria/utils/argparse.py b/aria/utils/argparse.py index f8d7e88..a05a841 100644 --- a/aria/utils/argparse.py +++ b/aria/utils/argparse.py @@ -14,7 +14,7 @@ # limitations under the License. """ -ARIA utilities argparse module +Enhancements to Python's ``argparse`` module. """ from __future__ import absolute_import # so we can import standard 'argparse' http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/utils/caching.py ---------------------------------------------------------------------- diff --git a/aria/utils/caching.py b/aria/utils/caching.py index 4c3d82b..5f8cd88 100644 --- a/aria/utils/caching.py +++ b/aria/utils/caching.py @@ -14,7 +14,7 @@ # limitations under the License. """ -ARIA utilities caching module +Caching utilities. """ from __future__ import absolute_import # so we can import standard 'collections' and 'threading' http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/utils/collections.py ---------------------------------------------------------------------- diff --git a/aria/utils/collections.py b/aria/utils/collections.py index d8b7e90..ccc37a1 100644 --- a/aria/utils/collections.py +++ b/aria/utils/collections.py @@ -14,7 +14,7 @@ # limitations under the License. """ -ARIA utilities collections module +Additional collection classes and collection utilities. """ from __future__ import absolute_import # so we can import standard 'collections' @@ -36,7 +36,8 @@ class FrozenList(list): """ An immutable list. - After initialization it will raise :class:`TypeError` exceptions if modification is attempted. + After initialization it will raise :class:`~exceptions.TypeError` exceptions if modification is + attempted. Note that objects stored in the list may not be immutable. """ @@ -86,7 +87,8 @@ class FrozenDict(OrderedDict): """ An immutable ordered dict. - After initialization it will raise :class:`TypeError` exceptions if modification is attempted. + After initialization it will raise :class:`~exceptions.TypeError` exceptions if modification is + attempted. Note that objects stored in the dict may not be immutable. """ @@ -115,7 +117,8 @@ EMPTY_READ_ONLY_DICT = FrozenDict() class StrictList(list): """ - A list that raises :class:`TypeError` exceptions when objects of the wrong type are inserted. + A list that raises :class:`~exceptions.TypeError` exceptions when objects of the wrong type are + inserted. """ def __init__(self, @@ -175,8 +178,8 @@ class StrictList(list): class StrictDict(OrderedDict): """ - An ordered dict that raises :class:`TypeError` exceptions when keys or values of the wrong type - are used. + An ordered dict that raises :class:`~exceptions.TypeError` exceptions when keys or values of the + wrong type are used. """ def __init__(self, @@ -270,7 +273,7 @@ def prune(value, is_removable_function=is_removable): def deepcopy_with_locators(value): """ - Like :func:`deepcopy`, but also copies over locators. + Like :func:`~copy.deepcopy`, but also copies over locators. """ res = deepcopy(value) http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/5be27b0c/aria/utils/console.py ---------------------------------------------------------------------- diff --git a/aria/utils/console.py b/aria/utils/console.py index 9c89e5e..642cbb1 100644 --- a/aria/utils/console.py +++ b/aria/utils/console.py @@ -14,7 +14,7 @@ # limitations under the License. """ -ARIA utilities console module +Abstraction API above terminal color libraries. """ from clint.textui.core import STDOUT
