robotframework 6.1rc1__zip → 7.0__zip

{robotframework-6.1rc1 → robotframework-7.0}/src/robot/api/interfaces.py

@@ -34,9 +34,6 @@ base class.
 .. note:: These classes are not exposed via the top level :mod:`robot.api`
           package and need to imported via :mod:`robot.api.interfaces`.
 
-.. note:: Using this module requires having the typing_extensions__ module
-          installed when using Python 3.6 or 3.7.
-
 This module is new in Robot Framework 6.1.
 
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#dynamic-library-api
@@ -44,22 +41,12 @@ __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#listener-version-2
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#listener-version-3
 __ http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#parser-interface
-__ https://pypi.org/project/typing-extensions/
 """
 
 import sys
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
-# Need to use version check and not try/except to support Mypy's stubgen.
-if sys.version_info >= (3, 8):
-    from typing import TypedDict
-else:
-    try:
-        from typing_extensions import TypedDict
-    except ImportError:
-        raise ImportError("Using the 'robot.api.interfaces' module requires having "
-                          "the 'typing_extensions' module installed with Python < 3.8.")
+from typing import Any, Mapping, Sequence, TypedDict, Union
 if sys.version_info >= (3, 10):
     from types import UnionType
 else:
@@ -72,32 +59,32 @@ from robot.running import TestDefaults, TestSuite
 
 # Type aliases used by DynamicLibrary and HybridLibrary.
 Name = str
-PositArgs = List[Any]
-NamedArgs = Dict[str, Any]
+PositArgs = Sequence[Any]
+NamedArgs = Mapping[str, Any]
 Documentation = str
-Arguments = List[
+Arguments = Sequence[
     Union[
-        str,               # Name with possible default like `arg` or `arg=1`.
-        Tuple[str],        # Name without a default like `('arg',)`.
-        Tuple[str, Any]    # Name and default like `('arg', 1)`.
+        str,                   # Name with possible default like `arg` or `arg=1`.
+        'tuple[str]',          # Name without a default like `('arg',)`.
+        'tuple[str, Any]'      # Name and default like `('arg', 1)`.
     ]
 ]
-Type = Union[
-    type,                           # Actual type.
-    str,                            # Type name or alias.
-    UnionType,                      # Union syntax (e.g. `int | float`).
-    Tuple[Union[type, str], ...]    # Tuple of types. Behaves like union.
+TypeHint = Union[
+    type,                      # Actual type.
+    str,                       # Type name or alias.
+    UnionType,                 # Union syntax (e.g. `int | float`).
+    'tuple[TypeHint, ...]'     # Tuple of type hints. Behaves like a union.
 ]
-Types = Union[
-    Dict[str, Type],       # Types by name.
-    List[                  # Types by position.
+TypeHints = Union[
+    Mapping[str, TypeHint],    # Types by name.
+    Sequence[                  # Types by position.
         Union[
-            Type,          # Type info.
-            None           # No type info.
+            TypeHint,          # Type hint.
+            None               # No type hint.
         ]
     ]
 ]
-Tags = List[str]
+Tags = Sequence[str]
 Source = str
 
 
@@ -112,7 +99,7 @@ class DynamicLibrary(ABC):
     """
 
     @abstractmethod
-    def get_keyword_names(self) -> List[Name]:
+    def get_keyword_names(self) -> Sequence[Name]:
         """Return names of the keywords this library implements.
 
         :return: Keyword names as a list of strings.
@@ -137,7 +124,7 @@ class DynamicLibrary(ABC):
         """
         raise NotImplementedError
 
-    def get_keyword_documentation(self, name: Name) -> Optional[Documentation]:
+    def get_keyword_documentation(self, name: Name) -> 'Documentation | None':
         """Optional method to return keyword documentation.
 
         The first logical line of keyword documentation is shown in
@@ -155,7 +142,7 @@ class DynamicLibrary(ABC):
         """
         return None
 
-    def get_keyword_arguments(self, name: Name) -> Optional[Arguments]:
+    def get_keyword_arguments(self, name: Name) -> 'Arguments | None':
         """Optional method to return keyword's argument specification.
 
         Returned information is used during execution for argument validation.
@@ -179,7 +166,7 @@ class DynamicLibrary(ABC):
         - If keyword does not accept varargs, a lone ``*`` can be used
           a separator between normal and named-only arguments like
           ``['normal', '*', 'named']``.
-        - Kwargs must have a ``**``  prefix like [``**config``]. There can
+        - Kwargs must have a ``**``  prefix like ``['**config']``. There can
           be only one kwargs, and it must be last.
 
         Both normal arguments and named-only arguments can have default values:
@@ -198,7 +185,7 @@ class DynamicLibrary(ABC):
         """
         return None
 
-    def get_keyword_types(self, name: Name) -> Optional[Types]:
+    def get_keyword_types(self, name: Name) -> 'TypeHints | None':
         """Optional method to return keyword's type specification.
 
         Type information is used for automatic argument conversion during
@@ -231,7 +218,7 @@ class DynamicLibrary(ABC):
         """
         return None
 
-    def get_keyword_tags(self, name: Name) -> Optional[Tags]:
+    def get_keyword_tags(self, name: Name) -> 'Tags | None':
         """Optional method to return keyword's tags.
 
         Tags are shown in the execution log and in documentation generated by
@@ -242,7 +229,7 @@ class DynamicLibrary(ABC):
         """
         return None
 
-    def get_keyword_source(self, name: Name) -> Optional[Source]:
+    def get_keyword_source(self, name: Name) -> 'Source | None':
         """Optional method to return keyword's source path and line number.
 
         Source information is used by IDEs to provide navigation from
@@ -281,7 +268,7 @@ class HybridLibrary(ABC):
     """
 
     @abstractmethod
-    def get_keyword_names(self) -> List[Name]:
+    def get_keyword_names(self) -> Sequence[Name]:
         """Return names of the implemented keyword methods as a list or strings.
 
         Returned names must match names of the implemented keyword methods.
@@ -299,10 +286,10 @@ class StartSuiteAttributes(TypedDict):
     id: str
     longname: str
     doc: str
-    metadata: dict
+    metadata: 'dict[str, str]'
     source: str
-    suites: List[str]
-    tests: List[str]
+    suites: 'list[str]'
+    tests: 'list[str]'
     totaltests: int
     starttime: str
 
@@ -328,7 +315,7 @@ class StartTestAttributes(TypedDict):
     longname: str
     originalname: str
     doc: str
-    tags: List[str]
+    tags: 'list[str]'
     template: str
     source: str
     lineno: int
@@ -352,22 +339,18 @@ class OptionalKeywordAttributes(TypedDict, total=False):
     These attributes are included with control structures. For example, with
     IF structures attributes include ``condition``.
     """
-    # FOR
-    variables: List[str]
+    # FOR / ITERATION with FOR
+    variables: 'list[str] | dict[str, str]'
     flavor: str
-    values: List[str]
-    # ITERATION with FOR
-    variables: Dict[str, str]
+    values: 'list[str]'    # Also RETURN
     # WHILE and IF
     condition: str
     # WHILE
     limit: str
     # EXCEPT
-    patterns: List[str]
+    patterns: 'list[str]'
     pattern_type: str
     variable: str
-    # RETURN
-    values: List[str]
 
 
 class StartKeywordAttributes(OptionalKeywordAttributes):
@@ -379,9 +362,9 @@ class StartKeywordAttributes(OptionalKeywordAttributes):
     kwname: str
     libname: str
     doc: str
-    args: List[str]
-    assign: List[str]
-    tags: List[str]
+    args: 'list[str]'
+    assign: 'list[str]'
+    tags: 'list[str]'
     source: str
     lineno: int
     status: str
@@ -413,10 +396,10 @@ class LibraryAttributes(TypedDict):
 
     See the User Guide for more information.
     """
-    args: List[str]
+    args: 'list[str]'
     originalname: str
     source: str
-    importer: Union[str, None]
+    importer: 'str | None'
 
 
 class ResourceAttributes(TypedDict):
@@ -425,7 +408,7 @@ class ResourceAttributes(TypedDict):
     See the User Guide for more information.
     """
     source: str
-    importer: Union[str, None]
+    importer: 'str | None'
 
 
 class VariablesAttributes(TypedDict):
@@ -433,13 +416,13 @@ class VariablesAttributes(TypedDict):
 
     See the User Guide for more information.
     """
-    args: List[str]
+    args: 'list[str]'
     source: str
-    importer: Union[str, None]
+    importer: 'str | None'
 
 
 class ListenerV2:
-    """Optional base class for listeners using the listener API v2."""
+    """Optional base class for listeners using the listener API version 2."""
     ROBOT_LISTENER_API_VERSION = 2
 
     def start_suite(self, name: str, attributes: StartSuiteAttributes):
@@ -518,7 +501,7 @@ class ListenerV2:
 
 
 class ListenerV3:
-    """Optional base class for listeners using the listener API v3."""
+    """Optional base class for listeners using the listener API version 3."""
     ROBOT_LISTENER_API_VERSION = 3
 
     def start_suite(self, data: running.TestSuite, result: result.TestSuite):
@@ -531,7 +514,359 @@ class ListenerV3:
         """Called when a test or task starts."""
 
     def end_test(self, data: running.TestCase, result: result.TestCase):
-        """Called when a test or ends starts."""
+        """Called when a test or tasks ends."""
+
+    def start_keyword(self, data: running.Keyword, result: result.Keyword):
+        """Called when a keyword starts by default.
+
+        This method is called, by default, with user keywords, library keywords
+        and when a keyword call is invalid. It is not called, however, if a more
+        specific :meth:`start_user_keyword`, :meth:`start_library_keyword` or
+        :meth:`start_invalid_keyword` method is implemented.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_keyword(self, data: running.Keyword, result: result.Keyword):
+        """Called when a keyword ends by default.
+
+        This method is called, by default, with user keywords, library keywords
+        and when a keyword call is invalid. It is not called, however, if a more
+        specific :meth:`end_user_keyword`, :meth:`end_library_keyword` or
+        :meth:`end_invalid_keyword` method is implemented.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_user_keyword(self, data: running.Keyword,
+                           implementation: running.UserKeyword,
+                           result: result.Keyword):
+        """Called when a user keyword starts.
+
+        The default implementation calls :meth:`start_keyword`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_keyword(data, result)
+
+    def end_user_keyword(self, data: running.Keyword,
+                         implementation: running.UserKeyword,
+                         result: result.Keyword):
+        """Called when a user keyword ends.
+
+        The default implementation calls :meth:`end_keyword`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_keyword(data, result)
+
+    def start_library_keyword(self, data: running.Keyword,
+                              implementation: running.LibraryKeyword,
+                              result: result.Keyword):
+        """Called when a library keyword starts.
+
+        The default implementation calls :meth:`start_keyword`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_keyword(data, result)
+
+    def end_library_keyword(self, data: running.Keyword,
+                            implementation: running.LibraryKeyword,
+                            result: result.Keyword):
+        """Called when a library keyword ends.
+
+        The default implementation calls :meth:`start_keyword`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_keyword(data, result)
+
+    def start_invalid_keyword(self, data: running.Keyword,
+                              implementation: running.KeywordImplementation,
+                              result: result.Keyword):
+        """Called when an invalid keyword call starts.
+
+        Keyword may not have been found, there could have been multiple matches,
+        or the keyword call itself could have been invalid.
+
+        The default implementation calls :meth:`start_keyword`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_keyword(data, result)
+
+    def end_invalid_keyword(self, data: running.Keyword,
+                            implementation: running.KeywordImplementation,
+                            result: result.Keyword):
+        """Called when an invalid keyword call ends.
+
+        Keyword may not have been found, there could have been multiple matches,
+        or the keyword call itself could have been invalid.
+
+        The default implementation calls :meth:`end_keyword`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_keyword(data, result)
+
+    def start_for(self, data: running.For, result: result.For):
+        """Called when a FOR loop starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_for(self, data: running.For, result: result.For):
+        """Called when a FOR loop ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_for_iteration(self, data: running.ForIteration,
+                            result: result.ForIteration):
+        """Called when a FOR loop iteration starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_for_iteration(self, data: running.ForIteration,
+                          result: result.ForIteration):
+        """Called when a FOR loop iteration ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_while(self, data: running.While, result: result.While):
+        """Called when a WHILE loop starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_while(self, data: running.While, result: result.While):
+        """Called when a WHILE loop ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_while_iteration(self, data: running.WhileIteration,
+                              result: result.WhileIteration):
+        """Called when a WHILE loop iteration starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_while_iteration(self, data: running.WhileIteration,
+                            result: result.WhileIteration):
+        """Called when a WHILE loop iteration ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_if(self, data: running.If, result: result.If):
+        """Called when an IF/ELSE structure starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_if(self, data: running.If, result: result.If):
+        """Called when an IF/ELSE structure ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_if_branch(self, data: running.IfBranch, result: result.IfBranch):
+        """Called when an individual IF/ELSE branch starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_if_branch(self, data: running.IfBranch, result: result.IfBranch):
+        """Called when an individual IF/ELSE branch ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_try(self, data: running.Try, result: result.Try):
+        """Called when a TRY/EXCEPT structure starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_try(self, data: running.Try, result: result.Try):
+        """Called when a TRY/EXCEPT structure ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_try_branch(self, data: running.TryBranch, result: result.TryBranch):
+        """Called when an individual TRY/EXCEPT branch starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_try_branch(self, data: running.TryBranch, result: result.TryBranch):
+        """Called when an individual TRY/EXCEPT branch ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_var(self, data: running.Var, result: result.Var):
+        """Called when VAR starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_var(self, data: running.Var, result: result.Var):
+        """Called when VAR ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_break(self, data: running.Break, result: result.Break):
+        """Called when BREAK starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_break(self, data: running.Break, result: result.Break):
+        """Called when BREAK ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_continue(self, data: running.Continue, result: result.Continue):
+        """Called when CONTINUE starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_continue(self, data: running.Continue, result: result.Continue):
+        """Called when CONTINUE ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_return(self, data: running.Return, result: result.Return):
+        """Called when RETURN starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_return(self, data: running.Return, result: result.Return):
+        """Called when RETURN ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_error(self, data: running.Error, result: result.Error):
+        """Called when encountered invalid syntax starts.
+
+        The default implementation calls :meth:`start_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.start_body_item(data, result)
+
+    def end_error(self, data: running.Error, result: result.Error):
+        """Called when encountered invalid syntax ends.
+
+        The default implementation calls :meth:`end_body_item`.
+
+        New in Robot Framework 7.0.
+        """
+        self.end_body_item(data, result)
+
+    def start_body_item(self, data, result):
+        """Called by default when a keyword or a control structure starts.
+
+        New in Robot Framework 7.0.
+        """
+        pass
+
+    def end_body_item(self, data, result):
+        """Called by default when a keyword or a control structure ends.
+
+        New in Robot Framework 7.0.
+        """
+        pass
 
     def log_message(self, message: Message):
         """Called when a normal log message are emitted.
@@ -548,22 +883,22 @@ class ListenerV3:
         if it is enabled.
         """
 
-    def output_file(self, path: str):
+    def output_file(self, path: Path):
         """Called after the output file has been created.
 
         At this point the file is guaranteed to be closed.
         """
 
-    def log_file(self, path: str):
+    def log_file(self, path: Path):
         """Called after the log file has been created."""
 
-    def report_file(self, path: str):
+    def report_file(self, path: Path):
         """Called after the report file has been created."""
 
-    def xunit_file(self, path: str):
+    def xunit_file(self, path: Path):
         """Called after the xunit compatible output file has been created."""
 
-    def debug_file(self, path: str):
+    def debug_file(self, path: Path):
         """Called after the debug file has been created."""
 
     def close(self):
@@ -605,7 +940,7 @@ class Parser(ABC):
 
     The support for custom parsers is new in Robot Framework 6.1.
     """
-    extension: Union[str, Sequence[str]]
+    extension: 'str | Sequence[str]'
 
     @abstractmethod
     def parse(self, source: Path, defaults: TestDefaults) -> TestSuite: