log_level¶

class LogLevel(StrEnum):
    """
    Logical log levels for the CLI.

    Includes a custom TRACE (more verbose than DEBUG) and QUIET
    (suppresses all output beyond CRITICAL).
    """

    TRACE = "trace"
    DEBUG = "debug"
    INFO = "info"
    WARNING = "warning"
    ERROR = "error"
    QUIET = "quiet"

    @classmethod
    def parse(cls, value: str | None) -> LogLevel | None:
        """Parse case-insensitively; returns None if value is falsy."""
        if not value:
            return None
        norm = value.strip().lower()
        try:
            return cls(norm)
        except ValueError as exc:
            valid = ", ".join(v.value for v in cls)
            raise UnknownLogLevelError(value, valid) from exc

    @classmethod
    def get_default_log_level(cls) -> LogLevel:
        """
        Returns the log level used when none is configured.

        Returns:
            LogLevel: `LogLevel.INFO`.
        """
        return LogLevel.INFO

    def to_logging_level(self) -> int:
        """
        Converts this logical `LogLevel` into a stdlib `logging` level number.

        `TRACE` maps to `0` (below `logging.DEBUG`, see `core/log_utils.py`'s
        custom TRACE level) and `QUIET` maps to `logging.CRITICAL + 10`, so
        it suppresses even CRITICAL records.

        Returns:
            int: The equivalent stdlib `logging` level.
        """
        r = logging.INFO
        if self is LogLevel.TRACE:
            r = 0
        if self is LogLevel.DEBUG:
            r = logging.DEBUG
        if self is LogLevel.INFO:
            r = logging.INFO
        if self is LogLevel.WARNING:
            r = logging.WARNING
        if self is LogLevel.ERROR:
            r = logging.ERROR
        if self is LogLevel.QUIET:
            r = logging.CRITICAL + 10
        return r