docs: Update documentation about database output API and create command

3 files changed, 162 insertions, 8 deletions

diff --git a/doc/source/api/output.rst b/doc/source/api/output.rst
index 0e474a33..5aea51ec 100644
--- a/doc/source/api/output.rst
+++ b/doc/source/api/output.rst
@@ -23,6 +23,23 @@ iterating over all WA output directories found.
     :param path: must be the path to the top-level output directory (the one
                  containing ``__meta`` subdirectory and ``run.log``).
 
+WA output stored in a Postgres database by the ``Postgres`` output processor
+can be accessed via a :class:`RunDatabaseOutput` which can be initialized as follows:
+
+.. class:: RunDatabaseOutput(password, host='localhost', user='postgres', port='5432', dbname='wa', run_uuid=None, list_runs=False)
+
+    The main interface into Postgres database containing WA results.
+
+    :param password: The password used to authenticate with
+    :param host: The database host address. Defaults to ``'localhost'``
+    :param user: The user name used to authenticate with. Defaults to ``'postgres'``
+    :param port: The database connection port number. Defaults to ``'5432'``
+    :param dbname: The database name. Defaults to ``'wa'``
+    :param run_uuid: The ``run_uuid`` to identify the selected run
+    :param list_runs: Will connect to the database and will print out the available runs
+            with their corresponding run_uuids. Defaults to ``False``
+
+
 Example
 -------
 
@@ -39,6 +56,32 @@ called ``wa_output`` in the current working directory we can initialize a
        ...: output_directory = 'wa_output'
        ...: run_output = RunOutput(output_directory)
 
+Alternatively if the results have been stored in a Postgres database we can
+initialize a ``RunDatabaseOutput`` as follows:
+
+.. code-block:: python
+
+    In [1]: from wa import RunDatabaseOutput
+       ...:
+       ...: db_settings = {
+       ...:                host: 'localhost',
+       ...:                port: '5432',
+       ...:                dbname: 'wa'
+       ...:                user: 'postgres',
+       ...:                password: 'wa'
+       ...:                }
+       ...:
+       ...: RunDatabaseOutput(list_runs=True, **db_settings)
+    Available runs are:
+    ========= ============ ============= =================== =================== ====================================
+     Run Name      Project Project Stage          Start Time            End Time                             run_uuid
+    ========= ============ ============= =================== =================== ====================================
+    Test Run    my_project          None 2018-11-29 14:53:08 2018-11-29 14:53:24 aa3077eb-241a-41d3-9610-245fd4e552a9
+    run_1       my_project          None 2018-11-29 14:53:34 2018-11-29 14:53:37 4c2885c9-2f4a-49a1-bbc5-b010f8d6b12a
+    ========= ============ ============= =================== =================== ====================================
+
+    In [2]: run_uuid = '4c2885c9-2f4a-49a1-bbc5-b010f8d6b12a'
+       ...: run_output = RunDatabaseOutput(run_uuid=run_uuid, **db_settings)
 
 
 From here we can retrieve various information about the run. For example if we
@@ -65,7 +108,7 @@ parameters and the metrics recorded from the first job was we can do the followi
     Out[5]: u'dhrystone'
 
     # Print out all the runtime parameters and their values for this job
-    In [6]: for k, v in job_1.spec.runtime_parameters.iteritems():
+    In [6]: for k, v in job_1.spec.runtime_parameters.items():
        ...:     print (k, v)
     (u'airplane_mode': False)
     (u'brightness': 100)
@@ -92,6 +135,15 @@ parameters and the metrics recorded from the first job was we can do the followi
      <total DMIPS: 52793 (+)>,
      <total score: 92758402 (+)>]
 
+    # Load the run results csv file into pandas
+    In [7]: pd.read_csv(run_output.get_artifact_path('run_result_csv'))
+    Out[7]:
+                id   workload  iteration          metric          value    units
+    0   450000-wk1  dhrystone          1  thread 0 score   1.442310e+07      NaN
+    1   450000-wk1  dhrystone          1  thread 0 DMIPS   8.209700e+04      NaN
+    2   450000-wk1  dhrystone          1  thread 1 score   1.442310e+07      NaN
+    3   450000-wk1  dhrystone          1  thread 1 DMIPS   8.720900e+04      NaN
+    ...
 
 
 We can also retrieve information about the target that the run was performed on
@@ -214,7 +266,7 @@ methods
    Return the :class:`Metric` associated with the run (not the individual jobs)
    with the specified `name`.
 
-   :return: The :class`Metric` object for the metric with the specified name.
+   :return: The :class:`Metric` object for the metric with the specified name.
 
 
 .. method:: RunOutput.get_job_spec(spec_id)
@@ -232,6 +284,46 @@ methods
     :return: A list of `str` labels of workloads that were part of this run.
 
 
+:class:`RunDatabaseOutput`
+---------------------------
+
+:class:`RunDatabaseOutput` provides access to the output of a WA :term:`run`,
+including metrics,artifacts, metadata, and configuration stored in a postgres database.
+The majority of attributes and methods are the same :class:`RunOutput` however the
+noticeable differences are:
+
+``jobs``
+    A list of :class:`JobDatabaseOutput` objects for each job that was executed
+    during the run.
+
+``basepath``
+  A representation of the current database and host information backing this object.
+
+methods
+~~~~~~~
+
+.. method:: RunDatabaseOutput.get_artifact(name)
+
+    Return the :class:`Artifact` specified by ``name``. This will only look
+    at the run artifacts; this will not search the artifacts of the individual
+    jobs. The `path` attribute of the :class:`Artifact` will be set to the Database OID of the object.
+
+    :param name:  The name of the artifact who's path to retrieve.
+    :return: The :class:`Artifact` with that name
+    :raises HostError: If the artifact with the specified name does not exist.
+
+
+.. method:: RunDatabaseOutput.get_artifact_path(name)
+
+    Returns a `StringIO` object containing the contents of the artifact
+    specified by ``name``. This will only look at the run artifacts; this will
+    not search the artifacts of the individual jobs.
+
+    :param name:  The name of the artifact who's path to retrieve.
+    :return: A `StringIO` object with the contents of the artifact
+    :raises HostError: If the artifact with the specified name does not exist.
+
+
 :class:`JobOutput`
 ------------------
 
@@ -311,11 +403,10 @@ methods
 
     Return the :class:`Artifact` specified by ``name`` associated with this job.
 
-    :param name:  The name of the artifact who's path to retrieve.
+    :param name:  The name of the artifact to retrieve.
     :return: The :class:`Artifact` with that name
     :raises HostError: If the artifact with the specified name does not exist.
 
-
 .. method:: RunOutput.get_artifact_path(name)
 
     Return the path to the file backing the artifact specified by ``name``,
@@ -325,13 +416,48 @@ methods
     :return: The path to the artifact
     :raises HostError: If the artifact with the specified name does not exist.
 
-
 .. method:: RunOutput.get_metric(name)
 
    Return the :class:`Metric` associated with this job with the specified
    `name`.
 
-   :return: The :class`Metric` object for the metric with the specified name.
+   :return: The :class:`Metric` object for the metric with the specified name.
+
+
+:class:`JobDatabaseOutput`
+---------------------------
+
+:class:`JobOutput` provides access to the output of a single :term:`job`
+executed during a WA :term:`run`, including metrics, artifacts, metadata, and
+configuration stored in a postgres database.
+The majority of attributes and methods are the same :class:`JobOutput` however the
+noticeable differences are:
+
+``basepath``
+  A representation of the current database and host information backing this object.
+
+
+methods
+~~~~~~~
+
+.. method:: JobDatabaseOutput.get_artifact(name)
+
+    Return the :class:`Artifact` specified by ``name`` associated with this job.
+    The `path` attribute of the :class:`Artifact` will be set to the Database
+    OID of the object.
+
+    :param name:  The name of the artifact to retrieve.
+    :return: The :class:`Artifact` with that name
+    :raises HostError: If the artifact with the specified name does not exist.
+
+.. method:: JobDatabaseOutput.get_artifact_path(name)
+
+    Returns a ``StringIO`` object containing the contents of the artifact
+    specified by ``name`` associated with this job.
+
+    :param name:  The name of the artifact who's path to retrieve.
+    :return: A `StringIO` object with the contents of the artifact
+    :raises HostError: If the artifact with the specified name does not exist.
 
 
 :class:`Metric`
@@ -420,7 +546,7 @@ An :class:`Artifact` has  the following attributes:
             it is the opposite of ``export``, but in general may also be
             discarded.
 
-            .. note:: whether a file is marked as ``log``/``data`` or ``raw``
+            .. note:: Whether a file is marked as ``log``/``data`` or ``raw``
                     depends on how important it is to preserve this file,
                     e.g. when archiving, vs how much space it takes up.
                     Unlike ``export`` artifacts which are (almost) always
diff --git a/doc/source/developer_information/how_tos/processing_output.rst b/doc/source/developer_information/how_tos/processing_output.rst
index 16d31a47..18b6ca3e 100644
--- a/doc/source/developer_information/how_tos/processing_output.rst
+++ b/doc/source/developer_information/how_tos/processing_output.rst
@@ -26,7 +26,8 @@ CPU frequency fixed to max, and once with CPU frequency fixed to min.
 Classifiers are used to indicate the configuration in the output.
 
 First, create the :class:`RunOutput` object, which is the main interface for
-interacting with WA outputs.
+interacting with WA outputs. Or alternatively a :class:`RunDatabaseOutput`
+if storing your results in a postgres database.
 
 .. code-block:: python
 
diff --git a/doc/source/user_information/user_reference/invocation.rst b/doc/source/user_information/user_reference/invocation.rst
index 18e44a57..ead05042 100644
--- a/doc/source/user_information/user_reference/invocation.rst
+++ b/doc/source/user_information/user_reference/invocation.rst
@@ -238,6 +238,33 @@ Which will produce something like::
 This will be populated with default values which can then be customised for the
 particular use case.
 
+Additionally the create command can be used to initialize (and update) a
+Postgres database which can be used by the ``postgres`` output processor.
+
+The most of database connection parameters have a default value however they can
+be overridden via command line arguments. When initializing the database WA will
+also save the supplied parameters into the default user config file so that they
+do not need to be specified time the output processor is used.
+
+As an example if we had a database server running on at 10.0.0.2 using the
+standard port we could use the following command to initialize a database for
+use with WA::
+
+        wa create database -a 10.0.0.2 -u my_username -p Pa55w0rd
+
+This will log into the database server with the supplied credentials and create
+a database (defaulting to 'wa') and will save the configuration to the
+``~/.workload_automation/config.yaml`` file.
+
+With updates to WA there may be changes to the database schema used. In this
+case the create command can also be used with the ``-U`` flag to update the
+database to use the new schema as follows::
+
+        wa create database -a 10.0.0.2 -u my_username -p Pa55w0rd -U
+
+This will upgrade the database sequentially until the database schema is using
+the latest version.
+
 .. _process-command:
 
 Process