robotframework 7.3.1__tar.gz → 7.4__tar.gz

{robotframework-7.3.1 → robotframework-7.4}/BUILD.rst

@@ -282,6 +282,6 @@ Announcements
 2. `Forum <https://forum.robotframework.org/>`_.
 
 3. `LinkedIn group <https://www.linkedin.com/groups/3710899/>`_. A personal
-    LinkedIn post is a good idea at least with bigger releases.
+   LinkedIn post is a good idea at least with bigger releases.
 
 4. `robotframework-users <https://groups.google.com/group/robotframework-users>`_

{robotframework-7.3.1 → robotframework-7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: robotframework
-Version: 7.3.1
+Version: 7.4
 Summary: Generic automation framework for acceptance testing and robotic process automation (RPA)
 Home-page: https://robotframework.org
 Download-URL: https://pypi.org/project/robotframework
@@ -10,7 +10,7 @@ License: Apache License 2.0
 Project-URL: Source, https://github.com/robotframework/robotframework
 Project-URL: Issue Tracker, https://github.com/robotframework/robotframework/issues
 Project-URL: Documentation, https://robotframework.org/robotframework
-Project-URL: Release Notes, https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.3.1.rst
+Project-URL: Release Notes, https://github.com/robotframework/robotframework/blob/master/doc/releasenotes/rf-7.4.rst
 Project-URL: Slack, http://slack.robotframework.org
 Keywords: robotframework automation testautomation rpa testing acceptancetesting atdd bdd
 Platform: any

{robotframework-7.3.1 → robotframework-7.4}/setup.py

@@ -6,7 +6,7 @@ from setuptools import find_packages, setup
 
 # Version number typically updated by running `invoke set-version <version>`.
 # Run `invoke --help set-version` or see tasks.py for details.
-VERSION = "7.3.1"
+VERSION = "7.4"
 with open(join(dirname(abspath(__file__)), "README.rst")) as f:
     LONG_DESCRIPTION = f.read()
     base_url = "https://github.com/robotframework/robotframework/blob/master"

{robotframework-7.3.1 → robotframework-7.4}/src/robot/api/__init__.py

@@ -33,6 +33,9 @@ Currently exposed APIs are:
 * :mod:`.interfaces` module containing optional base classes that can be used
   when creating libraries and other extensions. New in Robot Framework 6.1.
 
+* :mod:`.types` module with types exposed for libraries and other extensions.
+  New in Robot Framework 7.4.
+
 * :mod:`.parsing` module exposing the parsing APIs. This module is new in Robot
   Framework 4.0. Various parsing related functions and classes were exposed
   directly via :mod:`robot.api` already in Robot Framework 3.2, but they are

{robotframework-7.3.1 → robotframework-7.4}/src/robot/api/interfaces.py

@@ -22,8 +22,8 @@ Module contents:
 - :class:`ListenerV2` for `listener interface version 2`__.
 - :class:`ListenerV3` for `listener interface version 3`__.
 - :class:`Parser` for `custom parsers`__. Also
-  :class:`~robot.running.builder.settings.TestDefaults` used in ``Parser``
-  type hints can be imported via this module if needed.
+  :class:`~robot.running.builder.settings.TestDefaults` used in :class:`Parser`
+  type hints is exposed via this module.
 - Type definitions used by the aforementioned classes.
 
 Main benefit of using these base classes is that editors can provide automatic
@@ -54,7 +54,7 @@ else:
     UnionType = type
 
 from robot import result, running
-from robot.running import TestDefaults, TestSuite
+from robot.running import TestDefaults as TestDefaults, TestSuite
 
 # Type aliases used by DynamicLibrary and HybridLibrary.
 Name = str

robotframework-7.4/src/robot/api/logger.py

@@ -0,0 +1,219 @@
+#  Copyright 2008-2015 Nokia Networks
+#  Copyright 2016-     Robot Framework Foundation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Public logging API for test libraries.
+
+This module provides a public API for writing messages to the log file
+and the console. Test libraries can use this API like::
+
+    logger.info('My message')
+
+instead of logging through the standard output like::
+
+    print('*INFO* My message')
+
+In addition to a programmatic interface being cleaner to use, this API
+has a benefit that the log messages have accurate timestamps.
+
+If the logging methods are used when Robot Framework is not running,
+the messages are redirected to the standard Python ``logging`` module
+using logger named ``RobotFramework``.
+
+Log levels
+----------
+
+It is possible to log messages using levels ``TRACE``, ``DEBUG``, ``INFO``,
+``WARN`` and ``ERROR`` either using the :func:`write` function or, more
+commonly, with the log level specific :func:`trace`, :func:`debug`,
+:func:`info`, :func:`warn`, :func:`error` functions.
+
+The trace and debug messages are not logged by default, but that can be
+changed with the ``--loglevel`` command line option. Warnings and errors are
+automatically written also to the console and to the *Test Execution Errors*
+section in the log file.
+
+If libraries accept arbitrary log levels and use type hints, they can use
+the :attr:`LogLevel` type alias as shown in the example_ below. It is new
+in Robot Framework 7.4, but :attr:`LOGLEVEL` with same content exists since
+Robot Framework 7.0 and will be available at least until in Robot Framework 9.0.
+
+Logging HTML
+------------
+
+All methods that are used for writing messages to the log file have an
+optional ``html`` argument. If a message to be logged is supposed to be
+shown as HTML, this argument should be set to ``True``. Alternatively,
+:func:`write` accepts a pseudo log level ``HTML``.
+
+Logging to console
+------------------
+
+Normal messages are written only to the log file, not to the console.
+There are, however, various ways to log to the console if needed:
+
+- Messages with ``WARN`` and ``ERROR`` levels are shown on the console automatically.
+- The :func:`console` function logs only to the console.
+- The :func:`info` function supports logging both to the log file and to
+  the console by using the ``also_console`` argument.
+- The :func:`write` function supports a pseudo log level ``CONSOLE`` that
+  can be used for logging both the log file and to the console.
+
+Example
+-------
+
+::
+
+    from robot.api import logger
+
+
+    def my_keyword(arg: str):
+        logger.debug(f"Got argument {arg}.")
+        logger.info("<b>Robot Framework</b> rocks!", html=True)
+
+
+    def another_keyword(arg: int, log_level: logger.LogLevel = "INFO"):
+        logger.write(f"Got argument {arg}.", log_level)
+"""
+
+import logging
+from typing import Literal
+
+from robot.output import librarylogger
+from robot.running.context import EXECUTION_CONTEXTS
+
+# LOGLEVEL was introduced in RF 7.0 and naming convention compliant LogLevel in RF 7.4.
+# TODO: Deprecate LOGLEVEL in RF 8.0. Update the above "Log levels" section as well.
+LogLevel = Literal["TRACE", "DEBUG", "INFO", "CONSOLE", "HTML", "WARN", "ERROR"]
+LOGLEVEL = LogLevel
+
+
+def write(
+    msg: object,
+    level: LogLevel = "INFO",
+    html: bool = False,
+    console: "bool | None" = None,
+):
+    """Writes the message to the log file using the specified level.
+
+    :param msg: The message to be logged. Converted to string automatically.
+    :param level: Either the actual log level to use or a pseudo log level
+        ``HTML`` or ``CONSOLE``.
+    :param html: When set to ``True``, the message is considered to be HTML.
+    :param console:  Controls writing the message to the console in addition
+        to the log file. If ``None`` (default), messages with the ``ERROR`` and
+        ``WARN`` level are written to the console and others are not.
+
+    Valid log levels are ``TRACE``, ``DEBUG``, ``INFO`` (default), ``WARN``,
+    and ``ERROR``. In addition to that, there are pseudo log levels ``HTML``
+    and ``CONSOLE`` for logging messages as HTML and for logging messages
+    both to the log file and to the console, respectively. With both of these
+    pseudo levels the level in the log file will be ``INFO``.
+
+    Instead of using this method, it is generally better to use the level
+    specific methods such as ``info`` and ``debug``.
+
+    The ``CONSOLE`` pseudo level is new in Robot Framework 6.1 and
+    the ``console`` argument is new in Robot Framework 7.4.
+    """
+    if EXECUTION_CONTEXTS.current is not None:
+        librarylogger.write(msg, level, html, console)
+    else:
+        logger = logging.getLogger("RobotFramework")
+        level_int = {
+            "TRACE": logging.DEBUG // 2,
+            "DEBUG": logging.DEBUG,
+            "INFO": logging.INFO,
+            "CONSOLE": logging.INFO,
+            "HTML": logging.INFO,
+            "WARN": logging.WARNING,
+            "ERROR": logging.ERROR,
+        }[level]
+        logger.log(level_int, msg)
+
+
+def trace(msg: object, html: bool = False):
+    """Writes the message to the log file using the ``TRACE`` level.
+
+    :param msg: The message to be logged. Converted to string automatically.
+    :param html: When set to ``True``, the message is considered to be HTML.
+    """
+    write(msg, "TRACE", html)
+
+
+def debug(msg: object, html: bool = False):
+    """Writes the message to the log file using the ``DEBUG`` level.
+
+    :param msg: The message to be logged. Converted to string automatically.
+    :param html: When set to ``True``, the message is considered to be HTML.
+    """
+    write(msg, "DEBUG", html)
+
+
+def info(
+    msg: object,
+    html: bool = False,
+    also_console: bool = False,
+    console: bool = False,
+):
+    """Writes the message to the log file using the ``INFO`` level.
+
+    :param msg: The message to be logged. Converted to string automatically.
+    :param html: When set to ``True``, the message is considered to be HTML.
+    :param also_console: Deprecated alias for ``console``.
+    :param console: When ``True``, the message is logged to the console in
+        addition to the log file.
+
+    The ``console`` argument was introduced in Robot Framework 7.4 as
+    a replacement for the older ``also_console`` argument. Both are supported
+    for now, but ``also_console`` will be deprecated and removed in the future.
+    """
+    write(msg, "INFO", html, also_console or console)
+
+
+def warn(msg: object, html: bool = False, console: bool = True):
+    """Writes the message to the log file using the ``WARN`` level.
+
+    :param msg: The message to be logged. Converted to string automatically.
+    :param html: When set to ``True``, the message is considered to be HTML.
+    :param console: When ``False``, the message is not logged to the console.
+        New in Robot Framework 7.4.
+    """
+    write(msg, "WARN", html, console)
+
+
+def error(msg: object, html: bool = False, console: bool = True):
+    """Writes the message to the log file using the ``ERROR`` level.
+
+    :param msg: The message to be logged. Converted to string automatically.
+    :param html: When set to ``True``, the message is considered to be HTML.
+    :param console: When ``False``, the message is not logged to the console.
+        New in Robot Framework 7.4.
+    """
+    write(msg, "ERROR", html, console)
+
+
+def console(
+    msg: object,
+    newline: bool = True,
+    stream: Literal["stdout", "stderr"] = "stdout",
+):
+    """Writes the message to the console.
+
+    :param msg: The message to be logged. Converted to string automatically.
+    :param newline: When ``True``, a newline character is automatically added
+        to the message.
+    :param stream: Name of the standard stream to write the message to.
+    """
+    librarylogger.console(msg, newline, stream)

robotframework-7.4/src/robot/api/types.py

@@ -0,0 +1,36 @@
+#  Copyright 2008-2015 Nokia Networks
+#  Copyright 2016-     Robot Framework Foundation
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+"""Types that libraries and other extensions can utilize.
+
+- The :class:`~robot.utils.secret.Secret` class is used for encapsulating
+  passwords, tokens and other such secret information.
+
+- :class:`KeywordName` and :class:`KeywordArguments` are used in type hints
+  with keywords executing other keywords. External tools can recognize special
+  arguments using these types and handle them adequately.
+
+New in Robot Framework 7.4.
+"""
+
+from robot.utils.secret import Secret as Secret
+
+
+class KeywordName(str):
+    """Name of a keyword executed by another keyword."""
+
+
+class KeywordArgument:
+    """Argument of a keyword executed by another keyword."""

{robotframework-7.3.1 → robotframework-7.4}/src/robot/conf/settings.py

@@ -174,7 +174,7 @@ class _BaseSettings:
             collect = show = level
         try:
             collect, show = LogLevel(collect), LogLevel(show)
-        except DataError as err:
+        except ValueError as err:
             self._raise_invalid("LogLevel", str(err))
         if collect.priority > show.priority:
             self._raise_invalid(

{robotframework-7.3.1 → robotframework-7.4}/src/robot/errors.py

@@ -119,6 +119,10 @@ TimeoutError = TimeoutExceeded
 class Information(RobotError):
     """Used by argument parser with --help or --version."""
 
+    def __init__(self, message: str, status_rc: bool = True):
+        super().__init__(message)
+        self.rc = INFO_PRINTED if status_rc else 0
+
 
 class ExecutionStatus(RobotError):
     """Base class for exceptions communicating status in test execution."""

{robotframework-7.3.1 → robotframework-7.4}/src/robot/htmldata/htmlfilewriter.py

@@ -52,10 +52,10 @@ class HtmlFileWriter:
 
 
 class Writer(ABC):
-    handles_line = None
+    handles_lines: "str | tuple[str, ...]" = ()
 
-    def handles(self, line: str):
-        return line.startswith(self.handles_line)
+    def handles(self, line: str) -> bool:
+        return line.strip().startswith(self.handles_lines)
 
     @abstractmethod
     def write(self, line: str):
@@ -63,10 +63,7 @@ class Writer(ABC):
 
 
 class ModelWriter(Writer, ABC):
-    handles_line = "<!-- JS MODEL -->"
-
-    def handles(self, line: str):
-        return line.strip().startswith(self.handles_line)
+    handles_lines = "<!-- JS MODEL -->"
 
 
 class LineWriter(Writer):
@@ -74,7 +71,7 @@ class LineWriter(Writer):
     def __init__(self, output: TextIOBase):
         self.output = output
 
-    def handles(self, line: str):
+    def handles(self, line: str) -> bool:
         return True
 
     def write(self, line: str):
@@ -82,7 +79,7 @@ class LineWriter(Writer):
 
 
 class GeneratorWriter(Writer):
-    handles_line = '<meta name="Generator" content='
+    handles_lines = ('<meta name="Generator" content=', "<meta name=Generator content")
 
     def __init__(self, writer: HtmlWriter):
         self.writer = writer
@@ -106,7 +103,7 @@ class InliningWriter(Writer, ABC):
 
 
 class JsFileWriter(InliningWriter):
-    handles_line = '<script type="text/javascript" src='
+    handles_lines = '<script type="text/javascript" src='
 
     def write(self, line: str):
         src = re.search('src="([^"]+)"', line).group(1)
@@ -114,7 +111,7 @@ class JsFileWriter(InliningWriter):
 
 
 class CssFileWriter(InliningWriter):
-    handles_line = '<link rel="stylesheet"'
+    handles_lines = '<link rel="stylesheet"'
 
     def write(self, line: str):
         href, media = re.search('href="([^"]+)" media="([^"]+)"', line).groups()