ariatosca-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From emblempar...@apache.org
Subject [2/2] incubator-ariatosca git commit: Many improvements to docs
Date Mon, 26 Jun 2017 22:35:50 GMT
Many improvements to docs


Project: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/commit/7ed92d0f
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/tree/7ed92d0f
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/diff/7ed92d0f

Branch: refs/heads/ARIA-286-sphinx-documentation
Commit: 7ed92d0fe6edd0f44ea36c7ddd9403d62f9cead7
Parents: 6621327
Author: Tal Liron <tal.liron@gmail.com>
Authored: Mon Jun 26 17:35:35 2017 -0500
Committer: Tal Liron <tal.liron@gmail.com>
Committed: Mon Jun 26 17:35:35 2017 -0500

----------------------------------------------------------------------
 aria/__init__.py                             |  12 +-
 aria/cli/color.py                            |   3 +-
 aria/cli/core/aria.py                        |   9 +-
 aria/cli/defaults.py                         |   9 +-
 aria/cli/service_template_utils.py           |  55 +--
 aria/cli/table.py                            |  54 +--
 aria/cli/utils.py                            |  24 +-
 aria/core.py                                 |   2 +-
 aria/exceptions.py                           |   9 +-
 aria/extension.py                            |  32 +-
 aria/logger.py                               |  35 +-
 aria/modeling/__init__.py                    |   2 +-
 aria/modeling/constraints.py                 |   4 +-
 aria/modeling/exceptions.py                  |   2 +-
 aria/modeling/functions.py                   |  21 +-
 aria/modeling/mixins.py                      |  54 +--
 aria/modeling/models.py                      |   2 +-
 aria/modeling/orchestration.py               |  60 ++--
 aria/modeling/service_common.py              |  47 +--
 aria/modeling/service_instance.py            | 334 +++++++++---------
 aria/modeling/service_template.py            | 396 +++++++++++-----------
 aria/modeling/types.py                       |  47 ++-
 aria/modeling/utils.py                       |  19 +-
 aria/orchestrator/decorators.py              |   4 +-
 aria/orchestrator/workflows/api/task.py      |  10 +-
 aria/parser/consumption/context.py           |  26 +-
 aria/parser/consumption/presentation.py      |   6 +-
 aria/parser/loading/context.py               |   6 +-
 aria/parser/loading/literal.py               |   2 +-
 aria/parser/loading/location.py              |   8 +-
 aria/parser/loading/uri.py                   |   6 +-
 aria/parser/modeling/context.py              |  20 +-
 aria/parser/presentation/context.py          |  26 +-
 aria/parser/presentation/field_validators.py |  19 +-
 aria/parser/presentation/fields.py           |  31 +-
 aria/parser/presentation/null.py             |   4 +-
 aria/parser/presentation/presentation.py     |  54 ++-
 aria/parser/presentation/source.py           |   2 +-
 aria/parser/presentation/utils.py            |  12 +-
 aria/parser/reading/context.py               |   8 +-
 aria/parser/reading/locator.py               |   4 +-
 aria/parser/reading/reader.py                |   2 +-
 aria/parser/validation/context.py            |  15 +-
 aria/utils/__init__.py                       |   2 +-
 aria/utils/argparse.py                       |   2 +-
 aria/utils/caching.py                        |   5 +-
 aria/utils/collections.py                    |   8 +-
 aria/utils/formatting.py                     |  29 +-
 aria/utils/threading.py                      |   5 +-
 aria/utils/uris.py                           |   2 +-
 docs/aria.modeling.rst                       |   5 +
 docs/conf.py                                 |  53 ++-
 52 files changed, 868 insertions(+), 740 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/__init__.py
----------------------------------------------------------------------
diff --git a/aria/__init__.py b/aria/__init__.py
index 5eea665..521fc48 100644
--- a/aria/__init__.py
+++ b/aria/__init__.py
@@ -44,13 +44,17 @@ __all__ = (
     '__version__',
     'workflow',
     'operation',
+    'install_aria_extensions',
+    'application_model_storage',
+    'application_resource_storage'
 )
 
 
 def install_aria_extensions():
     """
-    Iterates all Python packages with names beginning with :code:`aria_extension_` and all
-    :code:`aria_extension` entry points and loads them.
+    Iterates all Python packages with names beginning with ``aria_extension_`` and all
+    ``aria_extension`` entry points and loads them.
+
     It then invokes all registered extension functions.
     """
     for loader, module_name, _ in iter_modules():
@@ -63,7 +67,7 @@ def install_aria_extensions():
 
 def application_model_storage(api, api_kwargs=None, initiator=None, initiator_kwargs=None):
     """
-    Initiate model storage
+    Initiate model storage.
     """
     return storage.ModelStorage(api_cls=api,
                                 api_kwargs=api_kwargs,
@@ -74,7 +78,7 @@ def application_model_storage(api, api_kwargs=None, initiator=None, initiator_kw
 
 def application_resource_storage(api, api_kwargs=None, initiator=None, initiator_kwargs=None):
     """
-    Initiate resource storage
+    Initiate resource storage.
     """
 
     return storage.ResourceStorage(api_cls=api,

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/cli/color.py
----------------------------------------------------------------------
diff --git a/aria/cli/color.py b/aria/cli/color.py
index 0761f6b..03381ba 100644
--- a/aria/cli/color.py
+++ b/aria/cli/color.py
@@ -80,8 +80,7 @@ class ColorSpec(object):
     def __init__(self, fore=None, back=None, style=None):
         """
         It is possible to provide fore, back and style arguments. each could be either
-        the color is lower case letter, or the actual color from colorama.
-
+        the color is lower case letter, or the actual color from Colorama.
         """
         self._kwargs = dict(fore=fore, back=back, style=style)
         self._str = StringIO()

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/cli/core/aria.py
----------------------------------------------------------------------
diff --git a/aria/cli/core/aria.py b/aria/cli/core/aria.py
index bcff367..344aacc 100644
--- a/aria/cli/core/aria.py
+++ b/aria/cli/core/aria.py
@@ -251,9 +251,8 @@ class AliasedGroup(click.Group):
 
     def resolve_command(self, ctx, args):
         """
-        Override clicks ``resolve_command`` method
-        and appends *Did you mean ...* suggestions
-        to the raised exception message.
+        Override clicks ``resolve_command`` method and appends *Did you mean ...* suggestions to the
+        raised exception message.
         """
         try:
             return super(AliasedGroup, self).resolve_command(ctx, args)
@@ -274,7 +273,7 @@ class AliasedGroup(click.Group):
 
 def group(name):
     """
-    Allow to create a group with a default click context and a cls for click's ``didyoueamn``
+    Allow to create a group with a default click context and a class for Click's ``didyoueamn``
     without having to repeat it for every group.
     """
     return click.group(
@@ -295,7 +294,7 @@ def command(*args, **kwargs):
 
 def argument(*args, **kwargs):
     """
-    Make Click arguments ARIA specific.
+    Make Click arguments specific to ARIA.
 
     This exists purely for aesthetic reasons, otherwise some decorators are called
     ``@click.something`` instead of ``@aria.something``

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/cli/defaults.py
----------------------------------------------------------------------
diff --git a/aria/cli/defaults.py b/aria/cli/defaults.py
index 8c1f3ae..e84abc0 100644
--- a/aria/cli/defaults.py
+++ b/aria/cli/defaults.py
@@ -14,10 +14,17 @@
 # limitations under the License.
 
 """
-CLI defaults.
+Various CLI default values.
 """
 
+#: Default service template filename
 SERVICE_TEMPLATE_FILENAME = 'service_template.yaml'
+
+#: Default task max attempts
 TASK_MAX_ATTEMPTS = 30
+
+#: Default task retry interval
 TASK_RETRY_INTERVAL = 30
+
+#: Default sort descending
 SORT_DESCENDING = False

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/cli/service_template_utils.py
----------------------------------------------------------------------
diff --git a/aria/cli/service_template_utils.py b/aria/cli/service_template_utils.py
index 8d4b009..abfbf9a 100644
--- a/aria/cli/service_template_utils.py
+++ b/aria/cli/service_template_utils.py
@@ -31,21 +31,20 @@ def get(source, service_template_filename):
     Get a source and return a path to the main service template file
 
     The behavior based on then source argument content is:
-        - local ``.yaml`` file: return the file
-        - local archive (``.csar``, ``.zip``, ``.tar``, ``.tar.gz``, and ``.tar.bz2``):
-            extract it locally and return path service template file
-        - URL:
-            - download and get service template from downloaded archive
-        - GitHub repo:
-            - download and get service template from downloaded archive
-
-    :param source: Path/URL/github repo to archive/service-template file
-    :type source: str
-    :param service_template_filename: Path to service template (if source is an archive [but
-     not a csar archive - with csars archives, this is read from the metadata file])
-    :type service_template_filename: str
-    :return: Path to main service template file
-    :rtype: str
+
+    * local ``.yaml`` file: return the file
+    * local archive (``.csar``, ``.zip``, ``.tar``, ``.tar.gz``, and ``.tar.bz2``): extract it
+      locally and return path service template file
+    * URL: download and get service template from downloaded archive
+    * GitHub repo: download and get service template from downloaded archive
+
+    :param source: path/URL/GitHub repo to archive/service-template file
+    :type source: basestring
+    :param service_template_filename: path to service template if source is a non-CSAR archive
+                                      (with CSAR archives, this is read from the metadata file)
+    :type service_template_filename: basestring
+    :return: path to main service template file
+    :rtype: basestring
     """
     if urlparse(source).scheme:
         downloaded_file = utils.download_file(source)
@@ -69,14 +68,15 @@ def get(source, service_template_filename):
 
 
 def _get_service_template_file_from_archive(archive, service_template_filename):
-    """Extract archive to temporary location and get path to service template file.
+    """
+    Extract archive to temporary location and get path to service template file.
 
-    :param archive: Path to archive file
-    :type archive: str
-    :param service_template_filename: Path to service template file relative to archive
-    :type service_template_filename: str
-    :return: Absolute path to service template file
-    :rtype: str
+    :param archive: path to archive file
+    :type archive: basestring
+    :param service_template_filename: path to service template file relative to archive
+    :type service_template_filename: basestring
+    :return: absolute path to service template file
+    :rtype: basestring
 
     """
     if csar.is_csar_archive(archive):
@@ -98,12 +98,13 @@ def _get_service_template_file_from_archive(archive, service_template_filename):
 
 
 def _map_to_github_url(source):
-    """Returns a path to a downloaded github archive.
+    """
+    Returns a path to a downloaded GitHub archive.
 
-    :param source: github repo in the format of `org/repo[:tag/branch]`.
-    :type source: str
-    :return: URL to the archive file for the given repo in github
-    :rtype: str
+    :param source: GitHub repo: ``org/repo[:tag/branch]``
+    :type source: basestring
+    :return: URL to the archive file for the given repo in GitHub
+    :rtype: basestring
 
     """
     source_parts = source.split(':', 1)

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/cli/table.py
----------------------------------------------------------------------
diff --git a/aria/cli/table.py b/aria/cli/table.py
index 9e53437..a4e959c 100644
--- a/aria/cli/table.py
+++ b/aria/cli/table.py
@@ -27,6 +27,24 @@ from .env import logger
 
 def print_data(columns, items, header_text,
                column_formatters=None, col_max_width=None, defaults=None):
+    """
+    Prints data in a tabular form.
+
+    :param columns: columns of the table, e.g. ``['id','name']``
+    :type columns: iterable of basestring
+    :param items: each element must have keys or attributes corresponding to the ``columns`` items,
+                  e.g. ``[{'id':'123', 'name':'Pete'}]``
+    :type data: [{:obj:`basestring`: :obj:`basestring`}]
+    :param column_formatters: maps column name to formatter, a function that may manipulate the
+                              string values printed for this column, e.g. 
+                              ``{'created_at': timestamp_formatter}``
+    :param col_max_width: maximum width of table
+    :type col_max_width: int
+    :type column_formatters: {obj:`basestring`: :obj:`function`}
+    :param defaults: default values for keys that don't exist in the data itself, e.g.
+                     ``{'serviceId':'123'}``
+    :type defaults: {:obj:`basestring`: :obj:`basestring`}
+    """
     if items is None:
         items = []
     elif not isinstance(items, list):
@@ -47,30 +65,18 @@ def _generate(cols, data, column_formatters=None, defaults=None):
     """
     Return a new PrettyTable instance representing the list.
 
-    Arguments:
-
-        cols - An iterable of strings that specify what
-               are the columns of the table.
-
-               for example: ['id','name']
-
-        data - An iterable of dictionaries or objects, each element must
-               have keys or attributes corresponding to the cols items.
-
-               for example: [{'id':'123', 'name':'Pete'}]
-
-        column_formatters - A dictionary from a column name to a formatter - a function that
-                            may manipulate the string values printed for this column.
-                            (See below for a few built-in formatter examples)
-
-                            for example: {'created_at': timestamp_formatter}
-
-        defaults - A dictionary specifying default values for
-                   key's that don't exist in the data itself.
-
-                   for example: {'serviceId':'123'} will set the
-                   serviceId value for all rows to '123'.
-
+    :param cols: columns of the table, e.g. ``['id','name']``
+    :type cols: iterable of :obj:`basestring`
+    :param data: each element must have keys or attributes corresponding to the ``cols`` items,
+                 e.g. ``[{'id':'123', 'name':'Pete'}]``
+    :type data: [{:obj:`basestring`: :obj:`basestring`}]
+    :param column_formatters: maps column name to formatter, a function that may manipulate the
+                              string values printed for this column, e.g. 
+                              ``{'created_at': timestamp_formatter}``
+    :type column_formatters: {:obj:`basestring`: :obj:`function`}
+    :param defaults: default values for keys that don't exist in the data itself, e.g.
+                     ``{'serviceId':'123'}``
+    :type defaults: {:obj:`basestring`: :obj:`basestring`}
     """
     def get_values_per_column(column, row_data):
         if hasattr(row_data, column) or (isinstance(row_data, dict) and column in row_data):

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/cli/utils.py
----------------------------------------------------------------------
diff --git a/aria/cli/utils.py b/aria/cli/utils.py
index 0ceb2ea..0d0666b 100644
--- a/aria/cli/utils.py
+++ b/aria/cli/utils.py
@@ -48,8 +48,8 @@ def get_parameter_templates_as_string(parameter_templates):
 
 def check_overriding_storage_exceptions(e, model_class, name):
     """
-    This method checks whether the storage exception is a known type where we'd like to override
-     the exception message; If so, it raises a new error. Otherwise it simply returns.
+    Checks whether the storage exception is a known type where we'd like to override the exception
+    message; If so, it raises a new error. Otherwise it simply returns.
     """
     assert isinstance(e, BaseException)
     if 'UNIQUE constraint failed' in e.message:
@@ -72,12 +72,13 @@ def download_file(url):
 
 
 def generate_progress_handler(file_path, action='', max_bar_length=80):
-    """Returns a function that prints a progress bar in the terminal
+    """
+    Returns a function that prints a progress bar in the terminal.
 
-    :param file_path: The name of the file being transferred
-    :param action: Uploading/Downloading
-    :param max_bar_length: Maximum allowed length of the bar. Default: 80
-    :return: The configured print_progress function
+    :param file_path: the name of the file being transferred
+    :param action: uploading/downloading
+    :param max_bar_length: maximum allowed length of the bar
+    :return: configured ``print_progress`` function
     """
     # We want to limit the maximum line length to 80, but allow for a smaller
     # terminal size. We also include the action string, and some extra chars
@@ -95,12 +96,13 @@ def generate_progress_handler(file_path, action='', max_bar_length=80):
     bar_length -= len(file_name)
 
     def print_progress(read_bytes, total_bytes):
-        """Print upload/download progress on a single line
+        """
+        Print upload/download progress on a single line.
 
-        Call this function in a loop to create a progress bar in the terminal
+        Call this function in a loop to create a progress bar in the terminal.
 
-        :param read_bytes: Number of bytes already processed
-        :param total_bytes: Total number of bytes in the file
+        :param read_bytes: number of bytes already processed
+        :param total_bytes: total number of bytes in the file
         """
 
         filled_length = min(bar_length, int(round(bar_length * read_bytes /

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/core.py
----------------------------------------------------------------------
diff --git a/aria/core.py b/aria/core.py
index 830a841..a8d5245 100644
--- a/aria/core.py
+++ b/aria/core.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-ARIA core module
+ARIA core module.
 """
 
 from . import exceptions

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/exceptions.py b/aria/exceptions.py
index b7705ea..5d3e21d 100644
--- a/aria/exceptions.py
+++ b/aria/exceptions.py
@@ -14,8 +14,7 @@
 # limitations under the License.
 
 """
-The ARIA exceptions module provides base exception classes and other common exceptions used
-throughout ARIA.
+Base exception classes and other common exceptions used throughout ARIA.
 """
 
 import sys
@@ -47,21 +46,21 @@ class AriaException(Exception):
 
 class DependentServicesError(AriaError):
     """
-    Raised when attempting to delete a service template which has existing services
+    Raised when attempting to delete a service template which has existing services.
     """
     pass
 
 
 class DependentActiveExecutionsError(AriaError):
     """
-    Raised when attempting to delete a service which has active executions
+    Raised when attempting to delete a service which has active executions.
     """
     pass
 
 
 class DependentAvailableNodesError(AriaError):
     """
-    Raised when attempting to delete a service which has available nodes
+    Raised when attempting to delete a service which has available nodes.
     """
     pass
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/extension.py
----------------------------------------------------------------------
diff --git a/aria/extension.py b/aria/extension.py
index 3065435..e90750d 100644
--- a/aria/extension.py
+++ b/aria/extension.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-The ARIA extension module provides a mechanism for registering and loading ARIA extensions.
+Mechanism for registering and loading ARIA extensions.
 """
 
 # pylint: disable=no-self-use
@@ -53,7 +53,9 @@ def _registrar(function):
 
 
 class _ExtensionRegistration(object):
-    """Base class for extension class decorators"""
+    """
+    Base class for extension class decorators.
+    """
 
     def __init__(self):
         self._registrars = {}
@@ -74,7 +76,7 @@ class _ExtensionRegistration(object):
 
     def init(self):
         """
-        Initialize all registrars by calling all registered functions
+        Initialize all registrars by calling all registered functions.
         """
         registered_instances = [cls() for cls in self._registered_classes]
         for name, registrar in self._registrars.items():
@@ -85,13 +87,16 @@ class _ExtensionRegistration(object):
 
 
 class _ParserExtensionRegistration(_ExtensionRegistration):
-    """Parser extensions class decorator"""
+    """
+    Parser extensions class decorator.
+    """
 
     @_registrar
     def presenter_class(self):
         """
         Presentation class registration.
-        Implementing functions can return a single class or a list/tuple of classes
+
+        Implementing functions can return a single class or a list/tuple of classes.
         """
         return []
 
@@ -99,7 +104,8 @@ class _ParserExtensionRegistration(_ExtensionRegistration):
     def specification_package(self):
         """
         Specification package registration.
-        Implementing functions can return a package name or a list/tuple of names
+
+        Implementing functions can return a package name or a list/tuple of names.
         """
         return []
 
@@ -107,7 +113,8 @@ class _ParserExtensionRegistration(_ExtensionRegistration):
     def specification_url(self):
         """
         Specification URL registration.
-        Implementing functions should return a dictionary from names to URLs
+
+        Implementing functions should return a dictionary from names to URLs.
         """
         return {}
 
@@ -115,7 +122,8 @@ class _ParserExtensionRegistration(_ExtensionRegistration):
     def uri_loader_prefix(self):
         """
         URI loader prefix registration.
-        Implementing functions can return a single prefix or a list/tuple of prefixes
+
+        Implementing functions can return a single prefix or a list/tuple of prefixes.
         """
         return collections.StrictList(value_class=basestring)
 
@@ -123,13 +131,15 @@ parser = _ParserExtensionRegistration()
 
 
 class _ProcessExecutorExtensionRegistration(_ExtensionRegistration):
-    """Process executor extension class decorator"""
+    """
+    Process executor extension class decorator.
+    """
 
     @_registrar
     def decorate(self):
         """
         The operation function executed by the process executor will be decorated with the function
-        returned from decorate().
+        returned from ``decorate()``.
         """
         return []
 
@@ -138,7 +148,7 @@ process_executor = _ProcessExecutorExtensionRegistration()
 
 def init():
     """
-    Initialize all registrars by calling all registered functions
+    Initialize all registrars by calling all registered functions.
     """
     parser.init()
     process_executor.init()

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/logger.py
----------------------------------------------------------------------
diff --git a/aria/logger.py b/aria/logger.py
index 0f35752..2ccff25 100644
--- a/aria/logger.py
+++ b/aria/logger.py
@@ -14,8 +14,8 @@
 # limitations under the License.
 
 """
-The ARIA logger module provides mix-ins and functions for logging, supporting multiple backends
-(such as SQL) and consistent formatting.
+Mix-ins and functions for logging, supporting multiple backends (such as SQL) and consistent
+formatting.
 """
 
 import logging
@@ -39,12 +39,11 @@ _base_logger = logging.getLogger('aria')
 
 class LoggerMixin(object):
     """
-    Mixin Logger Class
-    configuration (class members):
+    Provides logging functionality to a class.
 
-    logger_name: logger name [default: <class_name>]
-    logger_level: logger level [default: logging.DEBUG]
-    base_logger: This Mixing will create child logger from this base_logger [default: root logger]
+    :ivar logger_name: logger name; default to the class name
+    :ivar logger_level: logger level; defaults to `logging.DEBUG`
+    :ivar base_logger: child loggers are created from this; defaults to the root logger
     """
     logger_name = None
     logger_level = logging.DEBUG
@@ -67,7 +66,7 @@ class LoggerMixin(object):
             base_logger=logging.getLogger(),
             **kwargs):
         """
-        Set the logger used by the consuming class
+        Set the logger used by the consuming class.
         """
         cls.logger_name = logger_name
         cls.logger_level = logger_level
@@ -87,10 +86,12 @@ class LoggerMixin(object):
 
 def create_logger(logger=_base_logger, handlers=(), **configs):
     """
-
-    :param logging.Logger logger: The logger name [default: aria logger]
-    :param list handlers: The logger handlers
-    :param configs: The logger configurations
+    :param logger: logger name; defaults to ARIA logger
+    :type logger: logging.Logger
+    :param handlers: logger handlers
+    :type handlers: []
+    :param configs: logger configurations
+    :type configs: []
     :return: logger
     """
     logger.handlers = []
@@ -104,7 +105,6 @@ def create_logger(logger=_base_logger, handlers=(), **configs):
 
 def create_console_log_handler(level=logging.DEBUG, formatter=None):
     """
-
     :param level:
     :param formatter:
     :return:
@@ -124,10 +124,9 @@ def create_sqla_log_handler(model, log_cls, execution_id, level=logging.DEBUG):
 
 class _DefaultConsoleFormat(logging.Formatter):
     """
-    _DefaultConsoleFormat class
-    Console logger formatter
-    info level logs format: '%(message)s'
-    every other log level are formatted: '%(levelname)s: %(message)s'
+    Info level log format: ``%(message)s``
+    
+    Every other log level is formatted: ``%(levelname)s: %(message)s``
     """
     def format(self, record):
         try:
@@ -148,7 +147,7 @@ def create_file_log_handler(
         backup_count=10,
         formatter=None):
     """
-    Create a logging.handlers.RotatingFileHandler
+    Create a :class:`logging.handlers.RotatingFileHandler`.
     """
     rotating_file = logging_handlers.RotatingFileHandler(
         filename=file_path,

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/__init__.py
----------------------------------------------------------------------
diff --git a/aria/modeling/__init__.py b/aria/modeling/__init__.py
index 4ec6b2c..57bc188 100644
--- a/aria/modeling/__init__.py
+++ b/aria/modeling/__init__.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-ARIA modeling package
+This package provides an API for modeling ARIA's state and serializing it to storage.
 """
 
 from collections import namedtuple

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/constraints.py
----------------------------------------------------------------------
diff --git a/aria/modeling/constraints.py b/aria/modeling/constraints.py
index 45b3861..8ed33d5 100644
--- a/aria/modeling/constraints.py
+++ b/aria/modeling/constraints.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-ARIA modeling constraints module
+Constraints for the requirements-and-capabilities matching mechanism.
 """
 
 class NodeTemplateConstraint(object):
@@ -26,6 +26,6 @@ class NodeTemplateConstraint(object):
 
     def matches(self, source_node_template, target_node_template):
         """
-        Returns true is the target matches the constraint for the source.
+        Returns ``True`` if the target matches the constraint for the source.
         """
         raise NotImplementedError

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/exceptions.py
----------------------------------------------------------------------
diff --git a/aria/modeling/exceptions.py b/aria/modeling/exceptions.py
index 19e664a..573efaf 100644
--- a/aria/modeling/exceptions.py
+++ b/aria/modeling/exceptions.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-ARIA modeling exceptions module
+Modeling exceptions.
 """
 
 from ..exceptions import AriaException

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/functions.py
----------------------------------------------------------------------
diff --git a/aria/modeling/functions.py b/aria/modeling/functions.py
index 06f6c32..b764aa8 100644
--- a/aria/modeling/functions.py
+++ b/aria/modeling/functions.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-ARIA modeling functions module
+Mechanism for evaluating intrinsic functions.
 """
 
 from ..parser.consumption import ConsumptionContext
@@ -38,10 +38,11 @@ class Function(object):
 
     def __evaluate__(self, container_holder):
         """
-        Evaluates the function if possible. If impossible, raises
-        :class:`CannotEvaluateFunctionException` (do not just return None).
+        Evaluates the function if possible.
 
-        :rtype: Evaluation (or any object with ``value`` and ``final`` properties)
+        :rtype: :class:`Evaluation` (or any object with ``value`` and ``final`` properties)
+        :raises CannotEvaluateFunctionException: if cannot be evaluated at this time (do *not* just
+                                                 return ``None``) 
         """
 
         raise NotImplementedError
@@ -54,6 +55,10 @@ class Function(object):
 class Evaluation(object):
     """
     An evaluated :class:`Function` return value.
+    
+    :ivar value: evaluated value
+    :ivar final: whether the value is final
+    :vartype final: boolean
     """
 
     def __init__(self, value, final=False):
@@ -64,13 +69,13 @@ class Evaluation(object):
 def evaluate(value, container_holder, report_issues=False): # pylint: disable=too-many-branches
     """
     Recursively attempts to call ``__evaluate__``. If an evaluation occurred will return an
-    :class:`Evaluation`, otherwise it will be None. If any evaluation is non-final, then the entire
-    evaluation will also be non-final.
+    :class:`Evaluation`, otherwise it will be ``None``. If any evaluation is non-final, then the
+    entire evaluation will also be non-final.
 
     The ``container_holder`` argument should have three properties: ``container`` should return
     the model that contains the value, ``service`` should return the containing
-    :class:`aria.modeling.models.Service` model or None, and ``service_template`` should return the
-    containing :class:`aria.modeling.models.ServiceTemplate` model or None.
+    :class:`~aria.modeling.models.Service` model or None, and ``service_template`` should return the
+    containing :class:`~aria.modeling.models.ServiceTemplate` model or ``None``.
     """
 
     evaluated = False

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/mixins.py
----------------------------------------------------------------------
diff --git a/aria/modeling/mixins.py b/aria/modeling/mixins.py
index 134748d..e707f02 100644
--- a/aria/modeling/mixins.py
+++ b/aria/modeling/mixins.py
@@ -13,7 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""'
+"""
 ARIA modeling mix-ins module
 """
 
@@ -49,7 +49,7 @@ class ModelMixin(object):
         """
         Create a dict representation of the model.
 
-        :param suppress_error: If set to ``True``, sets ``None`` to attributes that it's unable to
+        :param suppress_error: if set to ``True``, sets ``None`` to attributes that it's unable to
                                retrieve (e.g., if a relationship wasn't established yet, and so it's
                                impossible to access a property through it)
         """
@@ -84,7 +84,7 @@ class ModelMixin(object):
 
         fields = set(cls._iter_association_proxies())
         fields.update(cls.__table__.columns.keys())
-        return fields - set(getattr(cls, '__private_fields__', []))
+        return fields - set(getattr(cls, '__private_fields__', ()))
 
     @classmethod
     def _iter_association_proxies(cls):
@@ -113,10 +113,10 @@ class ModelIDMixin(object):
 
 class InstanceModelMixin(ModelMixin):
     """
-    Mixin for :class:`ServiceInstance` models.
+    Mix-in for service instance models.
 
-    All models support validation, diagnostic dumping, and representation as
-    raw data (which can be translated into JSON or YAML) via ``as_raw``.
+    All models support validation, diagnostic dumping, and representation as raw data (which can be
+    translated into JSON or YAML) via ``as_raw``.
     """
 
     @property
@@ -135,9 +135,9 @@ class InstanceModelMixin(ModelMixin):
 
 class TemplateModelMixin(InstanceModelMixin):
     """
-    Mixin for :class:`ServiceTemplate` models.
+    Mix-in for service template models.
 
-    All model models can be instantiated into :class:`ServiceInstance` models.
+    All model models can be instantiated into service instance models.
     """
 
     def instantiate(self, container):
@@ -146,16 +146,17 @@ class TemplateModelMixin(InstanceModelMixin):
 
 class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):                                 #pylint: disable=abstract-method
     """
-    Represents a typed value. The value can contain nested intrinsic functions.
+    Mix-in for typed values. The value can contain nested intrinsic functions.
 
-    This model can be used as the ``container_holder`` argument for :func:`functions.evaluate`.
+    This model can be used as the ``container_holder`` argument for
+    :func:`~aria.modeling.functions.evaluate`.
 
-    :ivar name: Name
+    :ivar name: name
     :vartype name: basestring
-    :ivar type_name: Type name
+    :ivar type_name: type name
     :vartype type_name: basestring
-    :ivar value: Value
-    :ivar description: Description
+    :ivar value: value
+    :ivar description: description
     :vartype description: basestring
     """
 
@@ -185,8 +186,10 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):
         """
         The sole owner of this parameter, which is another model that relates to it.
 
-        *All* parameters should have an owner model. In case this property method fails to find
-        it, it will raise a ValueError, which should signify an abnormal, orphaned parameter.
+        *All* parameters should have an owner model.
+
+        :raises exceptions.ValueError: if failed to find an owner, which signifies an abnormal,
+                                       orphaned parameter
         """
 
         # Find first non-null relationship
@@ -208,8 +211,10 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):
         The logical container is equivalent to the ``SELF`` keyword used by intrinsic functions in
         TOSCA.
 
-        *All* parameters should have a container model. In case this property method fails to find
-        it, it will raise a ValueError, which should signify an abnormal, orphaned parameter.
+        *All* parameters should have a container model.
+
+        :raises exceptions.ValueError: if failed to find a container model, which signifies an
+                                       abnormal, orphaned parameter
         """
 
         from . import models
@@ -251,7 +256,11 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):
     @caching.cachedmethod
     def service(self):
         """
-        The :class:`Service` containing this parameter, or None if not contained in a service.
+        The :class:`~aria.modeling.models.Service` model containing this parameter, or ``None`` if
+        not contained in a service.
+
+        :raises exceptions.ValueError: if failed to find a container model, which signifies an
+                                       abnormal, orphaned parameter
         """
 
         from . import models
@@ -266,8 +275,11 @@ class ParameterMixin(TemplateModelMixin, caching.HasCachedMethods):
     @caching.cachedmethod
     def service_template(self):
         """
-        The :class:`ServiceTemplate` containing this parameter, or None if not contained in a
-        service template.
+        The :class:`~aria.modeling.models.ServiceTemplate` model containing this parameter, or
+        ``None`` if not contained in a service template.
+
+        :raises exceptions.ValueError: if failed to find a container model, which signifies an
+                                       abnormal, orphaned parameter
         """
 
         from . import models

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/models.py
----------------------------------------------------------------------
diff --git a/aria/modeling/models.py b/aria/modeling/models.py
index d15f791..129b5bb 100644
--- a/aria/modeling/models.py
+++ b/aria/modeling/models.py
@@ -14,7 +14,7 @@
 # limitations under the License.
 
 """
-Modeling models module
+Models.
 """
 
 # pylint: disable=abstract-method

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/orchestration.py
----------------------------------------------------------------------
diff --git a/aria/modeling/orchestration.py b/aria/modeling/orchestration.py
index bd89ddb..6096fcc 100644
--- a/aria/modeling/orchestration.py
+++ b/aria/modeling/orchestration.py
@@ -157,37 +157,37 @@ class PluginBase(mixins.ModelMixin):
     are archives of one or more `wheels <https://packaging.python.org/distributing/#wheels>`__.
     Most of these fields are indeed extracted from the installed wagon's metadata.
 
-    :ivar archive_name: Filename (not the full path) of the wagon's archive, often with a ".wgn"
+    :ivar archive_name: filename (not the full path) of the wagon's archive, often with a ".wgn"
                         extension
     :vartype archive_name: basestring
-    :ivar distribution: The name of the operating system on which the wagon was installed (e.g.
+    :ivar distribution: name of the operating system on which the wagon was installed (e.g.
                         "ubuntu")
     :vartype distribution: basestring
-    :ivar distribution_release: The release of the operating system on which the wagon was installed
+    :ivar distribution_release: release of the operating system on which the wagon was installed
                                 (e.g. "trusty")
     :vartype distribution_release: basestring
-    :ivar distribution_version: The version of the operating system on which the wagon was installed
+    :ivar distribution_version: version of the operating system on which the wagon was installed
                                 (e.g. "14.04")
     :vartype distribution_version: basestring
-    :ivar package_name: The primary Python package name used when the wagon was installed, which is
-                        one of the wheels in the wagon (e.g. "cloudify-script-plugin")
+    :ivar package_name: primary Python package name used when the wagon was installed, which is one
+                        of the wheels in the wagon (e.g. "cloudify-script-plugin")
     :vartype package_name: basestring
-    :ivar package_source: The full install string for the primary Python package name used when the
+    :ivar package_source: full install string for the primary Python package name used when the
                           wagon was installed (e.g. "cloudify-script-plugin==1.2")
     :vartype package_source: basestring
-    :ivar package_version: The version for the primary Python package name used when the wagon was
+    :ivar package_version: version for the primary Python package name used when the wagon was
                            installed (e.g. "1.2")
     :vartype package_version: basestring
-    :ivar supported_platform: If the wheels are *all* pure Python then this would be "any",
+    :ivar supported_platform: if the wheels are *all* pure Python then this would be "any",
                               otherwise it would be the installed platform name (e.g.
                               "linux_x86_64")
     :vartype supported_platform: basestring
-    :ivar supported_py_versions: The Python versions supported by all the wheels (e.g. ["py26",
+    :ivar supported_py_versions: Python versions supported by all the wheels (e.g. ["py26",
                                  "py27"])
     :vartype supported_py_versions: [basestring]
-    :ivar wheels: The filenames of the wheels archived in the wagon, often with a ".whl" extension
+    :ivar wheels: filenames of the wheels archived in the wagon, often with a ".whl" extension
     :vartype wheels: [basestring]
-    :ivar uploaded_at: Timestamp for when the wagon was installed
+    :ivar uploaded_at: timestamp for when the wagon was installed
     :vartype uploaded_at: basestring
     """
 
@@ -221,34 +221,34 @@ class TaskBase(mixins.ModelMixin):
     Tasks are often based on :class:`Operation`, and thus act on either a :class:`Node` or a
     :class:`Relationship`, however this is not required.
 
-    :ivar node: The node actor (optional)
-    :vartype node: :class:`Node`
-    :ivar relationship: The relationship actor (optional)
-    :vartype relationship: :class:`Relationship`
-    :ivar plugin: The implementing plugin (set to None for default execution plugin)
-    :vartype plugin: :class:`Plugin`
+    :ivar node: node actor (optional)
+    :vartype node: Node
+    :ivar relationship: relationship actor (optional)
+    :vartype relationship: Relationship
+    :ivar plugin: implementing plugin (set to None for default execution plugin)
+    :vartype plugin: Plugin
     :ivar function: Python path to an ``@operation`` function
     :vartype function: basestring
-    :ivar arguments: Arguments that can be used by this task
-    :vartype arguments: {basestring: :class:`Argument`}
-    :ivar max_attempts: Maximum number of retries allowed in case of failure
+    :ivar arguments: arguments that can be used by this task
+    :vartype arguments: {:obj:`basestring`: :class:`Argument`}
+    :ivar max_attempts: maximum number of retries allowed in case of failure
     :vartype max_attempts: int
-    :ivar retry_interval: Interval between retries (in seconds)
+    :ivar retry_interval: interval between retries (in seconds)
     :vartype retry_interval: int
-    :ivar ignore_failure: Set to True to ignore failures
+    :ivar ignore_failure: set to ``True`` to ignore failures
     :vartype ignore_failure: bool
-    :ivar due_at: Timestamp to start the task
+    :ivar due_at: timestamp to start the task
     :vartype due_at: datetime
-    :ivar execution: Assigned execution
-    :vartype execution: :class:`Execution`
-    :ivar status: Current atomic status ('pending', 'retrying', 'sent', 'started', 'success',
+    :ivar execution: assigned execution
+    :vartype execution: Execution
+    :ivar status: current atomic status ('pending', 'retrying', 'sent', 'started', 'success',
                   'failed')
     :vartype status: basestring
-    :ivar started_at: Timestamp for when task started
+    :ivar started_at: timestamp for when task started
     :vartype started_at: datetime
-    :ivar ended_at: Timestamp for when task ended
+    :ivar ended_at: timestamp for when task ended
     :vartype ended_at: datetime
-    :ivar attempts_count: How many attempts occurred
+    :ivar attempts_count: how many attempts occurred
     :vartype attempts_count: int
     """
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/service_common.py
----------------------------------------------------------------------
diff --git a/aria/modeling/service_common.py b/aria/modeling/service_common.py
index 59bcd02..2ba3aa3 100644
--- a/aria/modeling/service_common.py
+++ b/aria/modeling/service_common.py
@@ -37,12 +37,12 @@ from . import relationship
 
 class OutputBase(ParameterMixin):
     """
-    :ivar name: Name
+    :ivar name: name
     :vartype name: basestring
-    :ivar type_name: Type name
+    :ivar type_name: type name
     :vartype type_name: basestring
-    :ivar value: Value
-    :ivar description: Description
+    :ivar value: value
+    :ivar description: human-readable description
     :vartype description: basestring
     """
 
@@ -75,12 +75,12 @@ class OutputBase(ParameterMixin):
 
 class InputBase(ParameterMixin):
     """
-    :ivar name: Name
+    :ivar name: name
     :vartype name: basestring
-    :ivar type_name: Type name
+    :ivar type_name: type name
     :vartype type_name: basestring
-    :ivar value: Value
-    :ivar description: Description
+    :ivar value: value
+    :ivar description: human-readable description
     :vartype description: basestring
     """
 
@@ -157,12 +157,12 @@ class InputBase(ParameterMixin):
 
 class ConfigurationBase(ParameterMixin):
     """
-    :ivar name: Name
+    :ivar name: name
     :vartype name: basestring
-    :ivar type_name: Type name
+    :ivar type_name: type name
     :vartype type_name: basestring
-    :ivar value: Value
-    :ivar description: Description
+    :ivar value: value
+    :ivar description: human-readable description
     :vartype description: basestring
     """
 
@@ -195,12 +195,12 @@ class ConfigurationBase(ParameterMixin):
 
 class PropertyBase(ParameterMixin):
     """
-    :ivar name: Name
+    :ivar name: name
     :vartype name: basestring
-    :ivar type_name: Type name
+    :ivar type_name: type name
     :vartype type_name: basestring
-    :ivar value: Value
-    :ivar description: Description
+    :ivar value: value
+    :ivar description: human-readable description
     :vartype description: basestring
     """
 
@@ -255,6 +255,7 @@ class PropertyBase(ParameterMixin):
     @declared_attr
     def artifact_fk(cls):
         return relationship.foreign_key('artifact', nullable=True)
+
     # endregion
 
     # region many_to_one relationships
@@ -312,12 +313,12 @@ class PropertyBase(ParameterMixin):
 
 class AttributeBase(ParameterMixin):
     """
-    :ivar name: Name
+    :ivar name: name
     :vartype name: basestring
-    :ivar type_name: Type name
+    :ivar type_name: type name
     :vartype type_name: basestring
-    :ivar value: Value
-    :ivar description: Description
+    :ivar value: value
+    :ivar description: human-readable description
     :vartype description: basestring
     """
 
@@ -354,7 +355,7 @@ class TypeBase(InstanceModelMixin):
     """
     Represents a type and its children.
 
-    :ivar name:
+    :ivar name: name
     :vartype name: basestring
     """
 
@@ -466,9 +467,9 @@ class MetadataBase(TemplateModelMixin):
 
     This model is used by both service template and service instance elements.
 
-    :ivar name: Name
+    :ivar name: name
     :vartype name: basestring
-    :ivar value: Value
+    :ivar value: value
     :vartype value: basestring
     """
 

http://git-wip-us.apache.org/repos/asf/incubator-ariatosca/blob/7ed92d0f/aria/modeling/service_instance.py
----------------------------------------------------------------------
diff --git a/aria/modeling/service_instance.py b/aria/modeling/service_instance.py
index 78ee105..033785d 100644
--- a/aria/modeling/service_instance.py
+++ b/aria/modeling/service_instance.py
@@ -54,39 +54,39 @@ class ServiceBase(InstanceModelMixin):
     You will usually not create it programmatically, but instead instantiate it from a service
     template.
 
-    :ivar name: Name (unique for this ARIA installation)
+    :ivar name: name (unique for this ARIA installation)
     :vartype name: basestring
-    :ivar service_template: Template from which this service was instantiated (optional)
-    :vartype service_template: :class:`ServiceTemplate`
-    :ivar description: Human-readable description
-    :vartype description: string
-    :ivar meta_data: Custom annotations
-    :vartype meta_data: {basestring: :class:`Metadata`}
-    :ivar node: Nodes
-    :vartype node: {basestring: :class:`Node`}
-    :ivar groups: Groups of nodes
-    :vartype groups: {basestring: :class:`Group`}
-    :ivar policies: Policies
-    :vartype policies: {basestring: :class:`Policy`]}
-    :ivar substitution: The entire service can appear as a node
+    :ivar service_template: template from which this service was instantiated (optional)
+    :vartype service_template: ServiceTemplate
+    :ivar description: human-readable description
+    :vartype description: basestring
+    :ivar meta_data: custom annotations
+    :vartype meta_data: {:obj:`basestring`: :class:`Metadata`}
+    :ivar nodes: nodes
+    :vartype nodes: {:obj:`basestring`: :class:`Node`}
+    :ivar groups: groups of nodes
+    :vartype groups: {:obj:`basestring`: :class:`Group`}
+    :ivar policies: policies
+    :vartype policies: {:obj:`basestring`: :class:`Policy`]}
+    :ivar substitution: the entire service can appear as a node
     :vartype substitution: :class:`Substitution`
-    :ivar inputs: Externally provided parameters
-    :vartype inputs: {basestring: :class:`Input`}
-    :ivar outputs: These parameters are filled in after service installation
-    :vartype outputs: {basestring: :class:`Output`}
-    :ivar workflows: Custom workflows that can be performed on the service
-    :vartype workflows: {basestring: :class:`Operation`}
-    :ivar plugins: Plugins used by the service
-    :vartype plugins: {basestring: :class:`Plugin`}
-    :ivar created_at: Creation timestamp
+    :ivar inputs: externally provided parameters
+    :vartype inputs: {:obj:`basestring`: :class:`Input`}
+    :ivar outputs: these parameters are filled in after service installation
+    :vartype outputs: {:obj:`basestring`: :class:`Output`}
+    :ivar workflows: custom workflows that can be performed on the service
+    :vartype workflows: {:obj:`basestring`: :class:`Operation`}
+    :ivar plugins: plugins used by the service
+    :vartype plugins: {:obj:`basestring`: :class:`Plugin`}
+    :ivar created_at: creation timestamp
     :vartype created_at: :class:`datetime.datetime`
-    :ivar updated_at: Update timestamp
+    :ivar updated_at: update timestamp
     :vartype updated_at: :class:`datetime.datetime`
-    :ivar modifications: Modifications of this service
+    :ivar modifications: modifications of this service
     :vartype modifications: [:class:`ServiceModification`]
-    :ivar updates: Updates of this service
+    :ivar updates: updates of this service
     :vartype updates: [:class:`ServiceUpdate`]
-    :ivar executions: Executions on this service
+    :ivar executions: executions on this service
     :vartype executions: [:class:`Execution`]
     """
 
@@ -319,43 +319,43 @@ class NodeBase(InstanceModelMixin):
 
     Nodes may have zero or more :class:`Relationship` instances to other nodes.
 
-    :ivar name: Name (unique for this service)
+    :ivar name: name (unique for this service)
     :vartype name: basestring
-    :ivar node_template: Template from which this node was instantiated (optional)
+    :ivar node_template: template from which this node was instantiated (optional)
     :vartype node_template: :class:`NodeTemplate`
-    :ivar type: Node type
-    :vartype type: :class:`Type`
-    :ivar description: Human-readable description
-    :vartype description: string
-    :ivar properties: Associated parameters
-    :vartype properties: {basestring: :class:`Property`}
-    :ivar interfaces: Bundles of operations
-    :vartype interfaces: {basestring: :class:`Interface`}
-    :ivar artifacts: Associated files
-    :vartype artifacts: {basestring: :class:`Artifact`}
-    :ivar capabilities: Exposed capabilities
-    :vartype capabilities: {basestring: :class:`Capability`}
-    :ivar outbound_relationships: Relationships to other nodes
+    :ivar type: node type
+    :vartype type: Type
+    :ivar description: human-readable description
+    :vartype description: basestring
+    :ivar properties: associated parameters
+    :vartype properties: {:obj:`basestring`: :class:`Property`}
+    :ivar interfaces: bundles of operations
+    :vartype interfaces: {:obj:`basestring`: :class:`Interface`}
+    :ivar artifacts: associated files
+    :vartype artifacts: {:obj:`basestring`: :class:`Artifact`}
+    :ivar capabilities: exposed capabilities
+    :vartype capabilities: {:obj:`basestring`: :class:`Capability`}
+    :ivar outbound_relationships: relationships to other nodes
     :vartype outbound_relationships: [:class:`Relationship`]
-    :ivar inbound_relationships: Relationships from other nodes
+    :ivar inbound_relationships: relationships from other nodes
     :vartype inbound_relationships: [:class:`Relationship`]
-    :ivar host: Host node (can be self)
+    :ivar host: host node (can be self)
     :vartype host: :class:`Node`
-    :ivar state: The state of the node, according to to the TOSCA-defined node states
+    :ivar state: the state of the node, according to to the TOSCA-defined node states
     :vartype state: string
-    :ivar version: Used by `aria.storage.instrumentation`
+    :ivar version: used by :mod:`aria.storage.instrumentation`
     :vartype version: int
-    :ivar service: Containing service
+    :ivar service: containing service
     :vartype service: :class:`Service`
-    :ivar groups: We are a member of these groups
+    :ivar groups: we are a member of these groups
     :vartype groups: [:class:`Group`]
-    :ivar policies: Policies enacted on this node
+    :ivar policies: policies enacted on this node
     :vartype policies: [:class:`Policy`]
-    :ivar substitution_mapping: Our contribution to service substitution
+    :ivar substitution_mapping: our contribution to service substitution
     :vartype substitution_mapping: :class:`SubstitutionMapping`
-    :ivar tasks: Tasks for this node
+    :ivar tasks: tasks for this node
     :vartype tasks: [:class:`Task`]
-    :ivar hosted_tasks: Tasks on this node
+    :ivar hosted_tasks: tasks on this node
     :vartype hosted_tasks: [:class:`Task`]
     """
 
@@ -704,23 +704,23 @@ class GroupBase(InstanceModelMixin):
     """
     Usually an instance of a :class:`GroupTemplate`.
 
-    :ivar name: Name (unique for this service)
+    :ivar name: name (unique for this service)
     :vartype name: basestring
-    :ivar group_template: Template from which this group was instantiated (optional)
+    :ivar group_template: template from which this group was instantiated (optional)
     :vartype group_template: :class:`GroupTemplate`
-    :ivar type: Group type
-    :vartype type: :class:`Type`
-    :ivar description: Human-readable description
-    :vartype description: string
-    :ivar nodes: Members of this group
+    :ivar type: group type
+    :vartype type: Type
+    :ivar description: human-readable description
+    :vartype description: basestring
+    :ivar nodes: members of this group
     :vartype nodes: [:class:`Node`]
-    :ivar properties: Associated parameters
-    :vartype properties: {basestring: :class:`Property`}
-    :ivar interfaces: Bundles of operations
-    :vartype interfaces: {basestring: :class:`Interface`}
-    :ivar service: Containing service
+    :ivar properties: associated parameters
+    :vartype properties: {:obj:`basestring`: :class:`Property`}
+    :ivar interfaces: bundles of operations
+    :vartype interfaces: {:obj:`basestring`: :class:`Interface`}
+    :ivar service: containing service
     :vartype service: :class:`Service`
-    :ivar policies: Policies enacted on this group
+    :ivar policies: policies enacted on this group
     :vartype policies: [:class:`Policy`]
     """
 
@@ -832,21 +832,21 @@ class PolicyBase(InstanceModelMixin):
     """
     Usually an instance of a :class:`PolicyTemplate`.
 
-    :ivar name: Name (unique for this service)
+    :ivar name: name (unique for this service)
     :vartype name: basestring
-    :ivar policy_template: Template from which this policy was instantiated (optional)
+    :ivar policy_template: template from which this policy was instantiated (optional)
     :vartype policy_template: :class:`PolicyTemplate`
-    :ivar type: Policy type
-    :vartype type: :class:`Type`
-    :ivar description: Human-readable description
-    :vartype description: string
-    :ivar nodes: Policy will be enacted on all these nodes
+    :ivar type: policy type
+    :vartype type: Type
+    :ivar description: human-readable description
+    :vartype description: basestring
+    :ivar nodes: policy will be enacted on all these nodes
     :vartype nodes: [:class:`Node`]
-    :ivar groups: Policy will be enacted on all nodes in these groups
+    :ivar groups: policy will be enacted on all nodes in these groups
     :vartype groups: [:class:`Group`]
-    :ivar properties: Associated parameters
-    :vartype properties: {basestring: :class:`Property`}
-    :ivar service: Containing service
+    :ivar properties: associated parameters
+    :vartype properties: {:obj:`basestring`: :class:`Property`}
+    :ivar service: containing service
     :vartype service: :class:`Service`
     """
 
@@ -958,13 +958,13 @@ class SubstitutionBase(InstanceModelMixin):
 
     Usually an instance of a :class:`SubstitutionTemplate`.
 
-    :ivar substitution_template: Template from which this substitution was instantiated (optional)
+    :ivar substitution_template: template from which this substitution was instantiated (optional)
     :vartype substitution_template: :class:`SubstitutionTemplate`
-    :ivar node_type: Exposed node type
+    :ivar node_type: exposed node type
     :vartype node_type: :class:`Type`
-    :ivar mappings: Requirement and capability mappings
-    :vartype mappings: {basestring: :class:`SubstitutionTemplate`}
-    :ivar service: Containing service
+    :ivar mappings: requirement and capability mappings
+    :vartype mappings: {:obj:`basestring`: :class:`SubstitutionTemplate`}
+    :ivar service: containing service
     :vartype service: :class:`Service`
     """
 
@@ -1047,15 +1047,15 @@ class SubstitutionMappingBase(InstanceModelMixin):
 
     Usually an instance of a :class:`SubstitutionTemplate`.
 
-    :ivar name: Exposed capability or requirement name
+    :ivar name: exposed capability or requirement name
     :vartype name: basestring
-    :ivar node: Node
-    :vartype node: :class:`Node`
-    :ivar capability: Capability in the node
+    :ivar node: node
+    :vartype node: Node
+    :ivar capability: capability in the node
     :vartype capability: :class:`Capability`
-    :ivar requirement_template: Requirement template in the node template
+    :ivar requirement_template: requirement template in the node template
     :vartype requirement_template: :class:`RequirementTemplate`
-    :ivar substitution: Containing substitution
+    :ivar substitution: containing substitution
     :vartype substitution: :class:`Substitution`
     """
 
@@ -1156,29 +1156,29 @@ class RelationshipBase(InstanceModelMixin):
 
     Might be an instance of a :class:`RelationshipTemplate`.
 
-    :ivar name: Name (usually the name of the requirement at the source node template)
+    :ivar name: name (usually the name of the requirement at the source node template)
     :vartype name: basestring
-    :ivar relationship_template: Template from which this relationship was instantiated (optional)
+    :ivar relationship_template: template from which this relationship was instantiated (optional)
     :vartype relationship_template: :class:`RelationshipTemplate`
-    :ivar requirement_template: Template from which this relationship was instantiated (optional)
+    :ivar requirement_template: template from which this relationship was instantiated (optional)
     :vartype requirement_template: :class:`RequirementTemplate`
-    :ivar type: Relationship type
-    :vartype type: :class:`Type`
-    :ivar target_capability: Capability at the target node (optional)
+    :ivar type: relationship type
+    :vartype type: Type
+    :ivar target_capability: capability at the target node (optional)
     :vartype target_capability: :class:`Capability`
-    :ivar properties: Associated parameters
-    :vartype properties: {basestring: :class:`Property`}
-    :ivar interfaces: Bundles of operations
-    :vartype interfaces: {basestring: :class:`Interfaces`}
-    :ivar source_position: The position of the relationship in the outbound relationships.
+    :ivar properties: associated parameters
+    :vartype properties: {:obj:`basestring`: :class:`Property`}
+    :ivar interfaces: bundles of operations
+    :vartype interfaces: {:obj:`basestring`: :class:`Interfaces`}
+    :ivar source_position: position of the relationship in the outbound relationships.
     :vartype source_position: int
-    :ivar target_position: The position of the relationship in the inbound relationships.
+    :ivar target_position: position of the relationship in the inbound relationships.
     :vartype target_position: int
-    :ivar source_node: Source node
+    :ivar source_node: source node
     :vartype source_node: :class:`Node`
-    :ivar target_node: Target node
+    :ivar target_node: target node
     :vartype target_node: :class:`Node`
-    :ivar tasks: Tasks for this relationship
+    :ivar tasks: tasks for this relationship
     :vartype tasks: [:class:`Task`]
     """
 
@@ -1346,23 +1346,23 @@ class CapabilityBase(InstanceModelMixin):
 
     :ivar name: Name (unique for the node)
     :vartype name: basestring
-    :ivar capability_template: Template from which this capability was instantiated (optional)
+    :ivar capability_template: template from which this capability was instantiated (optional)
     :vartype capability_template: :class:`capabilityTemplate`
-    :ivar type: Capability type
-    :vartype type: :class:`Type`
-    :ivar min_occurrences: Minimum number of requirement matches required
+    :ivar type: capability type
+    :vartype type: Type
+    :ivar min_occurrences: minimum number of requirement matches required
     :vartype min_occurrences: int
-    :ivar max_occurrences: Maximum number of requirement matches allowed
+    :ivar max_occurrences: maximum number of requirement matches allowed
     :vartype min_occurrences: int
-    :ivar occurrences: Actual number of requirement matches
+    :ivar occurrences: actual number of requirement matches
     :vartype occurrences: int
-    :ivar properties: Associated parameters
-    :vartype properties: {basestring: :class:`Property`}
-    :ivar node: Containing node
-    :vartype node: :class:`Node`
-    :ivar relationship: Available when we are the target of a relationship
+    :ivar properties: associated parameters
+    :vartype properties: {:obj:`basestring`: :class:`Property`}
+    :ivar node: containing node
+    :vartype node: Node
+    :ivar relationship: available when we are the target of a relationship
     :vartype relationship: :class:`Relationship`
-    :ivar substitution_mapping: Our contribution to service substitution
+    :ivar substitution_mapping: our contribution to service substitution
     :vartype substitution_mapping: :class:`SubstitutionMapping`
     """
 
@@ -1473,23 +1473,23 @@ class InterfaceBase(InstanceModelMixin):
 
     Usually an instance of :class:`InterfaceTemplate`.
 
-    :ivar name: Name (unique for the node, group, or relationship)
+    :ivar name: name (unique for the node, group, or relationship)
     :vartype name: basestring
-    :ivar interface_template: Template from which this interface was instantiated (optional)
+    :ivar interface_template: template from which this interface was instantiated (optional)
     :vartype interface_template: :class:`InterfaceTemplate`
-    :ivar type: Interface type
-    :vartype type: :class:`Type`
-    :ivar description: Human-readable description
-    :vartype description: string
-    :ivar inputs: Inputs that can be used by all operations in the interface
-    :vartype inputs: {basestring: :class:`Input`}
-    :ivar operations: Operations
-    :vartype operations: {basestring: :class:`Operation`}
+    :ivar type: interface type
+    :vartype type: Type
+    :ivar description: human-readable description
+    :vartype description: basestring
+    :ivar inputs: inputs that can be used by all operations in the interface
+    :vartype inputs: {:obj:`basestring`: :class:`Input`}
+    :ivar operations: operations
+    :vartype operations: {:obj:`basestring`: :class:`Operation`}
     :ivar node: Containing node
-    :vartype node: :class:`Node`
-    :ivar group: Containing group
+    :vartype node: Node
+    :ivar group: containing group
     :vartype group: :class:`Group`
-    :ivar relationship: Containing relationship
+    :ivar relationship: containing relationship
     :vartype relationship: :class:`Relationship`
     """
 
@@ -1614,40 +1614,40 @@ class OperationBase(InstanceModelMixin):
 
     Might be an instance of :class:`OperationTemplate`.
 
-    :ivar name: Name (unique for the interface or service)
+    :ivar name: name (unique for the interface or service)
     :vartype name: basestring
-    :ivar operation_template: Template from which this operation was instantiated (optional)
+    :ivar operation_template: template from which this operation was instantiated (optional)
     :vartype operation_template: :class:`OperationTemplate`
-    :ivar description: Human-readable description
-    :vartype description: string
-    :ivar relationship_edge: When true specified that the operation is on the relationship's
+    :ivar description: human-readable description
+    :vartype description: basestring
+    :ivar relationship_edge: when ``True`` specifies that the operation is on the relationship's
                              target edge instead of its source (only used by relationship
                              operations)
     :vartype relationship_edge: bool
-    :ivar implementation: Implementation (interpreted by the plugin)
+    :ivar implementation: implementation (interpreted by the plugin)
     :vartype implementation: basestring
-    :ivar dependencies: Dependency strings (interpreted by the plugin)
-    :vartype dependencies: [basestring]
-    :ivar inputs: Input that can be used by this operation
-    :vartype inputs: {basestring: :class:`Input`}
-    :ivar plugin: Associated plugin
-    :vartype plugin: :class:`Plugin`
-    :ivar configurations: Configuration (interpreted by the plugin)
-    :vartype configurations: {basestring, :class:`Configuration`}
-    :ivar function: Name of the operation function
+    :ivar dependencies: dependency strings (interpreted by the plugin)
+    :vartype dependencies: [obj:`basestring`]
+    :ivar inputs: input that can be used by this operation
+    :vartype inputs: {:obj:`basestring`: :class:`Input`}
+    :ivar plugin: associated plugin
+    :vartype plugin: Plugin
+    :ivar configurations: configuration (interpreted by the plugin)
+    :vartype configurations: {obj:`basestring`: :class:`Configuration`}
+    :ivar function: name of the operation function
     :vartype function: basestring
-    :ivar arguments: Arguments to send to the operation function
-    :vartype arguments: {basestring: :class:`Argument`}
-    :ivar executor: Name of executor to run the operation with
+    :ivar arguments: arguments to send to the operation function
+    :vartype arguments: {:obj:`basestring`: :class:`Argument`}
+    :ivar executor: name of executor to run the operation with
     :vartype executor: basestring
-    :ivar max_attempts: Maximum number of attempts allowed in case of failure
+    :ivar max_attempts: maximum number of attempts allowed in case of failure
     :vartype max_attempts: int
-    :ivar retry_interval: Interval between retries (in seconds)
+    :ivar retry_interval: interval between retries (in seconds)
     :vartype retry_interval: int
-    :ivar interface: Containing interface
-    :vartype interface: :class:`Interface`
-    :ivar service: Containing service
-    :vartype service: :class:`Service`
+    :ivar interface: containing interface
+    :vartype interface: Interface
+    :ivar service: containing service
+    :vartype service: Service
     """
 
     __tablename__ = 'operation'
@@ -1833,26 +1833,26 @@ class ArtifactBase(InstanceModelMixin):
 
     Usually an instance of :class:`ArtifactTemplate`.
 
-    :ivar name: Name (unique for the node)
+    :ivar name: name (unique for the node)
     :vartype name: basestring
-    :ivar artifact_template: Template from which this artifact was instantiated (optional)
-    :vartype artifact_template: :class:`ArtifactTemplate`
-    :ivar type: Artifact type
-    :vartype type: :class:`Type`
-    :ivar description: Human-readable description
-    :vartype description: string
-    :ivar source_path: Source path (CSAR or repository)
+    :ivar artifact_template: template from which this artifact was instantiated (optional)
+    :vartype artifact_template: ArtifactTemplate
+    :ivar type: artifact type
+    :vartype type: Type
+    :ivar description: human-readable description
+    :vartype description: basestring
+    :ivar source_path: source path (CSAR or repository)
     :vartype source_path: basestring
-    :ivar target_path: Path at destination machine
+    :ivar target_path: path at destination machine
     :vartype target_path: basestring
-    :ivar repository_url: Repository URL
+    :ivar repository_url: repository URL
     :vartype repository_path: basestring
-    :ivar repository_credential: Credentials for accessing the repository
-    :vartype repository_credential: {basestring: basestring}
-    :ivar properties: Associated parameters
-    :vartype properties: {basestring: :class:`Property`}
-    :ivar node: Containing node
-    :vartype node: :class:`Node`
+    :ivar repository_credential: credentials for accessing the repository
+    :vartype repository_credential: {:obj:`basestring`: :obj:`basestring`}
+    :ivar properties: associated parameters
+    :vartype properties: {:obj:`basestring`: :class:`Property`}
+    :ivar node: containing node
+    :vartype node: Node
     """
 
     __tablename__ = 'artifact'


Mime
View raw message