py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/structured_logging/config.py

@@ -0,0 +1,337 @@
+"""Configuration management for structured logging."""
+
+import os
+from typing import Any, cast
+
+from ..log_levels import LogLevel
+from .env import is_test_environment
+
+
+class LoggingConfig:
+    """Manages configuration for structured logging."""
+
+    # Singleton instance for consistent configuration across the application
+    _instance = None
+
+    def __new__(cls, config_dict: dict[str, Any] | None = None) -> "LoggingConfig":
+        """Create or return the singleton instance."""
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            # Initialize only once
+            cls._instance._initialize(config_dict)
+        elif config_dict:
+            # Update existing instance with new config if provided
+            cls._instance.update(config_dict)
+        return cls._instance
+
+    def _initialize(self, config_dict: dict[str, Any] | None = None) -> None:
+        """Initialize logging configuration.
+
+        Args:
+            config_dict: Optional dictionary with initial configuration.
+        """
+        self._config_functions = self._get_config_functions()
+        self._explicit_config = config_dict or {}
+        # Add configuration caching for better performance
+        self._cache: dict[str, Any] = {}
+        # Disable caching in test environment to prevent stale cache from mocks.
+        # is_test_environment covers plain pytest, xdist workers, and wl test's
+        # NON_INTERACTIVE escape hatch.
+        self._cache_enabled = not is_test_environment()
+
+    def _get_config_functions(self):
+        """Get configuration functions with fallbacks."""
+        try:
+            from ..config import get_config
+
+            return get_config
+        except ImportError:
+            # Fallback if config is not available
+            def config(key: str, default: Any = None) -> Any:
+                return default
+
+            return config
+
+    def _get_environment(self) -> str:
+        """Get current environment."""
+        try:
+            from ..config import get_config
+
+            return cast("str", get_config("environment", "development"))
+        except ImportError:
+            # Fallback to environment variable
+            return os.environ.get("WL_ENVIRONMENT", "development")
+
+    def get_environment_specific_config(self, key: str, default: Any = None) -> Any:
+        """Get environment-specific configuration."""
+        environment = self._get_environment()
+
+        # Try environment-specific key first
+        env_specific_key = f"{key}_{environment}"
+        value = self._config_functions(env_specific_key)
+        if value is not None:
+            return value
+
+        # Fallback to regular key
+        return self._config_functions(key, default)
+
+    def get_log_level(self, min_level: int | None = None) -> int:
+        """
+        Get log level from config or parameter.
+
+        Args:
+            min_level: Explicit log level. If None, get from config.
+
+        Returns:
+            Log level as integer.
+        """
+        if min_level is not None:
+            return min_level
+
+        # Never cache in test environment to prevent stale values from mocks.
+        # is_test_environment covers plain pytest, xdist workers, and wl test's
+        # NON_INTERACTIVE escape hatch.
+        if is_test_environment():
+            cache_enabled = False
+            # Clear any existing cached values from previous tests
+            self._cache.clear()
+        else:
+            cache_enabled = self._cache_enabled
+
+        # Check cache first
+        cache_key = f"log_level_{self._get_environment()}"
+        if cache_enabled and cache_key in self._cache:
+            return cast("int", self._cache[cache_key])
+
+        # Check explicit config first
+        if "log_level" in self._explicit_config:
+            level_value = self._explicit_config["log_level"]
+        else:
+            # Get environment-specific log level
+            level_value = self.get_environment_specific_config("log_level", "INFO")
+
+        # Handle both string and numeric log levels
+        if isinstance(level_value, str):
+            level_name = level_value.upper()
+            log_level = getattr(LogLevel, level_name, LogLevel.INFO)
+        else:
+            log_level = level_value
+
+        # Cache the result
+        if cache_enabled:
+            self._cache[cache_key] = log_level
+
+        return log_level
+
+    def get_console_settings(self) -> tuple[bool, str]:
+        """
+        Get console output settings.
+
+        Returns:
+            Tuple of (enable_console, console_format).
+        """
+        # Check explicit config first
+        if "log_console" in self._explicit_config:
+            enable_console = self._explicit_config["log_console"]
+        else:
+            # Get environment-specific console setting
+            enable_console = self.get_environment_specific_config("log_console", False)
+
+        if "log_console_format" in self._explicit_config:
+            console_format = self._explicit_config["log_console_format"]
+        else:
+            # 首先尝试从环境变量获取
+            env_value = os.environ.get("WL_LOG_CONSOLE_FORMAT")
+            if env_value:
+                console_format = env_value
+            else:
+                # Get environment-specific console format
+                console_format = self.get_environment_specific_config(
+                    "log_console_format", "colored"
+                )
+
+        return enable_console, console_format
+
+    def get_file_format_settings(self) -> str:
+        """
+        Get log file format setting.
+
+        Returns:
+            Log file format ('human' or 'json').
+        """
+        # Check explicit config first
+        if "log_file_format" in self._explicit_config:
+            return cast("str", self._explicit_config["log_file_format"])
+        else:
+            # Get environment-specific file format
+            return cast(
+                "str", self.get_environment_specific_config("log_file_format", "human")
+            )
+
+    def get_log_file(self, log_file: str | None = None) -> str | None:
+        """
+        Get log file path.
+
+        Args:
+            log_file: Explicit log file path. If None, get from config.
+
+        Returns:
+            Log file path or None.
+        """
+        if log_file is not None:
+            return log_file
+
+        # Check explicit config first
+        if "log_file" in self._explicit_config:
+            return cast("str | None", self._explicit_config["log_file"])
+        else:
+            return None
+
+    def get_rotation_settings(self) -> dict[str, Any]:
+        """
+        Get log rotation settings.
+
+        Returns:
+            Dictionary with rotation settings.
+        """
+        # Check explicit config first
+        if "rotation" in self._explicit_config:
+            return cast("dict[str, Any]", self._explicit_config["rotation"])
+        else:
+            return {
+                "max_size": self._config_functions("log_max_size", 10 * 1024 * 1024),
+                "max_backups": self._config_functions("log_max_backups", 5),
+                "rotate_days": self._config_functions("log_rotate_days", 7),
+            }
+
+    @classmethod
+    def from_dict(cls, config_dict: dict[str, Any]) -> "LoggingConfig":
+        """
+        Create LoggingConfig from dictionary.
+
+        Args:
+            config_dict: Dictionary with configuration.
+
+        Returns:
+            LoggingConfig instance.
+        """
+        return cls(config_dict)
+
+    @classmethod
+    def from_env(cls, prefix: str = "WL_") -> "LoggingConfig":
+        """
+        Create LoggingConfig from environment variables.
+
+        Args:
+            prefix: Prefix for environment variables.
+
+        Returns:
+            LoggingConfig instance.
+        """
+        config_dict: dict[str, Any] = {}
+
+        # Map environment variables to config keys
+        env_mapping = {
+            f"{prefix}LOG_LEVEL": "log_level",
+            f"{prefix}LOG_CONSOLE": "log_console",
+            f"{prefix}LOG_CONSOLE_FORMAT": "log_console_format",
+            f"{prefix}LOG_FILE": "log_file",
+            f"{prefix}LOG_FILE_FORMAT": "log_file_format",
+            f"{prefix}LOG_MAX_SIZE": "log_max_size",
+            f"{prefix}LOG_MAX_BACKUPS": "log_max_backups",
+            f"{prefix}LOG_ROTATE_DAYS": "log_rotate_days",
+        }
+
+        for env_key, config_key in env_mapping.items():
+            if env_key in os.environ:
+                raw_value = os.environ[env_key]
+                # Convert boolean values
+                if raw_value.lower() in ("true", "false"):
+                    config_dict[config_key] = raw_value.lower() == "true"
+                # Convert numeric values
+                elif raw_value.isdigit():
+                    config_dict[config_key] = int(raw_value)
+                else:
+                    config_dict[config_key] = raw_value
+
+        # Handle rotation settings
+        rotation_keys = ["log_max_size", "log_max_backups", "log_rotate_days"]
+        rotation_settings: dict[str, Any] = {}
+        for key in rotation_keys:
+            if key in config_dict:
+                rotation_settings[key.replace("log_", "")] = config_dict.pop(key)
+
+        if rotation_settings:
+            config_dict["rotation"] = rotation_settings
+
+        return cls(config_dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """
+        Convert configuration to dictionary.
+
+        Returns:
+            Dictionary with configuration.
+        """
+        config_dict: dict[str, Any] = {
+            "log_level": LogLevel.get_name(self.get_log_level()),
+            "log_file": self.get_log_file(),
+        }
+
+        console_enabled, console_format = self.get_console_settings()
+        config_dict["log_console"] = console_enabled
+        config_dict["log_console_format"] = console_format
+
+        config_dict["log_file_format"] = self.get_file_format_settings()
+        config_dict["rotation"] = self.get_rotation_settings()
+
+        return config_dict
+
+    def update(self, config_dict: dict[str, Any]) -> None:
+        """
+        Update configuration with dictionary.
+
+        Args:
+            config_dict: Dictionary with configuration updates.
+        """
+        self._explicit_config.update(config_dict)
+        # Clear cache when config is updated
+        self._clear_cache()
+
+    def _clear_cache(self) -> None:
+        """
+        Clear configuration cache.
+        """
+        self._cache.clear()
+
+    def set_cache_enabled(self, enabled: bool) -> None:
+        """
+        Enable or disable configuration caching.
+
+        Args:
+            enabled: Whether to enable caching.
+        """
+        self._cache_enabled = enabled
+        if not enabled:
+            self._clear_cache()
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """
+        Get configuration value.
+
+        Args:
+            key: Configuration key.
+            default: Default value if key not found.
+
+        Returns:
+            Configuration value or default.
+        """
+        if key in self._explicit_config:
+            return self._explicit_config[key]
+        else:
+            return self._config_functions(key, default)
+
+    @classmethod
+    def reset(cls) -> None:
+        """Reset the singleton instance."""
+        cls._instance = None

wl_cli/utils/structured_logging/core.py

@@ -0,0 +1,177 @@
+"""Core logging functionality for WL Commands.
+
+This module serves as the entry point for the modularized structured logging functionality.
+主要功能委托给专门的模块以获得更好的组织结构。
+"""
+
+from typing import Any
+
+from ..log_rotators import LogRotator
+from .config import LoggingConfig
+from .filtering import LogLevelChecker
+from .formatters import LogFormatter
+from .handlers import LogHandler
+from .logger import StructuredLoggerCore
+
+
+# Backward compatibility: re-export all the main components
+class StructuredLogger(StructuredLoggerCore):
+    """A structured logger that outputs JSON formatted logs."""
+
+    def __init__(
+        self, name: str, min_level: int | None = None, log_file: str | None = None
+    ) -> None:
+        """
+        Initialize structured logger.
+
+        Args:
+            name (str): Logger name.
+            min_level (int, optional): Minimum log level. If None, read from config.
+            log_file (Optional[str]): Log file path. If None, read from config.
+        """
+        super().__init__(name, min_level, log_file)
+
+        # Add backward compatibility properties
+        self._min_level = self.filter.min_level
+        self._log_file = self.handler.log_file
+        self.log_rotator = self.handler.log_rotator
+        self._enable_console = self.handler.enable_console
+        self.console_format = self.handler.console_format
+        self.log_file_format = self.handler.log_file_format
+        self.filters = self.filter.filters
+
+    @property
+    def min_level(self):
+        """Get minimum log level."""
+        return self._min_level
+
+    @min_level.setter
+    def min_level(self, value):
+        """Set minimum log level."""
+        self._min_level = value
+        self.filter.min_level = value
+
+    @property
+    def log_file(self):
+        """Get log file path."""
+        return self._log_file
+
+    @log_file.setter
+    def log_file(self, value):
+        """Set log file path."""
+        self._log_file = value
+        self.handler.log_file = value
+
+    @property
+    def enable_console(self):
+        """Get console output enabled status."""
+        return self._enable_console
+
+    @enable_console.setter
+    def enable_console(self, value):
+        """Set console output enabled status."""
+        self._enable_console = value
+        self.handler.enable_console = value
+
+    # The five verb overrides used to live here, each re-popping `message` and
+    # `lang` before calling _log.  That duplication is gone (#136): _log now
+    # normalizes those kwargs once for every verb, so the inherited
+    # StructuredLoggerCore.debug/info/warning/error/critical are used directly.
+
+    # Compatibility methods for backward compatibility with tests
+    def _write_log(self, message: str) -> None:
+        """Write log message to appropriate output (compatibility method)."""
+        import json
+
+        # Handle file writing directly for backward compatibility with tests
+        if self.log_file:
+            # Handle log rotation directly
+            if self.log_rotator and self.log_rotator.should_rotate():
+                self.log_rotator.do_rotate()
+
+            try:
+                with open(self.log_file, "a", encoding="utf-8") as f:
+                    f.write(message + "\n")
+            except OSError:
+                # Ignore file write errors
+                pass
+
+        # Handle console output directly for backward compatibility with tests
+        if self.enable_console:
+            import sys
+
+            try:
+                # Format message for console based on console_format
+                console_message = message
+                if self.console_format != "json":
+                    # Try to parse JSON message and reformat as human-readable
+                    try:
+                        log_record = json.loads(message)
+                        console_message = self.formatter.format_console_log(log_record)
+                    except (json.JSONDecodeError, TypeError):
+                        # Fallback to raw message if parsing fails
+                        pass
+
+                # Determine output stream based on log level in message
+                if "CRITICAL" in message or "ERROR" in message:
+                    print(console_message, file=sys.stderr)
+                else:
+                    print(console_message, file=sys.stdout)
+            except OSError:
+                # Ignore console write errors
+                pass
+
+    def _write_log_with_rotation(self, message: str) -> None:
+        """Write log message with rotation (compatibility method)."""
+        self._write_log(message)
+
+    def _format_human_log(self, record: dict[str, Any]) -> str:
+        """Format log record for human-readable file output (compatibility method)."""
+        return self.formatter.format_human_log(record)
+
+    def _format_console_log(self, record: dict[str, Any]) -> str:
+        """Format log record for console output (compatibility method)."""
+        return self.formatter.format_console_log(record)
+
+    # Property accessors for backward compatibility
+    @property
+    def _COLORS(
+        self,
+    ) -> dict[str, str]:
+        """Get color codes (compatibility property)."""
+        return self.formatter._COLORS
+
+    @_COLORS.setter
+    def _COLORS(self, value: dict[str, str]) -> None:
+        """Set color codes (compatibility property)."""
+        self.formatter._COLORS = value
+
+    def _should_log(self, level: int, **kwargs) -> bool:
+        """Check if log should be processed based on level and filters (compatibility method)."""
+        return self.filter.should_log(level, **kwargs)
+
+    def _get_level_name(self, level: int) -> str:
+        """Convert level number to name (compatibility method)."""
+        return self.filter.get_level_name(level)
+
+    @property
+    def filters(self):
+        """Get filters for backward compatibility."""
+        return self.filter.filters
+
+    @filters.setter
+    def filters(self, value):
+        """Set filters for backward compatibility."""
+        self.filter.filters = value
+
+
+# Re-export classes for advanced usage
+__all__ = [
+    "StructuredLogger",
+    "StructuredLoggerCore",
+    "LoggingConfig",
+    "LogLevelChecker",
+    "LogFormatter",
+    "LogHandler",
+    "LogRotator",
+]

wl_cli/utils/structured_logging/env.py

@@ -0,0 +1,56 @@
+"""Test-environment predicates shared across the logging stack (#136, #142).
+
+"Are we under pytest? Is this a performance test?" used to be answered
+independently at every site that cared: the emit funnel
+(:mod:`wl_cli.utils.logging`), several places downstream in
+:class:`~wl_cli.utils.structured_logging.logger.StructuredLoggerCore`, and the
+logging config / handler internals.  They all now consult this module, so the
+judgment is written exactly once and a change to it cannot drift between the
+callers.
+"""
+
+import os
+
+__all__ = [
+    "is_performance_test",
+    "is_pytest",
+    "is_test_environment",
+    "pytest_test_name",
+]
+
+
+def pytest_test_name() -> str:
+    """Return pytest's per-test node id, or ``""`` outside a running test."""
+    return os.environ.get("PYTEST_CURRENT_TEST", "")
+
+
+def is_pytest() -> bool:
+    """True while pytest's per-test hook is active (plain or xdist worker)."""
+    return os.environ.get("PYTEST_CURRENT_TEST") is not None
+
+
+def is_performance_test() -> bool:
+    """True for the throughput suites that deliberately skip log I/O.
+
+    Matches any node id whose file / class / function mentions ``performance``;
+    that covers both ``test_log_performance.py`` and
+    ``test_logging_performance.py``.  This is a superset of the narrower
+    predicate the funnel used to carry, and is the one the logger already used
+    to suppress output, so routing the funnel through it changes nothing
+    observable.
+    """
+    return "performance" in pytest_test_name().lower()
+
+
+def is_test_environment() -> bool:
+    """Broad "an automated/test run" gate used for logger defaults.
+
+    Covers pytest (plain and xdist) plus the ``NON_INTERACTIVE`` escape hatch
+    that ``wl test`` sets, and drives default level / file / console choices.
+    """
+    return (
+        is_pytest()
+        or os.environ.get("PYTEST_XDIST_WORKER") is not None
+        or os.environ.get("PYTEST_XDIST_NUM_WORKERS") is not None
+        or os.environ.get("NON_INTERACTIVE") is not None
+    )

wl_cli/utils/structured_logging/filtering.py

@@ -0,0 +1,75 @@
+"""Filtering and level checking for structured logging."""
+
+import datetime
+from collections.abc import Callable
+from typing import Any
+
+from ..log_levels import LogLevel
+
+
+class LogLevelChecker:
+    """Manages filtering and level checking for structured logging."""
+
+    def __init__(self, min_level: int) -> None:
+        """
+        Initialize log level checker.
+
+        Args:
+            min_level: Minimum log level.
+        """
+        self.min_level = min_level
+        self.filters: list[Callable[[dict[str, Any]], bool]] = []
+
+    def add_filter(self, filter_func: Callable[[dict[str, Any]], bool]) -> None:
+        """
+        Add a filter function.
+
+        Args:
+            filter_func: Function that takes a log record and returns bool.
+        """
+        self.filters.append(filter_func)
+
+    def should_log(self, level: int, **kwargs) -> bool:
+        """
+        Check if log should be processed based on level and filters.
+
+        Args:
+            level: Log level.
+            **kwargs: Log record fields.
+
+        Returns:
+            True if log should be processed.
+        """
+        if level < self.min_level:
+            return False
+
+        # Only create record if level is sufficient
+        if not self.filters:
+            return True
+
+        # Create record with timestamp only if there are filters to apply
+        record = {
+            "level": level,
+            "timestamp": datetime.datetime.now().isoformat(),
+            **kwargs,
+        }
+        return all(f(record) for f in self.filters)
+
+    def get_level_name(self, level: int) -> str:
+        """
+        Convert level number to name.
+
+        Args:
+            level: Log level number.
+
+        Returns:
+            Log level name as string.
+        """
+        level_names = {
+            LogLevel.DEBUG: "DEBUG",
+            LogLevel.INFO: "INFO",
+            LogLevel.WARNING: "WARNING",
+            LogLevel.ERROR: "ERROR",
+            LogLevel.CRITICAL: "CRITICAL",
+        }
+        return level_names.get(level, "UNKNOWN")

wl_cli/utils/structured_logging/filters.py

@@ -0,0 +1,55 @@
+"""Log filters for WL Commands."""
+
+from typing import Any
+
+
+class LogFilter:
+    """Base class for log filters."""
+
+    def __call__(self, record: dict[str, Any]) -> bool:
+        """Determine if the log record should be processed."""
+        raise NotImplementedError("Subclasses must implement __call__ method.")
+
+
+class LevelFilter(LogFilter):
+    """Filter logs based on log level."""
+
+    def __init__(self, min_level: int, max_level: int | None = None) -> None:
+        """
+        Initialize level filter.
+
+        Args:
+            min_level (int): Minimum log level to include.
+            max_level (Optional[int]): Maximum log level to include.
+        """
+        self.min_level = min_level
+        self.max_level = max_level
+
+    def __call__(self, record: dict[str, Any]) -> bool:
+        """Check if log record level is within specified range."""
+        level = record.get("level", 0)
+        if level < self.min_level:
+            return False
+        if self.max_level is not None and level > self.max_level:
+            return False
+        return True
+
+
+class KeyValueFilter(LogFilter):
+    """Filter logs based on key-value pairs."""
+
+    def __init__(self, **kwargs) -> None:
+        """
+        Initialize key-value filter.
+
+        Args:
+            **kwargs: Key-value pairs to match in log records.
+        """
+        self.filters = kwargs
+
+    def __call__(self, record: dict[str, Any]) -> bool:
+        """Check if log record contains all specified key-value pairs."""
+        for key, value in self.filters.items():
+            if record.get(key) != value:
+                return False
+        return True