Enhanced visitor interface documentation.

pekkaklarck · pekkaklarck · commit ce4d5fa302d1 · 2015-06-04T16:21:06.000+03:00
New model modifiers (robotframework#1976) are visitors so API docs related to it need to be better. Also exposed SuiteVisitor via robot.api.
diff --git a/doc/api/code_examples/select_every_xth_test.py b/doc/api/code_examples/select_every_xth_test.py
@@ -0,0 +1,20 @@
+from robot.api import SuiteVisitor
+
+
+class SelectEveryXthTest(SuiteVisitor):
+
+    def __init__(self, x, start=0):
+        self.x = int(x)
+        self.start = int(start)
+
+    def start_suite(self, suite):
+        """Modify suite's tests to contain only every Xth."""
+        suite.tests = suite.tests[self.start::self.x]
+
+    def end_suite(self, suite):
+        """Remove suites that are empty after removing tests."""
+        suite.suites = [s for s in suite.suites if s.test_count > 0]
+
+    def visit_test(self, test):
+        """Save time to avoid visiting tests and their keywords."""
+        pass
diff --git a/src/robot/api/__init__.py b/src/robot/api/__init__.py
@@ -60,6 +60,7 @@
         via the :mod:`robot` root package.
 """
 
+from robot.model import SuiteVisitor
 from robot.parsing import TestCaseFile, TestDataDirectory, ResourceFile, TestData
 from robot.reporting import ResultWriter
 from robot.result import ExecutionResult, ResultVisitor
diff --git a/src/robot/model/__init__.py b/src/robot/model/__init__.py
@@ -21,8 +21,7 @@
 functionality, such as :mod:`visitors <robot.model.visitor>`.
 
 These classes are extended both in :mod:`robot.result` and :mod:`robot.running`
-packages and used also elsewhere. There should, however, be no need to
-externally use these classes directly, and they are not part of the public API.
+packages and used also elsewhere.
 
 This package is considered stable.
 """
@@ -36,7 +35,7 @@
 from .tags import Tags, TagPattern, TagPatterns
 from .criticality import Criticality
 from .namepatterns import SuiteNamePatterns, TestNamePatterns
-from .visitor import SuiteVisitor, SkipAllVisitor
+from .visitor import SuiteVisitor
 from .totalstatistics import TotalStatisticsBuilder
 from .statistics import Statistics
 from .imports import Imports
diff --git a/src/robot/model/visitor.py b/src/robot/model/visitor.py
@@ -12,65 +12,150 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+"""Interface to ease traversing through a test suite structure.
+
+Visitors make it easy to modify test suite structures or to collect information
+from them. They work both with the :class:`executable suite <robot.running.model.TestSuite>`
+and the :class:`result suite <robot.result.testsuite.TestSuite>`, but the
+objects passed to the visitor methods are slightly different. The main
+difference is that the result objects have attributes like :attr:`status` and
+:attr:`starttime` that do not exist in the executable objects.
+
+This module contains :class:`SuiteVisitor` that implements the core logic to
+visit a test suite structure, and the :mod:`~robot.result` package contains
+:class:`~robot.result.visitor.ResultVisitor` that supports visiting the whole
+test execution result structure. Both of these visitors should be imported
+via the :mod:`robot.api` package when used by external code.
+
+Visitor algorithm
+-----------------
+
+All suite, test, keyword and message objects have a :meth:`visit` method that
+accepts a visitor instance. These methods will then call the correct visitor
+method :meth:`~SuiteVisitor.visit_suite`, :meth:`~SuiteVisitor.visit_test`,
+:meth:`~SuiteVisitor.visit_keyword` or :meth:`~SuiteVisitor.visit_message`,
+depending on the instance where the :meth:`visit` method exists.
+
+The recommended and definitely easiest way to implement a visitor is extending
+the :class:`SuiteVisitor` base class. The default implementation of its
+:meth:`visit_x` methods take care of traversing child elements of the object
+:obj:`x` recursively. A :meth:`visit_x` method first calls a corresponding
+:meth:`start_x` method (e.g. :meth:`visit_suite` calls :meth:`start_suite`),
+then calls :meth:`visit` for all child objects of the :obj:`x` object, and
+finally calls the corresponding :meth:`end_x` method. The default
+implementations of :meth:`start_x` and :meth:`end_x` do nothing.
+
+Custom visitors can stop visiting at a certain level either by overriding
+suitable :meth:`visit_x` method or by returning an explicit ``False`` from
+any :meth:`start_x` method.
+
+Examples
+--------
+
+The following example modifies the test suite structure so that it keeps only
+every Xth test. It could be used, for example, with Robot Framework's
+``--prerunmodifier`` option to modify test data before execution.
+
+.. literalinclude:: /../../doc/api/code_examples/select_every_xth_test.py
+
+For more examples it is possible to look at the source code of visitors used
+internally by Robot Framework itself. Some good examples are
+:class:`~robot.model.tagsetter.TagSetter` and
+:mod:`keyword removers <robot.result.keywordremover>`.
+"""
+
+
 class SuiteVisitor(object):
+    """Abstract class to ease traversing through the test suite structure.
+
+    See the :mod:`module level <robot.model.visitor>` documentation for more
+    information and an example.
+    """
 
     def visit_suite(self, suite):
+        """Implements traversing through the suite and its direct children.
+
+        Can be overridden to allow modifying the passed in ``suite`` without
+        calling :func:`start_suite` or :func:`end_suite` nor visiting child
+        suites, tests or keywords (setup and teardown) at all.
+        """
         if self.start_suite(suite) is not False:
             suite.keywords.visit(self)
             suite.suites.visit(self)
             suite.tests.visit(self)
             self.end_suite(suite)
 
     def start_suite(self, suite):
+        """Called when suite starts. Default implementation does nothing.
+
+        Can return explicit ``False`` to stop visiting.
+        """
         pass
 
     def end_suite(self, suite):
+        """Called when suite ends. Default implementation does nothing."""
         pass
 
     def visit_test(self, test):
+        """Implements traversing through the test and its keywords.
+
+        Can be overridden to allow modifying the passed in ``test`` without
+        calling :func:`start_test` or :func:`end_test` nor visiting keywords.
+        """
         if self.start_test(test) is not False:
             test.keywords.visit(self)
             self.end_test(test)
 
     def start_test(self, test):
+        """Called when test starts. Default implementation does nothing.
+
+        Can return explicit ``False`` to stop visiting.
+        """
         pass
 
     def end_test(self, test):
+        """Called when test ends. Default implementation does nothing."""
         pass
 
     def visit_keyword(self, kw):
+        """Implements traversing through the keyword and its child keywords.
+
+        Can be overridden to allow modifying the passed in ``kw`` without
+        calling :func:`start_keyword` or :func:`end_keyword` nor visiting
+        child keywords.
+        """
         if self.start_keyword(kw) is not False:
             kw.keywords.visit(self)
             kw.messages.visit(self)
             self.end_keyword(kw)
 
     def start_keyword(self, keyword):
+        """Called when keyword starts. Default implementation does nothing.
+
+        Can return explicit ``False`` to stop visiting.
+        """
         pass
 
     def end_keyword(self, keyword):
+        """Called when keyword ends. Default implementation does nothing."""
         pass
 
     def visit_message(self, msg):
+        """Implements visiting the message.
+
+        Can be overridden to allow modifying the passed in ``msg`` without
+        calling :func:`start_message` or :func:`end_message`.
+        """
         if self.start_message(msg) is not False:
             self.end_message(msg)
 
     def start_message(self, msg):
-        pass
-
-    def end_message(self, msg):
-        pass
-
-
-class SkipAllVisitor(SuiteVisitor):
-    """Travels suite and it's sub-suites without doing anything."""
-    def visit_suite(self, suite):
-        pass
+        """Called when message starts. Default implementation does nothing.
 
-    def visit_keyword(self, kw):
-        pass
-
-    def visit_test(self, test):
+        Can return explicit ``False`` to stop visiting.
+        """
         pass
 
-    def visit_message(self, msg):
+    def end_message(self, msg):
+        """Called when message ends. Default implementation does nothing."""
         pass
diff --git a/src/robot/result/visitor.py b/src/robot/result/visitor.py
@@ -12,37 +12,31 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-"""Visitors can be used to easily travel test suites, test cases and keywords."""
+"""Visitors can be used to easily traverse result structures.
+
+This module contains :class:`ResultVisitor` for traversing the whole
+:class:`~robot.result.executionresult.Result` object. It extends
+:class:`~robot.model.visitor.SuiteVisitor` that contains visiting logic
+for the test suite structure.
+"""
 
 from robot.model import SuiteVisitor
 
 
 class ResultVisitor(SuiteVisitor):
-    """Abstract class to conveniently travel
-    :class:`~robot.result.executionresult.Result` objects.
-
-    An implementation of visitor can be given to the visit method of result
-    object. This will cause the result object to be traversed and the visitor
-    object's ``visit_x``, ``start_x``, and ``end_x`` methods to be called for
-    each test suite, test case, and keyword, as well as for errors, statistics,
-    and other information in the result object. See methods below for a full
-    list of available visitor methods.
-
-    The start and end method are called for each element and their child
-    elements. The visitor implementation can override only those that it is
-    interested in. If any of the ``start_x`` methods returns False for
-    a certain element, its children are not visited.
-
-    If the visitor implements a ``visit_x`` method for element x, then the
-    children of that element will not be visited, unless the visitor calls them
-    explicitly. For example, if the visitor implements method :meth:`visit_test`,
-    the :meth:`start_test`, :meth:`end_test`, :meth:`visit_keyword`,
-    :meth:`start_keyword`, and :meth:`end_keyword` methods are not called for
-    tests at all.
-
-    See the package documentation for :mod:`a usage example <robot.result>`.
-    Visitors are also very widely used internally in Robot Framework. For
-    an example, see the source code of :class:`robot.model.tagsetter.TagSetter`.
+    """Abstract class to conveniently travel :class:`~robot.result.executionresult.Result` objects.
+
+    A visitor implementation can be given to the :meth:`visit` method of a
+    result object. This will cause the result object to be traversed and the
+    visitor's :meth:`visit_x`, :meth:`start_x`, and :meth:`end_x` methods to
+    be called for each suite, test, keyword and message, as well as for errors,
+    statistics, and other information in the result object. See methods below
+    for a full list of available visitor methods.
+
+    See the :mod:`result package level <robot.result>` documentation for
+    more information about handling results and a concrete visitor example.
+    For more information about the visitor algorithm see documentation in
+    :mod:`robot.model.visitor` module.
     """
     def visit_result(self, result):
         if self.start_result(result) is not False:
diff --git a/utest/api/test_exposed_api.py b/utest/api/test_exposed_api.py
@@ -2,7 +2,7 @@
 
 from os.path import abspath, join
 
-from robot import api, parsing, reporting, result, running
+from robot import api, model, parsing, reporting, result, running
 
 from robot.utils.asserts import assert_equals
 
@@ -30,6 +30,10 @@ def test_test_suite(self):
     def test_result_writer(self):
         assert_equals(api.ResultWriter, reporting.ResultWriter)
 
+    def test_visitors(self):
+        assert_equals(api.SuiteVisitor, model.SuiteVisitor)
+        assert_equals(api.ResultVisitor, result.ResultVisitor)
+
 
 class TestTestSuiteBuilder(unittest.TestCase):
     misc = join(abspath(__file__), '..', '..', '..', 'atest', 'testdata', 'misc')
