ariatosca-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From emblempar...@apache.org
Subject [3/4] incubator-ariatosca git commit: Final work
Date Wed, 28 Jun 2017 23:29:25 GMT
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



Mime
View raw message