py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/structured_logging/logger.py

@@ -0,0 +1,354 @@
+"""Core logger implementation for structured logging."""
+
+import os
+from typing import Any
+
+from ..log_levels import LogLevel
+from ..log_rotators import LogRotator
+from .config import LoggingConfig
+from .env import is_performance_test, is_pytest, is_test_environment
+from .filtering import LogLevelChecker
+from .formatters import LogFormatter
+from .handlers import LogHandler
+
+
+class StructuredLoggerCore:
+    """Core structured logger implementation."""
+
+    def __init__(
+        self, name: str, min_level: int | None = None, log_file: str | None = None
+    ) -> None:
+        """
+        Initialize structured logger core.
+
+        Args:
+            name: Logger name.
+            min_level: Minimum log level.
+            log_file: Log file path.
+        """
+        self.name = name
+        self.config = LoggingConfig()
+
+        # One judgment for the whole constructor: are we in an automated run?
+        # The three default-picking blocks below all ask the same question, so
+        # it is answered once here (see structured_logging.env).
+        is_any_test = is_test_environment()
+
+        # In test environment, force min_level to INFO to ensure test messages get logged
+        # This overrides any configuration that might filter out test messages
+        if is_any_test and min_level is None:
+            # Force INFO level in tests so info messages are not filtered out
+            min_level = LogLevel.INFO
+
+        self.filter = LogLevelChecker(self.config.get_log_level(min_level))
+        self.formatter = LogFormatter()
+
+        # Context management
+        self.context_stack: list[dict[str, Any]] = []
+
+        # Get log file from config if not provided
+        # If log_file is explicitly None, we respect that and don't use config value
+        actual_log_file = log_file
+        if actual_log_file is None:
+            if is_any_test:
+                # In test environment, default to None to avoid file system operations
+                actual_log_file = None
+            else:
+                # Get from config if log_file is None
+                config_log_file = self.config.get_log_file()
+                # Only use config value if it's not an empty string
+                if config_log_file:
+                    actual_log_file = config_log_file
+
+        # Initialize log rotator if log file is specified
+        rotation_settings = self.config.get_rotation_settings()
+        self.log_rotator: LogRotator | None = (
+            LogRotator(
+                actual_log_file,
+                max_size=rotation_settings["max_size"],
+                max_backups=rotation_settings["max_backups"],
+                rotate_days=rotation_settings["rotate_days"],
+            )
+            if actual_log_file
+            else None
+        )
+
+        # Get console settings
+        enable_console, console_format = self.config.get_console_settings()
+        # Ensure console output is enabled by default for better out-of-the-box experience
+        # This overrides config setting to maintain backward compatibility
+        # 1. When in test environment (any pytest or wl test), always enable console
+        #    to allow tests to capture print output for assertions
+        # 2. When log_file is None (the default for tests), always enable console
+        #    because there's no other output destination
+        # In any test environment, always force enable_console to True
+        # This ensures tests can capture print output for assertions
+        if is_any_test or actual_log_file is None:
+            enable_console = True
+        file_format = self.config.get_file_format_settings()
+
+        self.handler = LogHandler(
+            log_file=actual_log_file,
+            log_rotator=self.log_rotator,
+            enable_console=enable_console,
+            console_format=console_format,
+            log_file_format=file_format,
+        )
+
+    def push_context(self, **context) -> None:
+        """
+        Push context to the context stack.
+
+        Args:
+            **context: Context key-value pairs.
+        """
+        self.context_stack.append(context)
+
+    def pop_context(self) -> dict | None:
+        """
+        Pop context from the context stack.
+
+        Returns:
+            The popped context or None if stack is empty.
+        """
+        if self.context_stack:
+            return self.context_stack.pop()
+        return None
+
+    def clear_context(self) -> None:
+        """
+        Clear all context from the context stack.
+        """
+        self.context_stack.clear()
+
+    def get_merged_context(self) -> dict:
+        """
+        Merge all contexts in the stack.
+
+        Returns:
+            Merged context dictionary.
+        """
+        merged = {}
+        for context in self.context_stack:
+            merged.update(context)
+        return merged
+
+    def add_filter(self, filter_func) -> None:
+        """Add a filter function."""
+        self.filter.add_filter(filter_func)
+
+    def _build_record(self, level: int, message: str, **kwargs) -> dict[str, Any]:
+        """
+        Build log record with consistent field naming.
+
+        Args:
+            level: Log level.
+            message: Log message.
+            **kwargs: Additional fields.
+
+        Returns:
+            Log record dictionary.
+        """
+        import datetime
+
+        # No pytest re-check here: _log routes every pytest call down its
+        # minimal-record branch, so this full path only ever runs outside
+        # pytest and the timestamp is always "now".
+        # Base record with consistent field naming (using underscore naming convention)
+        record = {
+            "logger_name": self.name,
+            "level": level,
+            "level_name": self.filter.get_level_name(level),
+            "timestamp": datetime.datetime.now().isoformat(),
+            "message": message,
+        }
+
+        # Only process additional fields if needed
+        if kwargs or self.context_stack:
+            normalized_kwargs = self._normalize_kwargs(kwargs)
+            self._add_caller_info(record, level)
+            all_context = self._merge_context(normalized_kwargs)
+            self._add_context_to_record(record, level, all_context)
+
+        return record
+
+    def _normalize_kwargs(self, kwargs: dict[str, Any]) -> dict[str, Any]:
+        """标准化关键字参数的命名"""
+        normalized_kwargs = {}
+        for key, value in kwargs.items():
+            # Convert camelCase to snake_case for consistency
+            normalized_key = ""
+            for char in key:
+                if char.isupper() and normalized_key:
+                    normalized_key += "_" + char.lower()
+                else:
+                    normalized_key += char.lower()
+            normalized_kwargs[normalized_key] = value
+        return normalized_kwargs
+
+    def _add_caller_info(self, record: dict[str, Any], level: int) -> None:
+        """添加调用者信息"""
+        if level in (LogLevel.DEBUG, LogLevel.ERROR, LogLevel.CRITICAL):
+            # Only production suppresses caller info. No pytest re-check: this
+            # runs only from _build_record, which pytest calls never reach
+            # (see _log).
+            is_production = os.environ.get("WL_ENVIRONMENT") == "production"
+            if not is_production:
+                import inspect
+
+                try:
+                    current_frame = inspect.currentframe()
+                    if current_frame:
+                        caller_frame = current_frame.f_back
+                        if caller_frame:
+                            caller_frame = (
+                                caller_frame.f_back
+                            )  # Skip this method and _log
+                            if caller_frame:
+                                caller_info = inspect.getframeinfo(caller_frame)
+                                record.update(
+                                    {
+                                        "module": os.path.basename(
+                                            caller_info.filename
+                                        ).split(".")[0],
+                                        "function": caller_info.function,
+                                        "line": caller_info.lineno,
+                                    }
+                                )
+                except Exception:
+                    # Skip caller info if there's any error
+                    pass
+
+    def _merge_context(self, normalized_kwargs: dict[str, Any]) -> dict[str, Any]:
+        """合并上下文信息"""
+        # Get merged context from context stack
+        stack_context = self.get_merged_context()
+        # Merge with explicit kwargs
+        return {**stack_context, **normalized_kwargs}
+
+    def _add_context_to_record(
+        self, record: dict[str, Any], level: int, all_context: dict[str, Any]
+    ) -> None:
+        """将上下文信息添加到记录中"""
+        if all_context:
+            # For debug level, include full context
+            if level == LogLevel.DEBUG:
+                record["context"] = all_context
+            else:
+                # For other levels, include essential context directly
+                essential_keys = [
+                    "module",
+                    "function",
+                    "line",
+                    "error",
+                    "traceback",
+                    "duration",
+                    "user",
+                    "action",
+                    "result",
+                    "lang",
+                ]
+                for key, value in all_context.items():
+                    if key in essential_keys:
+                        record[key] = value
+
+    def _log(self, level: int, message: str, **kwargs) -> None:
+        """
+        Internal logging method with performance optimizations.
+
+        Args:
+            level: Log level.
+            message: Log message.
+            **kwargs: Additional fields.
+        """
+        try:
+            # The min_level guard is deliberately *not* re-checked here: it
+            # already lives in should_log below, whose very first check is
+            # exactly `level < min_level`.  Leaving the guard in should_log
+            # alone keeps direct `logger.info(...)` callers filtered (the
+            # logger's own contract) without judging the same level twice.
+            #
+            # Strip the transport-only kwargs once, at the logger's single
+            # entry point: `lang` was already consumed by the emit funnel's
+            # language gate upstream, and `message` cannot survive the public
+            # signature's binding -- neither belongs in the emitted record.
+            kwargs.pop("message", None)
+            kwargs.pop("lang", None)
+            if not self.filter.should_log(level, message=message, **kwargs):
+                return
+
+            # Under pytest every call takes a minimal route; the perf suites go
+            # one step further and skip the write entirely so throughput
+            # measurements aren't distorted by I/O.
+            if is_pytest():
+                if is_performance_test():
+                    return
+                # For other tests, still call write_log to maintain test compatibility
+                record = {
+                    "logger_name": self.name,
+                    "level": level,
+                    "level_name": self.filter.get_level_name(level),
+                    "timestamp": "2026-01-01T00:00:00.000000",
+                    "message": message,
+                }
+                self.handler.write_log(record)
+                return
+
+            # Build log record
+            record = self._build_record(level, message, **kwargs)
+
+            # Write log with handler
+            self.handler.write_log(record)
+        except TypeError as e:
+            # Special handling for message parameter conflict
+            if "got multiple values for argument 'message'" in str(e):
+                # This happens when message is passed both as a positional argument and a keyword argument
+                # Rebuild kwargs without message and try again
+                kwargs.pop("message", None)
+                try:
+                    # Build log record
+                    record = self._build_record(level, message, **kwargs)
+
+                    # Write log with handler
+                    self.handler.write_log(record)
+                except Exception as e2:
+                    # Ensure logging system doesn't crash due to internal errors
+                    # We can't log the error here as it would cause recursion
+                    import sys
+
+                    print(f"Logging system error: {e2}", file=sys.stderr)
+                    pass
+            else:
+                # Ensure logging system doesn't crash due to internal errors
+                # We can't log the error here as it would cause recursion
+                import sys
+
+                print(f"Logging system error: {e}", file=sys.stderr)
+                pass
+        except Exception as e:
+            # Ensure logging system doesn't crash due to internal errors
+            # We can't log the error here as it would cause recursion
+            import sys
+
+            print(f"Logging system error: {e}", file=sys.stderr)
+            pass
+
+    def debug(self, message: str, **kwargs) -> None:
+        """Log debug message."""
+        self._log(LogLevel.DEBUG, message, **kwargs)
+
+    def info(self, message: str, **kwargs) -> None:
+        """Log info message."""
+        self._log(LogLevel.INFO, message, **kwargs)
+
+    def warning(self, message: str, **kwargs) -> None:
+        """Log warning message."""
+        self._log(LogLevel.WARNING, message, **kwargs)
+
+    def error(self, message: str, **kwargs) -> None:
+        """Log error message."""
+        self._log(LogLevel.ERROR, message, **kwargs)
+
+    def critical(self, message: str, **kwargs) -> None:
+        """Log critical message."""
+        self._log(LogLevel.CRITICAL, message, **kwargs)

wl_cli/utils/subprocess.py

@@ -0,0 +1,71 @@
+"""
+Subprocess utilities for WL Commands.
+"""
+
+import os
+import subprocess
+
+from ..exceptions import CommandError
+from .platform_adapter import PlatformAdapter
+
+
+def run_command(
+    command, env=None, capture_output=False, text=True, shell=False
+) -> subprocess.CompletedProcess:
+    """
+    Run a command with subprocess.run and handle errors.
+
+    Args:
+        command (list): Command to run.
+        env (dict, optional): Environment variables. Defaults to None.
+        capture_output (bool, optional): Whether to capture output. Defaults to False.
+        text (bool, optional): Whether to return text output. Defaults to True.
+        shell (bool, optional): Whether to run the command in a shell. Defaults to False.
+
+    Returns:
+        subprocess.CompletedProcess: Result of the command.
+
+    Raises:
+        CommandError: If the command fails.
+    """
+    # Validate command parameter
+    if command is None:
+        raise CommandError("Command cannot be None")
+
+    if not isinstance(command, list):
+        raise CommandError("Command must be a list")
+
+    if len(command) == 0:
+        raise CommandError("Command list cannot be empty")
+
+    # Validate each command argument
+    for arg in command:
+        if not isinstance(arg, str):
+            raise CommandError(
+                f"Command argument must be a string, got {type(arg).__name__}"
+            )
+
+    # Prepare environment variables
+    environment = env or os.environ.copy()
+
+    # Fix encoding issues on Windows
+    if PlatformAdapter.is_windows():
+        # Set environment variables to ensure proper UTF-8 handling
+        environment["PYTHONIOENCODING"] = "utf-8"
+        environment["PYTHONLEGACYWINDOWSFSENCODING"] = "1"
+
+    try:
+        return subprocess.run(
+            command,
+            check=True,
+            env=environment,
+            capture_output=capture_output,
+            text=text,
+            shell=shell,
+            # Explicitly set encoding for Windows systems
+            encoding="utf-8" if text else None,
+        )
+    except subprocess.CalledProcessError as e:
+        raise CommandError(f"Command failed: {e}")
+    except FileNotFoundError as e:
+        raise CommandError(f"Command not found: {e}")

wl_cli/utils/subprocess_utils.py

@@ -0,0 +1,260 @@
+"""Unified subprocess execution utilities for WL Commands."""
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from .file_operations import get_file_operations
+from .platform_adapter import PlatformAdapter
+from .uv_tool import (
+    get_direct_command,
+    get_uv_tool_env,
+    is_running_in_uv_tool,
+    should_use_direct_execution,
+)
+
+
+class SubprocessResult:
+    """Result of a subprocess execution."""
+
+    def __init__(
+        self,
+        returncode: int,
+        stdout: str,
+        stderr: str,
+        launch_error: str | None = None,
+        timed_out: bool = False,
+    ):
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+        #: Set whenever the run **raised instead of returning a child's result**
+        #: -- i.e. the ``except`` arm of
+        #: :meth:`SubprocessExecutor._execute_command`, which catches every
+        #: ``Exception``. In practice that is an ``OSError`` (an executable that
+        #: cannot be started), but not only: a malformed ``env`` raises
+        #: ``ValueError``, an undecodable output stream ``UnicodeDecodeError``,
+        #: and both land here too -- as does a deadline expiry's
+        #: ``subprocess.TimeoutExpired`` (see :attr:`timed_out`). Above all the
+        #: field is the *discriminator*, never the sign of ``returncode``:
+        #: ``subprocess`` reports a *signalled* child as ``-signum``, so SIGHUP
+        #: (``-1``) collides with the ``-1`` sentinel this arm returns (issue
+        #: #100 / review F1). Callers must ask this field, not ``returncode < 0``.
+        #: (The earlier "only on the ``OSError`` path" wording was never true --
+        #: ticket #101, N1.)
+        self.launch_error = launch_error
+        #: ``True`` when the caller's deadline expired before the child finished.
+        #: Such a run keeps ``launch_error`` set as well -- it never returned a
+        #: child's result -- so ``was_signalled`` stays ``False``: the timeout
+        #: machinery killed the child, which a caller must not read as "ran and
+        #: was signalled". This flag is the one discriminator between an expiry
+        #: and a launch failure, whose sentinel shares the ``-1`` returncode
+        #: (#184).
+        self.timed_out = timed_out
+
+    @property
+    def success(self) -> bool:
+        """Check if the subprocess execution was successful."""
+        return self.returncode == 0
+
+    @property
+    def was_signalled(self) -> bool:
+        """Whether the child ran and was then killed by a signal (``-signum``).
+
+        Distinct from "could not be launched": SIGHUP is ``-1``, which would
+        otherwise be indistinguishable from the launch-failure sentinel.
+        """
+        return self.launch_error is None and self.returncode < 0
+
+
+class SubprocessExecutor:
+    """Unified subprocess executor with caching and async capabilities."""
+
+    def __init__(self):
+        self._command_cache: dict[str, SubprocessResult] = {}
+        self._file_ops = get_file_operations()
+
+    def _prepare_environment(self, env: dict[str, str] | None = None) -> dict[str, str]:
+        """Prepare the environment variables for subprocess execution."""
+        if is_running_in_uv_tool():
+            # Start with UV Tool environment
+            uv_env = get_uv_tool_env()
+            # Update with user-provided environment if any
+            if env is not None:
+                uv_env.update(env)
+            environment = uv_env
+        else:
+            # Use user-provided environment or system environment
+            environment = env.copy() if env is not None else os.environ.copy()
+
+        # Fix encoding issues on Windows
+        if PlatformAdapter.is_windows():
+            environment["PYTHONIOENCODING"] = "utf-8"
+            environment["PYTHONLEGACYWINDOWSFSENCODING"] = "1"
+
+        return environment
+
+    def _prepare_cwd(self, cwd: Path | None = None) -> Path | None:
+        """Prepare the current working directory for subprocess execution."""
+        safe_cwd = cwd
+        if safe_cwd is None and is_running_in_uv_tool():
+            try:
+                safe_cwd = Path.cwd()
+            except FileNotFoundError:
+                safe_cwd = None
+        return safe_cwd
+
+    def subprocess_path(self) -> str | None:
+        """The ``PATH`` this executor's subprocesses resolve bare tokens against.
+
+        Not necessarily this process' own ``PATH``: :meth:`_prepare_environment`
+        rewrites it for uv-tool runs (``get_uv_tool_env`` prepends
+        ``UV_TOOL_DIR``). A caller that has to judge the *subjects* the executor
+        will actually run -- ``wl gate``'s preflight resolves ``ruff`` /
+        ``mypy`` / ``wl`` before handing them to it -- must ask here rather than
+        probe ``os.environ`` itself, or it judges a different PATH than the one
+        that executes: a chain the child could have run gets refused as an
+        environment gap (review F1 residual).
+        """
+        return self._prepare_environment().get("PATH")
+
+    def _execute_command(
+        self,
+        command: list[str],
+        env: dict[str, str],
+        cwd: Path | None,
+        quiet: bool,
+        timeout: float | None = None,
+    ) -> SubprocessResult:
+        """Execute a command and return the result.
+
+        ``timeout`` is opt-in and forwarded only when the caller sets one. The
+        commands this executor runs for production (``cargo build``, the test
+        runner, lint/fix passes) are legitimately long, so a default deadline
+        here would turn slow-but-healthy work into failures; only callers that
+        know their command is a *quick probe* should pass one (#184).
+        """
+        # Keeping the unlimited call byte-for-byte what it always was: the
+        # keyword is added only when a deadline was asked for.
+        deadline: dict[str, Any] = {} if timeout is None else {"timeout": timeout}
+        try:
+            if quiet:
+                # Capture output to suppress it
+                result = subprocess.run(
+                    command,
+                    env=env,
+                    cwd=cwd,
+                    capture_output=True,
+                    text=True,
+                    shell=False,
+                    encoding="utf-8" if PlatformAdapter.is_windows() else None,
+                    **deadline,
+                )
+            else:
+                # Let the command output directly to stdout/stderr
+                result = subprocess.run(
+                    command,
+                    env=env,
+                    cwd=cwd,
+                    shell=False,
+                    encoding="utf-8" if PlatformAdapter.is_windows() else None,
+                    **deadline,
+                )
+
+            return SubprocessResult(
+                returncode=result.returncode,
+                stdout=result.stdout if result.stdout else "",
+                stderr=result.stderr if result.stderr else "",
+            )
+        except subprocess.TimeoutExpired as e:
+            # An expired deadline is a failure *result*, not an escaping
+            # exception: callers keep asking ``success`` / ``launch_error`` the
+            # same way they do for every other failure. Partial output is
+            # dropped for the same reason the arm below drops it -- a caller
+            # must not parse half a probe's answer as a whole one.
+            return SubprocessResult(
+                returncode=-1,
+                stdout="",
+                stderr=str(e),
+                launch_error=str(e),
+                timed_out=True,
+            )
+        except Exception as e:
+            # Return a failed result in case of exception. ``launch_error``
+            # marks this as "could not be launched" so no caller has to infer it
+            # from the bare ``-1`` -- which a SIGHUP-killed child also reports.
+            return SubprocessResult(
+                returncode=-1, stdout="", stderr=str(e), launch_error=str(e)
+            )
+
+    def run(
+        self,
+        command: list[str],
+        env: dict[str, str] | None = None,
+        cwd: Path | None = None,
+        cache_result: bool = False,
+        quiet: bool = False,
+        timeout: float | None = None,
+    ) -> SubprocessResult:
+        """
+        Run a subprocess command.
+
+        Args:
+            command: The command to execute as a list of strings
+            env: Environment variables to use
+            cwd: Current working directory
+            cache_result: Whether to cache the result
+            quiet: Whether to suppress output
+            timeout: Optional deadline in seconds. ``None`` (the default) means
+                no deadline -- deliberately, since turning a legitimate long
+                task into a failure is worse than waiting; pass one only for
+                commands that are quick probes by definition. Expiry returns a
+                failed result with ``timed_out=True`` instead of raising.
+
+        Returns:
+            SubprocessResult: The result of the subprocess execution
+        """
+        command_key = " ".join(command)
+
+        # Return cached result if available
+        if cache_result and command_key in self._command_cache:
+            return self._command_cache[command_key]
+
+        # Prepare environment and working directory
+        environment = self._prepare_environment(env)
+        safe_cwd = self._prepare_cwd(cwd)
+
+        # Try direct execution if applicable. A direct run that times out is
+        # returned as-is rather than retried against the unresolved command:
+        # the retry could only spend the caller's deadline a second time (#184).
+        if should_use_direct_execution(command):
+            direct_command = get_direct_command(command)
+            try:
+                result = self._execute_command(
+                    direct_command, environment, safe_cwd, quiet, timeout
+                )
+                # Cache the result if requested
+                if cache_result:
+                    self._command_cache[command_key] = result
+                return result
+            except Exception:
+                # If direct execution fails, fall back to original command
+                pass
+
+        # Execute the original command
+        result = self._execute_command(command, environment, safe_cwd, quiet, timeout)
+
+        # Cache the result if requested
+        if cache_result:
+            self._command_cache[command_key] = result
+
+        return result
+
+    def clear_cache(self) -> None:
+        """Clear the command cache."""
+        self._command_cache.clear()
+
+    def get_cached_commands(self) -> list[str]:
+        """Get a list of cached command keys."""
+        return list(self._command_cache.keys())

wl_cli/utils/test_utils/__init__.py

@@ -0,0 +1,5 @@
+"""Test utilities for managing test execution."""
+
+from .test_filter import TestFilter
+
+__all__ = ["TestFilter"]