refactor(logging): extract resolve_log_level and create_log_handler into log.py

Add DEFAULT_LOG_FORMAT constant to constants.py and extract two public
functions into log.py: resolve_log_level() for env-var-based level
resolution and create_log_handler() for TTY-aware handler selection.

Simplify get_logger() to delegate to these new functions while keeping
its signature unchanged.

Signed-off-by: Major Hayden <major@redhat.com>

Author: major

src/constants.py

@@ -183,3 +183,5 @@
 LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR = "LIGHTSPEED_STACK_LOG_LEVEL"
 # Default log level when environment variable is not set
 DEFAULT_LOG_LEVEL = "INFO"
+# Default log format for plain-text logging in non-TTY environments
+DEFAULT_LOG_FORMAT = "%(asctime)s %(levelname)-8s %(name)s:%(lineno)d %(message)s"

src/log.py

@@ -6,7 +6,72 @@
 
 from rich.logging import RichHandler
 
-from constants import LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, DEFAULT_LOG_LEVEL
+from constants import (
+    LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR,
+    DEFAULT_LOG_LEVEL,
+    DEFAULT_LOG_FORMAT,
+)
+
+
+def resolve_log_level() -> int:
+    """
+    Resolve and validate the log level from environment variable.
+
+    Reads the LIGHTSPEED_STACK_LOG_LEVEL environment variable and validates
+    it against Python's logging module. If the environment variable is not set,
+    defaults to DEFAULT_LOG_LEVEL. If the value is invalid, logs a warning and
+    falls back to DEFAULT_LOG_LEVEL.
+
+    Parameters:
+        None
+
+    Returns:
+        int: A valid logging level constant (e.g., logging.INFO, logging.DEBUG).
+    """
+    level_str = os.environ.get(LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, DEFAULT_LOG_LEVEL)
+
+    # Validate the level string and convert to logging level constant
+    validated_level = getattr(logging, level_str.upper(), None)
+    if not isinstance(validated_level, int):
+        # Write directly to stderr instead of using a logger. This function is
+        # called at module-import time (before logging is configured), so routing
+        # through a logger produces inconsistent output depending on root-logger
+        # state.
+        print(
+            f"WARNING: Invalid log level '{level_str}', "
+            f"falling back to {DEFAULT_LOG_LEVEL}",
+            file=sys.stderr,
+        )
+        validated_level = getattr(logging, DEFAULT_LOG_LEVEL)
+
+    return validated_level
+
+
+def create_log_handler() -> logging.Handler:
+    """
+    Create and return a configured log handler based on TTY availability.
+
+    If stderr is connected to a terminal (TTY), returns a RichHandler for
+    rich-formatted console output. Otherwise, returns a StreamHandler with
+    plain-text formatting suitable for non-TTY environments (e.g., containers).
+
+    Parameters:
+        None
+
+    Returns:
+        logging.Handler: A configured handler instance (RichHandler or StreamHandler).
+    """
+    if sys.stderr.isatty():
+        # RichHandler's columnar layout assumes a real terminal.
+        # RichHandler handles its own formatting, so no formatter is set.
+        return RichHandler()
+
+    # In containers without a TTY, Rich falls back to 80 columns and
+    # the columns consume most of that width, leaving ~40 chars for the actual message.
+    # Tracebacks become nearly unreadable. Use a plain StreamHandler instead.
+    handler = logging.StreamHandler()
+    handler.setFormatter(logging.Formatter(DEFAULT_LOG_FORMAT))
+    return handler
 
 
 def get_logger(name: str) -> logging.Logger:
@@ -15,8 +80,8 @@ def get_logger(name: str) -> logging.Logger:
 
     The returned logger has its level set based on the LIGHTSPEED_STACK_LOG_LEVEL
     environment variable (defaults to INFO), its handlers replaced with a single
-    RichHandler for rich-formatted console output, and propagation to ancestor
-    loggers disabled.
+    handler (RichHandler for TTY or StreamHandler for non-TTY), and propagation
+    to ancestor loggers disabled.
 
     Parameters:
         name (str): Name of the logger to retrieve or create.
@@ -30,34 +95,7 @@ def get_logger(name: str) -> logging.Logger:
     if logger.handlers:
         return logger
 
-    # RichHandler's columnar layout (timestamp, level, right-aligned filename) assumes
-    # a real terminal. In containers without a TTY, Rich falls back to 80 columns and
-    # the columns consume most of that width, leaving ~40 chars for the actual message.
-    # Tracebacks become nearly unreadable. Use a plain StreamHandler when there's no TTY.
-    if sys.stderr.isatty():
-        logger.handlers = [RichHandler()]
-    else:
-        handler = logging.StreamHandler()
-        handler.setFormatter(
-            logging.Formatter(
-                "%(asctime)s %(levelname)-8s %(name)s:%(lineno)d %(message)s"
-            )
-        )
-        logger.handlers = [handler]
+    logger.handlers = [create_log_handler()]
     logger.propagate = False
-
-    # Read log level from environment variable with default fallback
-    level_str = os.environ.get(LIGHTSPEED_STACK_LOG_LEVEL_ENV_VAR, DEFAULT_LOG_LEVEL)
-
-    # Validate the level string and convert to logging level constant
-    validated_level = getattr(logging, level_str.upper(), None)
-    if not isinstance(validated_level, int):
-        logger.warning(
-            "Invalid log level '%s', falling back to %s",
-            level_str,
-            DEFAULT_LOG_LEVEL,
-        )
-        validated_level = getattr(logging, DEFAULT_LOG_LEVEL)
-
-    logger.setLevel(validated_level)
+    logger.setLevel(resolve_log_level())
     return logger