Expose robot.running.model classes via robot.running.

robot.result.model classes were already exposed via robot.result.

Also enhance related documentation.

Relatd to type hints in visitor API (#4569) and listener API (#4568).

src/robot/result/__init__.py

@@ -18,19 +18,15 @@
 The main public API of this package consists of the :func:`~.ExecutionResult`
 factory method, that returns :class:`~.Result` objects, and of the
 :class:`~.ResultVisitor` abstract class, that eases further processing
-the results.
+the results. It is recommended to import these public entry-points via the
+:mod:`robot.api` package like in the example below.
 
-The model objects in the :mod:`robot.result.model` module can also be considered
-to be part of the public API, because they can be found inside the :class:`~.Result`
-object. They can also be inspected and modified as part of the normal test
-execution by `pre-Rebot modifiers`__ and `listeners`__.
-
-It is highly recommended to import the public entry-points via the
-:mod:`robot.api` package like in the example below. In those rare cases
-where the aforementioned model objects are needed directly, they can be
-imported from this package.
-
-This package is considered stable.
+The model objects defined in the :mod:`robot.result.model` module are also
+part of the public API. They are used inside the :class:`~.Result` object,
+and they can also be inspected and modified as part of the normal test
+execution by using `pre-Rebot modifiers`__ and `listeners`__. These model
+objects are not exposed via :mod:`robot.api`, but they can be imported
+from :mod:`robot.result` if needed.
 
 Example
 -------
@@ -42,7 +38,7 @@
 """
 
 from .executionresult import Result
-from .model import (For, ForIteration, While, WhileIteration, If, IfBranch, Keyword,
-                    Message, TestCase, TestSuite, Try, TryBranch, Return, Continue, Break)
+from .model import (Break, Continue, For, ForIteration, If, IfBranch, Keyword, Message,
+                    Return, TestCase, TestSuite, Try, TryBranch, While, WhileIteration)
 from .resultbuilder import ExecutionResult, ExecutionResultBuilder
 from .visitor import ResultVisitor

src/robot/result/model.py

@@ -28,8 +28,7 @@
 modify these objects using the :mod:`visitor interface <robot.model.visitor>`.
 
 If classes defined here are needed, for example, as type hints, they can
-be imported directly from this :mod:`robot.running.model` module. This
-module is considered stable.
+be imported via the :mod:`robot.running` module.
 
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#listener-interface
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#programmatic-modification-of-results

src/robot/running/__init__.py

@@ -15,23 +15,28 @@
 
 """Implements the core test execution logic.
 
-The main public entry points of this package are of the following:
+The public API of this module consists of the following objects:
 
 * :class:`~robot.running.model.TestSuite` for creating an executable
   test suite structure programmatically.
 
+* :class:`~robot.running.builder.builders.TestSuiteBuilder` for creating
+  executable test suites based on data on a file system.
+  Instead of using this class directly, it is possible to use the
+  :meth:`TestSuite.from_file_system <robot.running.model.TestSuite.from_file_system>`
+  classmethod that uses it internally.
+
 * Classes used by :class:`~robot.running.model.TestSuite`, such as
   :class:`~robot.running.model.TestCase` and :class:`~robot.running.model.Keyword`,
   that are defined in the :mod:`robot.running.model` module.
 
-* :class:`~robot.running.builder.builders.TestSuiteBuilder` for creating
-  executable test suites based on existing test case files and directories. The
-  :meth:`TestSuite.from_file_system <robot.running.model.TestSuite.from_file_system>`
-  classmethod can be used for that purpose as well.
+:class:`~robot.running.model.TestSuite` and
+:class:`~robot.running.builder.builders.TestSuiteBuilder` can be imported via
+the :mod:`robot.api` package. If other classes are needed directly, they can be
+imported via :mod:`robot.running`.
 
-The classes mentioned above can be imported via the :mod:`robot.api` package
-as the examples below demonstrate. If other model objects are needed, they
-can be imported from the :mod:`robot.running.model` module.
+.. note:: Prior to Robot Framework 6.1, only some classes in
+          :mod:`robot.running.model` were exposed via :mod:`robot.running`.
 
 Examples
 --------
@@ -48,15 +53,13 @@
         [Setup]    Set Environment Variable    SKYNET    activated
         Environment Variable Should Be Set    SKYNET
 
-We can easily parse and create an executable test suite based on the above file
-using the :class:`~robot.running.builder.TestSuiteBuilder` class as follows::
+We can easily create an executable test suite based on the above file::
 
-    from robot.api import TestSuiteBuilder
+    from robot.api import TestSuite
 
-    suite = TestSuiteBuilder().build('path/to/activate_skynet.robot')
+    suite = TestSuite.from_file_system('path/to/activate_skynet.robot')
 
-That was easy. Let's next generate the same test suite from scratch
-using the :class:`~robot.running.model.TestSuite` class::
+That was easy. Let's next generate the same test suite from scratch::
 
     from robot.api import TestSuite
 
@@ -99,10 +102,11 @@
 """
 
 from .arguments import ArgInfo, ArgumentSpec, TypeConverter
-from .builder import TestSuiteBuilder, ResourceFileBuilder
+from .builder import ResourceFileBuilder, TestSuiteBuilder
 from .context import EXECUTION_CONTEXTS
-from .model import Keyword, TestCase, TestSuite
+from .model import (Break, Continue, For, If, IfBranch, Keyword, Return, TestCase,
+                    TestSuite, Try, TryBranch, While)
+from .runkwregister import RUN_KW_REGISTER
 from .testlibraries import TestLibrary
 from .usererrorhandler import UserErrorHandler
 from .userkeyword import UserLibrary
-from .runkwregister import RUN_KW_REGISTER

src/robot/running/model.py

@@ -15,20 +15,20 @@
 
 """Module implementing test execution related model objects.
 
-When tests are executed normally, these objects are created based on the test
-data on the file system by :class:`~robot.running.builder.builders.TestSuiteBuilder`,
-but external tools can also create an executable test suite model structure directly.
-Regardless the approach to create it, the model is executed by calling
-:meth:`~TestSuite.run` method of the root test suite. See the
-:mod:`robot.running` package level documentation for more information and
-examples.
-
-The most important classes defined in this module are :class:`TestSuite`,
-:class:`TestCase` and :class:`Keyword`. When tests are executed, these objects
-can be inspected and modified by `pre-run modifiers`__ and `listeners`__.
-These three classes are exposed via the :mod:`robot.api` package. If other
-classes are needed, they can be imported directly from this
-:mod:`robot.running.model` module. This module is considered stable.
+When tests are executed by Robot Framework, a :class:`TestSuite` structure using
+classes defined in this module is created by
+:class:`~robot.running.builder.builders.TestSuiteBuilder`
+based on data on a file system. In addition to that, external tools can
+create executable suite structures programmatically.
+
+Regardless the approach to construct it, a :class:`TestSuite` object is executed
+by calling its :meth:`~TestSuite.run` method as shown in the example in
+the :mod:`robot.running` package level documentation. When a suite is run,
+test, keywords, and other objects it contains can be inspected and modified
+by using `pre-run modifiers`__ and `listeners`__.
+
+The :class:`TestSuite` class is exposed via the :mod:`robot.api` package. If other
+classes are needed, they can be imported from :mod:`robot.running`.
 
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#programmatic-modification-of-results
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#listener-interface