python-code-validator 0.1.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

code_validator/output.py

@@ -7,12 +7,50 @@ controlled via configuration (e.g., log levels, silent mode).
 
 import logging
 import sys
-from typing import Literal
+from functools import wraps
+from typing import Callable, Concatenate, Literal, ParamSpec, TypeVar
 
 from .config import LogLevel
 
-LOG_FORMAT = "%(asctime)s | %(filename)-15s | %(funcName)-15s (%(lineno)-3s) | [%(levelname)s] - %(message)s"
 DATE_FORMAT = "%Y-%m-%d %H:%M:%S"
+LOG_FORMAT = (
+    "{asctime}.{msecs:03.0f} | "
+    "{levelname:^8} | "
+    "[{processName}({process})/{threadName}({thread})] | "
+    "{filename}:{funcName}:{lineno} | "
+    "{message}"
+)
+
+TRACE_LEVEL_NUM = 5
+logging.addLevelName(TRACE_LEVEL_NUM, "TRACE")
+
+
+def trace(self, message, *args, **kws):
+    """Logs a message with TRACE level (below DEBUG).
+
+    This method allows logging messages with a custom TRACE level,
+    defined at level number 5. It only emits the log if the logger
+    is enabled for this level.
+
+    To enable usage, attach this method to the `logging.Logger` class:
+
+        logging.Logger.trace = trace
+
+    Args:
+        self: logger instance.
+        message: The log message format string.
+        *args: Arguments to be merged into the message format string.
+        **kws: Optional keyword arguments passed to the logger,
+               e.g., `exc_info`, `stacklevel`, or `extra`.
+
+    Returns:
+        None
+    """
+    if self.isEnabledFor(TRACE_LEVEL_NUM):
+        self._log(TRACE_LEVEL_NUM, message, args, **kws)
+
+
+logging.Logger.trace = trace
 
 
 def setup_logging(log_level: LogLevel) -> logging.Logger:
@@ -27,8 +65,75 @@ def setup_logging(log_level: LogLevel) -> logging.Logger:
     Returns:
         The configured root logger instance.
     """
-    logging.basicConfig(level=log_level, format=LOG_FORMAT, datefmt=DATE_FORMAT)
-    return logging.getLogger()
+    formatter = logging.Formatter(fmt=LOG_FORMAT, datefmt=DATE_FORMAT, style="{")
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(formatter)
+
+    root_logger = logging.getLogger()
+    root_logger.setLevel(log_level)
+
+    if root_logger.hasHandlers():
+        root_logger.handlers.clear()
+
+    root_logger.addHandler(handler)
+
+    return root_logger
+
+
+P = ParamSpec("P")
+T_self = TypeVar("T_self")
+
+
+def log_initialization(
+    level: LogLevel | Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = LogLevel.TRACE,
+    start_message: str = "Initializing {class_name}...",
+    end_message: str = "{class_name} initialized.",
+) -> Callable[[Callable[Concatenate[T_self, P], None]], Callable[Concatenate[T_self, P], None]]:
+    """Decorator factory for logging the initialization of a class instance.
+
+    This decorator wraps a class's `__init__` method to automatically log
+    messages before and after the constructor's execution. It helps in
+    observing the lifecycle of objects, especially complex ones, without
+    cluttering the `__init__` method itself.
+
+    The log messages can include a `{class_name}` placeholder, which will
+    be replaced by the actual name of the class being initialized.
+
+    Args:
+        level: The logging level (e.g., `LogLevel.DEBUG`, `LogLevel.INFO`)
+            at which the messages should be logged.
+        start_message: the message string to log immediately before the
+            `__init__` method is called. This string can contain the
+            `{class_name}` placeholder.
+        end_message: The message string to log immediately after the
+            `__init__` method completes its execution. This string can
+            contain the `{class_name}` placeholder.
+
+    Returns:
+        A decorator function that can be applied to an `__init__` method
+        of a class.
+    """
+
+    def decorator(init_method: Callable[Concatenate[T_self, P], None]) -> Callable[Concatenate[T_self, P], None]:
+        """The actual decorator function."""
+
+        @wraps(init_method)
+        def wrapper(self: T_self, *args: P.args, **kwargs: P.kwargs) -> None:
+            """The wrapper function that adds logging around __init__."""
+            class_name = self.__class__.__name__
+            logger = logging.getLogger(self.__class__.__module__)
+            level_num = logging.getLevelName(level if isinstance(level, LogLevel) else level)
+
+            logger.log(level_num, start_message.format(class_name=class_name))
+            result = init_method(self, *args, **kwargs)
+            logger.log(level_num, end_message.format(class_name=class_name))
+
+            return result
+
+        return wrapper
+
+    return decorator
 
 
 class Console:
@@ -40,7 +145,7 @@ class Console:
 
     Attributes:
         _logger (logging.Logger): The logger instance used for all log records.
-        _is_silent (bool): A flag to suppress printing to stdout.
+        _is_quiet (bool): A flag to suppress printing to stdout.
         _stdout (TextIO): The stream to write messages to (defaults to sys.stdout).
 
     Example:
@@ -53,22 +158,59 @@ class Console:
         This is a warning.
     """
 
-    def __init__(self, logger: logging.Logger, *, is_silent: bool = False):
+    @log_initialization(level=LogLevel.TRACE)
+    def __init__(self, logger: logging.Logger, *, is_quiet: bool = False, show_verdict: bool = True):
         """Initializes the Console handler.
 
         Args:
             logger: The configured logger instance to use for logging.
-            is_silent: If True, suppresses output to stdout. Defaults to False.
+            is_quiet: If True, suppresses output to stdout. Defaults to False.
+            show_verdict: If False, suppresses showing verdicts. Default to True
         """
         self._logger = logger
-        self._is_silent = is_silent
+        self._is_quiet = is_quiet
+        self._show_verdict = show_verdict
         self._stdout = sys.stdout
 
+    def should_print(self, is_verdict: bool, show_user: bool) -> bool:
+        """Decides whether a message should be printed to stdout based on console flags.
+
+        Quiet mode (Q) suppresses all output if enabled. For non-verdict messages (¬V),
+        printing is allowed only when show_user (O) is True. For verdict messages (V),
+        printing is allowed only when show_verdict (S) is True.
+
+        Mathematically:
+            F = ¬Q ∧ ( (¬V ∧ O) ∨ (V ∧ S) )
+        where
+            Q = self._is_quiet,
+            V = is_verdict,
+            S = self._show_verdict,
+            O = show_user.
+
+        Proof sketch:
+            1. If Q is True, then ¬Q = False ⇒ F = False (silent mode).
+            2. If Q is False, split on V:
+               a. V = False ⇒ F = ¬Q ∧ O;
+               b. V = True  ⇒ F = ¬Q ∧ S.
+            3. Combine branches into F = ¬Q ∧ ( (¬V ∧ O) ∨ (V ∧ S) ).
+
+        Args:
+            is_verdict: True if this message is a verdict; controls branch V.
+            show_user: True if non-verdict messages should be printed; controls branch O.
+
+        Returns:
+            True if and only if the combined condition F holds, i.e. the message may be printed.
+        """
+        return not self._is_quiet and ((not is_verdict and show_user) or (is_verdict and self._show_verdict))
+
     def print(
         self,
         message: str,
         *,
-        level: LogLevel | Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = LogLevel.INFO,
+        level: LogLevel | Literal["TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = LogLevel.TRACE,
+        is_verdict: bool = False,
+        show_user: bool = False,
+        exc_info: bool = False,
     ) -> None:
         """Prints a message to stdout and logs it simultaneously.
 
@@ -80,11 +222,17 @@ class Console:
             message: The string message to be displayed and logged.
             level: The logging level for the message. Accepts both LogLevel
                    enum members and their string representations.
-                   Defaults to LogLevel.INFO.
+                   Defaults to LogLevel.TRACE.
+            is_verdict: If True, this message is considered a
+                        verdict and its printing is controlled by the
+                        console’s `show_verdict` flag. Defaults to False.
+            show_user:  If True and `is_verdict=False`, allows
+                        printing non-verdict messages to stdout. Defaults to
+                        False.
+            exc_info:   If True this work as loggings.exception("<message>").
         """
-        level_str = level.value.lower() if isinstance(level, LogLevel) else level.lower()
-        log_method = getattr(self._logger, level_str)
-        log_method(message)
+        level_num = logging.getLevelName(level if isinstance(level, LogLevel) else level)
+        self._logger.log(level_num, message, stacklevel=2, exc_info=exc_info)
 
-        if not self._is_silent:
+        if (not self._is_quiet) and ((not is_verdict and show_user) or (is_verdict and self._show_verdict)):
             print(message, file=self._stdout)

code_validator/rules_library/basic_rules.py

@@ -13,7 +13,7 @@ import sys
 
 from ..components.definitions import Constraint, Rule, Selector
 from ..config import FullRuleConfig, ShortRuleConfig
-from ..output import Console, LogLevel
+from ..output import Console, LogLevel, log_initialization
 
 
 class CheckSyntaxRule(Rule):
@@ -27,6 +27,7 @@ class CheckSyntaxRule(Rule):
         formally defined in the JSON configuration.
     """
 
+    @log_initialization(level=LogLevel.TRACE)
     def __init__(self, config: ShortRuleConfig, console: Console):
         """Initializes the syntax check rule handler.
 
@@ -45,7 +46,7 @@ class CheckSyntaxRule(Rule):
         Returns:
             Always returns True.
         """
-        self._console.print(f"Rule {self.config.rule_id}: Syntax is valid.", level=LogLevel.DEBUG)
+        self._console.print(f"Rule {self.config.rule_id}: Syntax is valid.", level=LogLevel.INFO)
         return True
 
 
@@ -57,6 +58,7 @@ class CheckLinterRule(Rule):
     configurable via the 'params' field in the JSON rule.
     """
 
+    @log_initialization(level=LogLevel.TRACE)
     def __init__(self, config: ShortRuleConfig, console: Console):
         """Initializes a PEP8 linter check rule handler."""
         self.config = config
@@ -80,7 +82,7 @@ class CheckLinterRule(Rule):
             self._console.print("Source code is empty, skipping PEP8 check.", level=LogLevel.WARNING)
             return True
 
-        self._console.print(f"Rule {self.config.rule_id}: Running flake8 linter...", level=LogLevel.DEBUG)
+        self._console.print(f"Rule {self.config.rule_id}: Running PEP8 linter...", level=LogLevel.INFO)
 
         params = self.config.params
         args = [sys.executable, "-m", "flake8", "-"]
@@ -90,6 +92,8 @@ class CheckLinterRule(Rule):
         elif ignore_list := params.get("ignore"):
             args.append(f"--ignore={','.join(ignore_list)}")
 
+        self._console.print(f"Arguments for flake8: {args}", level=LogLevel.TRACE)
+
         try:
             process = subprocess.run(
                 args,
@@ -102,7 +106,7 @@ class CheckLinterRule(Rule):
 
             if process.returncode != 0 and process.stdout:
                 linter_output = process.stdout.strip()
-                self._console.print(f"Flake8 found issues:\n{linter_output}", level=LogLevel.DEBUG)
+                self._console.print(f"Flake8 found issues:\n{linter_output}", level=LogLevel.WARNING, show_user=True)
                 return False
             elif process.returncode != 0:
                 self._console.print(
@@ -110,7 +114,7 @@ class CheckLinterRule(Rule):
                 )
                 return False
 
-            self._console.print("PEP8 check passed.", level=LogLevel.ERROR)
+            self._console.print("PEP8 check passed.", level=LogLevel.INFO)
             return True
         except FileNotFoundError:
             self._console.print("flake8 not found. Is it installed in the venv?", level=LogLevel.CRITICAL)
@@ -134,6 +138,7 @@ class FullRuleHandler(Rule):
         _console (Console): The console handler for logging.
     """
 
+    @log_initialization(level=LogLevel.TRACE)
     def __init__(self, config: FullRuleConfig, selector: Selector, constraint: Constraint, console: Console):
         """Initializes a full rule handler.
 
@@ -162,8 +167,8 @@ class FullRuleHandler(Rule):
             self._console.print("AST not available, skipping rule.", level=LogLevel.WARNING)
             return True
 
-        self._console.print(f"Applying selector: {self._selector.__class__.__name__}", level=LogLevel.DEBUG)
+        self._console.print(f"Applying selector: {self._selector.__class__.__name__}", level=LogLevel.TRACE)
         selected_nodes = self._selector.select(tree)
 
-        self._console.print(f"Applying constraint: {self._constraint.__class__.__name__}", level=LogLevel.DEBUG)
+        self._console.print(f"Applying constraint: {self._constraint.__class__.__name__}", level=LogLevel.TRACE)
         return self._constraint.check(selected_nodes)