Result: introduce plugin interface and corresponding dispatcher

It's a known fact that the concept of results (as in job results) has
been abused.  Runners implemented as results prove that.  This minimal
interface is intended for Result implementations that render the
complete result at once.  This is the case for most *real* result
writer needs, such as XUnit, JSON (ported on the upcoming commits) and
even the HTML report writer (port coming soon)

Once all results are ported, the ResultProxy, our more custom and old
fashioned form of a dispatcher, can be removed.  Then, the job
attribute `result`, which is currently a ResultProxy instance with
multiple Result* classes holding a lot of duplicate information, will
be turned into a single instance.
Signed-off-by: NCleber Rosa <crosa@redhat.com>

avocado/core/dispatcher.py

@@ -88,3 +88,9 @@ class JobPrePostDispatcher(Dispatcher):
             except:
                 job.log.error('Error running method "%s" of plugin "%s": %s',
                               method_name, ext.name, sys.exc_info()[1])
+
+
+class ResultDispatcher(Dispatcher):
+
+    def __init__(self):
+        super(ResultDispatcher, self).__init__('avocado.plugins.result')

avocado/core/plugin_interfaces.py

@@ -118,3 +118,19 @@ class JobPost(Plugin):
         """
         Entry point for actually running the post job action
         """
+
+
+class Result(Plugin):
+
+    @abc.abstractmethod
+    def render(self, result, job):
+        """
+        Entry point with method that renders the result
+
+        This will usually be used to write the result to a file or directory.
+
+        :param result: the complete job result
+        :type result: :class:`avocado.core.result.Result`
+        :param job: the finished job for which a result will be written
+        :type job: :class:`avocado.core.job.Job`
+        """

avocado/plugins/run.py

@@ -25,6 +25,7 @@ from avocado.core import job
 from avocado.core import loader
 from avocado.core import multiplexer
 from avocado.core.plugin_interfaces import CLICmd
+from avocado.core.dispatcher import ResultDispatcher
 from avocado.core.settings import settings
 from avocado.utils.data_structures import time_to_seconds
 
@@ -185,4 +186,13 @@ class Run(CLICmd):
             log.error(e.message)
             sys.exit(exit_codes.AVOCADO_FAIL)
         job_instance = job.Job(args)
-        return job_instance.run()
+        job_run = job_instance.run()
+        result_dispatcher = ResultDispatcher()
+        if result_dispatcher.extensions:
+            # At this point job_instance doesn't have a single results attribute
+            # which is the end goal.  For now, we pick any of the plugin classes
+            # added to the result proxy.
+            if len(job_instance.result_proxy.output_plugins) > 0:
+                result = job_instance.result_proxy.output_plugins[0]
+                result_dispatcher.map_method('render', result, job_instance)
+        return job_run

docs/source/ResultFormats.rst

@@ -269,8 +269,16 @@ If you are looking to implement a new machine or human readable output
 format, you can refer to :mod:`avocado.core.plugins.xunit` and use it as a
 starting point.
 
-In a nutshell, you have to implement a class that inherits from
+If your result is something that is produced at once, based on the
+complete job outcome, you should create a new class that inherits from
+:class:`avocado.core.plugin_interfaces.Result`  and implements the
+:meth:`avocado.core.plugin_interfaces.Result.render` method.
+
+But, if your result implementation is something that outputs
+information live before/after each test, have to implement the
+old-style interface.  Create a class that inherits from
 :class:`avocado.core.result.Result` and implements all public methods,
-that perform actions (write to a file/stream) for each test states. You can
-take a look at :doc:`Plugins` for more information on how to write a plugin
-that will activate and execute the new result format.
+that perform actions (write to a file/stream) for each test states.
+
+You can take a look at :doc:`Plugins` for more information on how to
+write a plugin that will activate and execute the new result format.