Console & Logging

Handles all console output and logging for the application.

This module provides a centralized way to manage user-facing messages and internal logging. It ensures that all output is consistent and can be controlled via configuration (e.g., log levels, silent mode).

class code_validator.output.Console(logger: Logger, *, is_quiet: bool = False, show_verdict: bool = True)

Bases: object

A centralized handler for printing messages to stdout and logging.

This class abstracts all output operations, allowing for consistent formatting and easy control over verbosity (e.g., silent mode). It ensures that every user-facing message is also properly logged.

_logger

The logger instance used for all log records.

Type:

logging.Logger

_is_quiet

A flag to suppress printing to stdout.

Type:

bool

_stdout

The stream to write messages to (defaults to sys.stdout).

Type:

TextIO

Example

>>> import logging
>>> logger = logging.getLogger(__name__)
>>> console = Console(logger)
>>> console.print("This is an informational message.")
This is an informational message.
>>> console.print("This is a warning.", level="WARNING")
This is a warning.
print(message: str, *, 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.

The message is always sent to the logger with the specified level. It is printed to the configured stdout stream only if the console is not in silent mode.

Parameters:

  • 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.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>”).

set_current_file_path(file_path: str) → None

Set the current file path for typo detection context.

Parameters:

file_path – Path to the file currently being validated

should_print(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) ).

Parameters:

  • 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.

code_validator.output.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.

Parameters:

  • 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.

code_validator.output.setup_logging(log_level: LogLevel) → Logger

Configures the root logger for the application.

Sets up the basic configuration for logging, including the level, message format, and date format.

Parameters:

log_level – The minimum level of logs to display.

Returns:

The configured root logger instance.

code_validator.output.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

Parameters:

  • 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