Expose stable parsing API (robotframework#3373).

pekkaklarck · pekkaklarck · commit c13f0148915c · 2020-01-11T22:07:45.000+02:00
Documentation still mostly missing but robotframework#3293 covers that.
diff --git a/src/robot/api/__init__.py b/src/robot/api/__init__.py
@@ -45,7 +45,7 @@
 * :func:`~robot.result.resultbuilder.ExecutionResult` factory method
   for reading execution results from XML output files and
   :class:`~robot.result.visitor.ResultVisitor` abstract class to ease
-  further processing the results. 
+  further processing the results.
   :class:`~robot.result.visitor.ResultVisitor` can also be used as a base
   for pre-Rebot modifier that is taken into use with ``--prerebotmodifier``
   commandline option.
@@ -68,6 +68,10 @@
 """
 
 from robot.model import SuiteVisitor
+# FIXME: Anything else to expose from parsing? Update parsing docs above.
+from robot.parsing import (get_model, get_resource_model,
+                           get_tokens, get_resource_tokens,
+                           ModelTransformer, ModelVisitor)
 from robot.reporting import ResultWriter
 from robot.result import ExecutionResult, ResultVisitor
 from robot.running import TestSuite, TestSuiteBuilder
diff --git a/src/robot/parsing/__init__.py b/src/robot/parsing/__init__.py
@@ -13,43 +13,37 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-# FIXME misleading maybe??
 """Implements test data parsing.
 
-Classes :class:`~.model.TestCaseFile`, :class:`~.model.TestDataDirectory`
-and :class:`~.model.ResourceFile` represented parsed test data. Objects
-of these classes can be modified and saved back to disk. In addition,
-a convenience factory function :func:`~.model.TestData` can be used to
-parse a test case file or directory to a corresponding object.
+Main entry points to parsing are the following:
 
-Aforementioned classes and functions are part of the public API. It is
-recommended that they are imported through the :mod:`robot.api` package
-like in the example below.
+* :func:`~.lexer.get_tokens` and :func:`~.lexer.get_resource_tokens`
+  for parsing test data to tokens.
 
-This package is likely to change radically in Robot Framework 2.9. The main
-motivation for the planned changes is making the data easier to use for
-external tools that use these modules.
+* :func:`~.builders.get_model` and :func:`~.builders.get_resource_model` for
+  parsing test data into a model represented as an abstract syntax tree (AST).
+
+*TODO:* Document how to modify the returned model using
+:class:`~.model.ModelVisitor` and :class:`~.model.ModelTransformer`.
+Also mention that the model as well as tokens are part of the public API.
+
+Like with rest of the public API, these functions and classes are exposed
+also via :module:`robot.api`.
+
+The :module:`robot.parsing` package has been totally rewritten in Robot
+Framework 3.2 and all code using it needs to be updated. Depending on the
+use case, it may be possible to use the :func:`robot.running.TestSuiteBuilder`
+that has not changed instead.
 
 Example
 -------
 
 ::
 
-    import sys
-    from robot.api import TestData
-
-    def print_suite(suite):
-        print 'Suite:', suite.name
-        for test in suite.testcase_table:
-            print '-', test.name
-        for child in suite.children:
-            print_suite(child)
-
-    suite = TestData(source=sys.argv[1])
-    print_suite(suite)
+    TODO
 """
 
 from .builders import get_model, get_resource_model
 from .lexer import get_tokens, get_resource_tokens, Token
-from .model import ModelTransformer
+from .model import ModelTransformer, ModelVisitor
 from .suitestructure import SuiteStructureBuilder, SuiteStructureVisitor
diff --git a/src/robot/parsing/model/__init__.py b/src/robot/parsing/model/__init__.py
@@ -16,4 +16,4 @@
 from .blocks import (File, SettingSection, VariableSection, TestCaseSection,
                      KeywordSection, CommentSection, TestCase, Keyword, ForLoop)
 from .statements import get_statements
-from .visitor import ModelTransformer
+from .visitor import ModelTransformer, ModelVisitor
