Move MetaWarning classes into new cli module

codebasin/__main__.py

@@ -8,10 +8,10 @@
 import argparse
 import logging
 import os
-import re
 import sys
 
 from codebasin import CodeBase, config, finder, report, util
+from codebasin.cli import Formatter, WarningAggregator
 
 log = logging.getLogger("codebasin")
 version = "1.2.0"
@@ -54,100 +54,6 @@ def _help_string(*lines: str, is_long=False, is_last=False):
     return result
 
 
-class Formatter(logging.Formatter):
-    def __init__(self, *, colors: bool = False):
-        self.colors = colors
-
-    def format(self, record: logging.LogRecord) -> str:
-        msg = record.msg
-        level = record.levelname.lower()
-
-        # Display info messages with no special formatting.
-        if level == "info":
-            return f"{msg}"
-
-        # Drop colors if requested.
-        if not self.colors:
-            return f"{level}: {msg}"
-
-        # Otherwise, use ASCII codes to improve readability.
-        BOLD = "\033[1m"
-        DEFAULT = "\033[39m"
-        YELLOW = "\033[93m"
-        RED = "\033[91m"
-        RESET = "\033[0m"
-
-        if level == "warning":
-            color = YELLOW
-        elif level == "error":
-            color = RED
-        else:
-            color = DEFAULT
-        return f"{BOLD}{color}{level}{RESET}: {msg}"
-
-
-class MetaWarning:
-    """
-    A MetaWarning is used to represent multiple warnings, and provide suggested
-    actions to the user.
-    """
-
-    def __init__(self, regex: str, msg: str):
-        self.regex = re.compile(regex)
-        self.msg = msg
-        self._count = 0
-
-    def inspect(self, record: logging.LogRecord):
-        if self.regex.search(record.msg):
-            self._count += 1
-
-    def warn(self):
-        if self._count == 0:
-            return
-        log.warning(self.msg.format(self._count))
-
-
-class WarningAggregator(logging.Filter):
-    """
-    Inspect warnings to generate meta-warnings and statistics.
-    """
-
-    def __init__(self):
-        self.meta_warnings = [
-            MetaWarning(".", "{} warnings generated during preprocessing."),
-            MetaWarning(
-                "user include",
-                "{} user include files could not be found.\n"
-                + "  These could contain important macros and includes.\n"
-                + "  Suggested solutions:\n"
-                + "  - Check that the file(s) exist in the code base.\n"
-                + "  - Check the include paths in the compilation database.\n"
-                + "  - Check if the include(s) should have used '<>'.",
-            ),
-            MetaWarning(
-                "system include",
-                "{} system include files could not be found.\n"
-                + "  These could define important feature macros.\n"
-                + "  Suggested solutions:\n"
-                + "  - Check that the file(s) exist on your system.\n"
-                + "  - Use .cbi/config to define system include paths.\n"
-                + "  - Use .cbi/config to define important macros.",
-            ),
-        ]
-
-    def filter(self, record: logging.LogRecord) -> bool:
-        if record.levelno == logging.WARNING:
-            for meta_warning in self.meta_warnings:
-                meta_warning.inspect(record)
-
-        # Do not filter anything.
-        return True
-
-    def warn(self):
-        for meta_warning in self.meta_warnings:
-            meta_warning.warn()
-
-
 def _main():
     # Read command-line arguments
     parser = argparse.ArgumentParser(
@@ -325,7 +231,7 @@ def _main():
     # Generate meta-warnings and statistics.
     # Temporarily override log_level to ensure they are visible.
     stdout_handler.setLevel(logging.WARNING)
-    aggregator.warn()
+    aggregator.warn(log)
     stdout_handler.setLevel(log_level)
 
     # Count lines for platforms

codebasin/cli.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+# Copyright (C) 2019-2024 Intel Corporation
+# SPDX-License-Identifier: BSD-3-Clause
+
+import logging
+import re
+
+
+class Formatter(logging.Formatter):
+    """
+    A Formatter that formats LogRecords using a format inspired by compilers
+    like gcc/clang, with optional colors.
+    """
+
+    def __init__(self, *, colors: bool = False):
+        """
+        Initialize this Formatter.
+
+        Parameters
+        ----------
+        colors: bool, default: False
+            Whether to colorize the output.
+        """
+        self.colors = colors
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        Format the specified record.
+
+        Parameters
+        ----------
+        record: logging.LogRecord
+            The record to format.
+
+        Returns
+        -------
+        str
+            The formatted output string.
+        """
+        msg = record.msg
+        level = record.levelname.lower()
+
+        # Display info messages with no special formatting.
+        if level == "info":
+            return f"{msg}"
+
+        # Drop colors if requested.
+        if not self.colors:
+            return f"{level}: {msg}"
+
+        # Otherwise, use ASCII codes to improve readability.
+        BOLD = "\033[1m"
+        DEFAULT = "\033[39m"
+        YELLOW = "\033[93m"
+        RED = "\033[91m"
+        RESET = "\033[0m"
+
+        if level == "warning":
+            color = YELLOW
+        elif level == "error":
+            color = RED
+        else:
+            color = DEFAULT
+        return f"{BOLD}{color}{level}{RESET}: {msg}"
+
+
+class MetaWarning:
+    """
+    A MetaWarning is used to represent multiple warnings, and to provide
+    suggested actions to the user.
+    """
+
+    def __init__(self, regex: str, msg: str):
+        """
+        Initialize a new MetaWarning.
+
+        Parameters
+        ----------
+        regex: str
+            A regular expression used to identify constituent warnings.
+            If any warning matches `regex`, this MetaWarning will trigger.
+
+        msg: str
+            The message to display when this MetaWarning is triggered.
+        """
+        self.regex = re.compile(regex)
+        self.msg = msg
+        self._count = 0
+
+    def inspect(self, record: logging.LogRecord) -> bool:
+        """
+        Inspect a LogRecord to determine if it matches this MetaWarning.
+
+        Parameters
+        ----------
+        record: logging.LogRecord
+            The LogRecord to inspect.
+
+        Returns
+        -------
+        bool
+            True if `record` matches this MetaWarning and False otherwise.
+        """
+        if self.regex.search(record.msg):
+            self._count += 1
+            return True
+        return False
+
+    def warn(self, logger: logging.Logger):
+        """
+        Produce the warning associated with this MetaWarning.
+
+        Parameters
+        ----------
+        log: logging.Logger
+            The Logger that should be used to generate the MetaWarning.
+        """
+        if self._count == 0:
+            return
+        logger.warning(self.msg.format(self._count))
+
+
+class WarningAggregator(logging.Filter):
+    """
+    A WarningAggregator is a logging.Filter that inspects warnings to generate
+    meta-warnings and statistics. It does not perform any filtering, but uses
+    the logging.Filter mechanism as a hook to automatically inspect every
+    warning passing through a logger.
+    """
+
+    def __init__(self):
+        self.meta_warnings = [
+            MetaWarning(".", "{} warnings generated during preprocessing."),
+            MetaWarning(
+                "user include",
+                "{} user include files could not be found.\n"
+                + "  These could contain important macros and includes.\n"
+                + "  Suggested solutions:\n"
+                + "  - Check that the file(s) exist in the code base.\n"
+                + "  - Check the include paths in the compilation database.\n"
+                + "  - Check if the include(s) should have used '<>'.",
+            ),
+            MetaWarning(
+                "system include",
+                "{} system include files could not be found.\n"
+                + "  These could define important feature macros.\n"
+                + "  Suggested solutions:\n"
+                + "  - Check that the file(s) exist on your system.\n"
+                + "  - Use .cbi/config to define system include paths.\n"
+                + "  - Use .cbi/config to define important macros.",
+            ),
+        ]
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """
+        Inspect the specified LogRecord, attempting to match it against each
+        possible MetaWarning.
+
+        Parameters
+        ----------
+        record: logging.LogRecord
+            The record to inspect.
+
+        Returns
+        -------
+        bool
+            True, to prevent any warnings from being filtered.
+        """
+        if record.levelno == logging.WARNING:
+            for meta_warning in self.meta_warnings:
+                meta_warning.inspect(record)
+        return True
+
+    def warn(self, logger: logging.Logger):
+        """
+        Produce the warning associated with any MetaWarning(s) that were
+        matched by this WarningAggregator.
+
+        Parameters
+        ----------
+        logger: logging.Logger
+            The Logger that should be used to generate the MetaWarning(s).
+        """
+        for meta_warning in self.meta_warnings:
+            meta_warning.warn(logger)

tests/cli/test_formatter.py

@@ -0,0 +1,55 @@
+# Copyright (C) 2019-2024 Intel Corporation
+# SPDX-License-Identifier: BSD-3-Clause
+
+import logging
+import unittest
+
+from codebasin.cli import Formatter
+
+
+class TestFormatter(unittest.TestCase):
+    """
+    Test Formatter class.
+    """
+
+    def setUp(self):
+        logging.disable()
+
+    def test_constructor(self):
+        """Check constructor arguments"""
+        self.assertTrue(Formatter(colors=True).colors)
+        self.assertFalse(Formatter(colors=False).colors)
+        self.assertFalse(Formatter().colors)
+
+    def test_format(self):
+        """Check output format"""
+        levels = ["DEBUG", "INFO", "WARNING", "ERROR"]
+        colors = ["\033[39m", "\033[39m", "\033[93m", "\033[91m"]
+        for colorize in [True, False]:
+            for levelname, color in zip(levels, colors):
+                formatter = Formatter(colors=colorize)
+                with self.subTest(
+                    colorize=colorize,
+                    levelname=levelname,
+                    color=color,
+                ):
+                    record = logging.makeLogRecord(
+                        {
+                            "msg": "Testing",
+                            "levelname": levelname,
+                        },
+                    )
+                    msg = record.msg
+                    level = record.levelname.lower()
+                    output = formatter.format(record)
+                    if level == "info":
+                        expected = msg
+                    elif colorize:
+                        expected = f"\033[1m{color}{level}\033[0m: {msg}"
+                    else:
+                        expected = f"{level}: {msg}"
+                    self.assertEqual(output, expected)
+
+
+if __name__ == "__main__":
+    unittest.main()