cocotb 1.9.2__cp38-cp38-win32.whl → 2.0.0b1__cp38-cp38-win32.whl

cocotb/{log.py → logging.py}

@@ -1,29 +1,8 @@
+# Copyright cocotb contributors
 # Copyright (c) 2013, 2018 Potential Ventures Ltd
 # Copyright (c) 2013 SolarFlare Communications Inc
-# All rights reserved.
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#     * Redistributions of source code must retain the above copyright
-#       notice, this list of conditions and the following disclaimer.
-#     * Redistributions in binary form must reproduce the above copyright
-#       notice, this list of conditions and the following disclaimer in the
-#       documentation and/or other materials provided with the distribution.
-#     * Neither the name of Potential Ventures Ltd,
-#       SolarFlare Communications Inc nor the
-#       names of its contributors may be used to endorse or promote products
-#       derived from this software without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL POTENTIAL VENTURES LTD BE LIABLE FOR ANY
-# DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# Licensed under the Revised BSD License, see LICENSE for details.
+# SPDX-License-Identifier: BSD-3-Clause
 
 """
 Everything related to logging
@@ -32,12 +11,14 @@ Everything related to logging
 import logging
 import os
 import sys
-import typing
-import warnings
+from functools import wraps
+from pathlib import Path
+from typing import Union
 
-import cocotb.ANSI as ANSI
-from cocotb import simulator
-from cocotb.utils import get_sim_time, get_time_from_sim_steps, want_color_output
+from cocotb import _ANSI, simulator
+from cocotb._deprecation import deprecated
+from cocotb._utils import want_color_output
+from cocotb.utils import get_sim_time, get_time_from_sim_steps
 
 try:
     _suppress = int(os.environ.get("COCOTB_REDUCED_LOG_FMT", "1"))
@@ -52,14 +33,20 @@ _LINENO_CHARS = 4
 _FUNCNAME_CHARS = 31
 
 # Custom log level
-logging.TRACE = 5
+logging.TRACE = 5  # type: ignore[attr-defined]  # type checkers don't like adding module attributes after the fact
 logging.addLevelName(5, "TRACE")
 
-# Default log level if not overwritten by the user.
-_COCOTB_LOG_LEVEL_DEFAULT = "INFO"
 
+__all__ = (
+    "SimColourLogFormatter",
+    "SimLog",
+    "SimLogFormatter",
+    "SimTimeContextFilter",
+    "default_config",
+)
 
-def default_config():
+
+def default_config() -> None:
     """Apply the default cocotb log formatting to the root logger.
 
     This hooks up the logger to write to stdout, using either
@@ -68,17 +55,16 @@ def default_config():
     :class:`SimTimeContextFilter` filter so that
     :attr:`~logging.LogRecord.created_sim_time` is available to the formatter.
 
-    The logging level for cocotb logs is set based on the
-    :envvar:`COCOTB_LOG_LEVEL` environment variable, which defaults to ``INFO``.
-
     If desired, this logging configuration can be overwritten by calling
     ``logging.basicConfig(..., force=True)`` (in Python 3.8 onwards), or by
     manually resetting the root logger instance.
     An example of this can be found in the section on :ref:`rotating-logger`.
 
     .. versionadded:: 1.4
+
+    .. versionchanged:: 2.0
+        No longer set the log level of the ``cocotb`` and ``gpi`` loggers.
     """
-    # construct an appropriate handler
     hdlr = logging.StreamHandler(sys.stdout)
     hdlr.addFilter(SimTimeContextFilter())
     if want_color_output():
@@ -86,66 +72,71 @@ def default_config():
     else:
         hdlr.setFormatter(SimLogFormatter())
 
-    logging.setLoggerClass(SimBaseLog)  # For backwards compatibility
     logging.basicConfig()
     logging.getLogger().handlers = [hdlr]  # overwrite default handlers
 
-    # apply level settings for cocotb
-    log = logging.getLogger("cocotb")
-
-    try:
-        # All log levels are upper case, convert the user input for convenience.
-        level = os.environ["COCOTB_LOG_LEVEL"].upper()
-    except KeyError:
-        level = _COCOTB_LOG_LEVEL_DEFAULT
-
-    try:
-        log.setLevel(level)
-    except ValueError:
-        valid_levels = ("CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "TRACE")
-        raise ValueError(
-            "Invalid log level %r passed through the "
-            "COCOTB_LOG_LEVEL environment variable. Valid log "
-            "levels: %s" % (level, ", ".join(valid_levels))
-        )
 
-    # Notify GPI of log level, which it uses as an optimization to avoid
-    # calling into Python.
-    logging.getLogger("gpi").setLevel(level)
+def _init(_: object) -> None:
+    """Set cocotb and pygpi log levels."""
 
+    # Monkeypatch "gpi" logger with function that also sets a PyGPI-local logger level
+    # as an optimization.
+    gpi_logger = logging.getLogger("gpi")
+    old_setLevel = gpi_logger.setLevel
 
-class SimBaseLog(logging.getLoggerClass()):
-    """This class only exists for backwards compatibility"""
+    @wraps(old_setLevel)
+    def setLevel(level: Union[int, str]) -> None:
+        old_setLevel(level)
+        simulator.set_gpi_log_level(gpi_logger.getEffectiveLevel())
 
-    @property
-    def logger(self):
-        warnings.warn(
-            "the .logger attribute should not be used now that `SimLog` "
-            "returns a native logger instance directly.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return self
-
-    @property
-    def colour(self):
-        warnings.warn(
-            "the .colour attribute may be removed in future, use the "
-            "equivalent `cocotb.utils.want_color_output()` instead",
-            DeprecationWarning,
-            stacklevel=2,
-        )
-        return want_color_output()
+    gpi_logger.setLevel = setLevel  # type: ignore[method-assign]
 
-    def setLevel(self, level: typing.Union[int, str]) -> None:
-        super().setLevel(level)
-        if self.name == "gpi":
-            simulator.log_level(self.getEffectiveLevel())
+    # Initialize PyGPI logging
+    simulator.initialize_logger(_log_from_c, logging.getLogger)
+
+    # Set "cocotb" and "gpi" logger based on environment variables
+    def set_level(logger_name: str, envvar: str, default_level: str) -> None:
+        log_level = os.environ.get(envvar, default_level)
+        log_level = log_level.upper()
+
+        logger = logging.getLogger(logger_name)
+
+        try:
+            logger.setLevel(log_level)
+        except ValueError:
+            valid_levels = ", ".join(
+                ("CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "TRACE", "NOTSET")
+            )
+            raise ValueError(
+                f"Invalid log level {log_level!r} passed through the "
+                f"{envvar} environment variable. Valid log "
+                f"levels: {valid_levels}"
+            ) from None
 
+    set_level("gpi", "GPI_LOG_LEVEL", "INFO")
+    set_level("cocotb", "COCOTB_LOG_LEVEL", "INFO")
 
-# this used to be a class, hence the unusual capitalization
-def SimLog(name, ident=None):
-    """Like logging.getLogger, but append a numeric identifier to the name"""
+
+def _setup_formatter(_: object) -> None:
+    """Setup cocotb's logging formatter."""
+    default_config()
+
+
+@deprecated('Use `logging.getLogger(f"{name}.0x{ident:x}")` instead')
+def SimLog(name: str, ident: Union[int, None] = None) -> logging.Logger:
+    """Like logging.getLogger, but append a numeric identifier to the name.
+
+    Args:
+        name: Logger name.
+        ident: Unique integer identifier.
+
+    Returns:
+        The Logger named ``{name}.0x{ident:x}``.
+
+    .. deprecated:: 2.0
+
+        Use ``logging.getLogger(f"{name}.0x{ident:x}")`` instead.
+    """
     if ident is not None:
         name = f"{name}.0x{ident:x}"
     return logging.getLogger(name)
@@ -163,11 +154,11 @@ class SimTimeContextFilter(logging.Filter):
     """
 
     # needed to make our docs render well
-    def __init__(self):
+    def __init__(self) -> None:
         """"""
         super().__init__()
 
-    def filter(self, record):
+    def filter(self, record: logging.LogRecord) -> bool:
         try:
             record.created_sim_time = get_sim_time()
         except RecursionError:
@@ -187,24 +178,26 @@ class SimLogFormatter(logging.Formatter):
 
     # Removes the arguments from the base class. Docstring needed to make
     # sphinx happy.
-    def __init__(self):
+    def __init__(self) -> None:
         """Takes no arguments."""
         super().__init__()
 
     # Justify and truncate
     @staticmethod
-    def ljust(string, chars):
+    def ljust(string: str, chars: int) -> str:
         if len(string) > chars:
             return ".." + string[(chars - 2) * -1 :]
         return string.ljust(chars)
 
     @staticmethod
-    def rjust(string, chars):
+    def rjust(string: str, chars: int) -> str:
         if len(string) > chars:
             return ".." + string[(chars - 2) * -1 :]
         return string.rjust(chars)
 
-    def _format(self, level, record, msg, coloured=False):
+    def _format(
+        self, level: str, record: logging.LogRecord, msg: str, coloured: bool = False
+    ) -> str:
         sim_time = getattr(record, "created_sim_time", None)
         if sim_time is None:
             sim_time_str = "  -.--ns"
@@ -221,7 +214,7 @@ class SimLogFormatter(logging.Formatter):
         )
         if not _suppress:
             prefix += (
-                self.rjust(os.path.split(record.filename)[1], _FILENAME_CHARS)
+                self.rjust(Path(record.filename).name, _FILENAME_CHARS)
                 + ":"
                 + self.ljust(str(record.lineno), _LINENO_CHARS)
                 + " in "
@@ -229,7 +222,7 @@ class SimLogFormatter(logging.Formatter):
                 + " "
             )
 
-        # these lines are copied from the builtin logger
+        # these lines are copied from the built-in logger
         if record.exc_info:
             # Cache the traceback text to avoid converting it multiple times
             # (it's constant anyway)
@@ -246,8 +239,8 @@ class SimLogFormatter(logging.Formatter):
         pad = "\n" + " " * (prefix_len)
         return prefix + pad.join(msg.split("\n"))
 
-    def format(self, record):
-        """Prettify the log output, annotate with simulation time"""
+    def format(self, record: logging.LogRecord) -> str:
+        """Prettify the log output by annotating with simulation time."""
 
         msg = record.getMessage()
         level = record.levelname.ljust(_LEVEL_CHARS)
@@ -259,16 +252,16 @@ class SimColourLogFormatter(SimLogFormatter):
     """Log formatter to provide consistent log message handling."""
 
     loglevel2colour = {
-        logging.TRACE: "%s",
+        logging.TRACE: "%s",  # type: ignore[attr-defined]  # type checkers don't like adding module attributes after the fact
         logging.DEBUG: "%s",
         logging.INFO: "%s",
-        logging.WARNING: ANSI.COLOR_WARNING + "%s" + ANSI.COLOR_DEFAULT,
-        logging.ERROR: ANSI.COLOR_ERROR + "%s" + ANSI.COLOR_DEFAULT,
-        logging.CRITICAL: ANSI.COLOR_CRITICAL + "%s" + ANSI.COLOR_DEFAULT,
+        logging.WARNING: _ANSI.COLOR_WARNING + "%s" + _ANSI.COLOR_DEFAULT,
+        logging.ERROR: _ANSI.COLOR_ERROR + "%s" + _ANSI.COLOR_DEFAULT,
+        logging.CRITICAL: _ANSI.COLOR_CRITICAL + "%s" + _ANSI.COLOR_DEFAULT,
     }
 
-    def format(self, record):
-        """Prettify the log output, annotate with simulation time"""
+    def format(self, record: logging.LogRecord) -> str:
+        """Prettify the log output by annotating with simulation time."""
 
         msg = record.getMessage()
 
@@ -286,18 +279,20 @@ class SimColourLogFormatter(SimLogFormatter):
         return self._format(level, record, msg, coloured=True)
 
 
-def _filter_from_c(logger_name, level):
-    return logging.getLogger(logger_name).isEnabledFor(level)
-
-
-def _log_from_c(logger_name, level, filename, lineno, msg, function_name):
+def _log_from_c(
+    logger: logging.Logger,
+    level: int,
+    filename: str,
+    lineno: int,
+    msg: str,
+    function_name: str,
+) -> None:
     """
     This is for use from the C world, and allows us to insert C stack
     information.
     """
-    logger = logging.getLogger(logger_name)
     if logger.isEnabledFor(level):
         record = logger.makeRecord(
-            logger.name, level, filename, lineno, msg, None, None, function_name
+            logger.name, level, filename, lineno, msg, (), None, function_name
         )
         logger.handle(record)