py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/performance/decorators.py

@@ -0,0 +1,111 @@
+"""Performance monitoring decorators and utilities."""
+
+import functools
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from .monitor import PerformanceMonitor
+
+
+def monitor_performance(operation_name: str, **additional_data: Any):
+    """
+    Decorator for monitoring the performance of a function.
+
+    Args:
+        operation_name: Name of the operation to track
+        **additional_data: Additional data to store with the metrics
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            monitor = get_performance_monitor()
+            with monitor.monitor_operation(operation_name, **additional_data):
+                return func(*args, **kwargs)
+
+        return wrapper
+
+    return decorator
+
+
+# Global monitor instance
+_performance_monitor = PerformanceMonitor()
+
+
+def get_performance_monitor() -> PerformanceMonitor:
+    """
+    Get the global performance monitor instance.
+
+    Returns:
+        The global performance monitor instance
+    """
+    return _performance_monitor
+
+
+def start_operation(operation_name: str) -> None:
+    """
+    Start timing an operation using the global monitor.
+
+    Args:
+        operation_name: Name of the operation to track
+    """
+    _performance_monitor.start_operation(operation_name)
+
+
+def end_operation(
+    operation_name: str, success: bool = True, **additional_data: Any
+) -> Any:
+    """
+    End timing an operation and record metrics using the global monitor.
+
+    Args:
+        operation_name: Name of the operation to track
+        success: Whether the operation was successful
+        **additional_data: Additional data to store with the metrics
+
+    Returns:
+        PerformanceMetrics object with the recorded metrics
+    """
+    return _performance_monitor.end_operation(
+        operation_name, success, **additional_data
+    )
+
+
+def monitor_operation(operation_name: str, **additional_data: Any):
+    """
+    Context manager for monitoring an operation using the global monitor.
+
+    Args:
+        operation_name: Name of the operation to track
+        **additional_data: Additional data to store with the metrics
+    """
+    return _performance_monitor.monitor_operation(operation_name, **additional_data)
+
+
+def get_metrics() -> list[Any]:
+    """
+    Get all recorded metrics from the global monitor.
+
+    Returns:
+        List of PerformanceMetrics objects
+    """
+    return _performance_monitor.get_metrics()
+
+
+def clear_metrics() -> None:
+    """Clear all recorded metrics from the global monitor."""
+    _performance_monitor.clear_metrics()
+
+
+def export_metrics(file_path: Path) -> None:
+    """
+    Export metrics to a JSON file using the global monitor.
+
+    Args:
+        file_path: Path to the output file
+    """
+    from .exporter import MetricsExporter
+
+    metrics = _performance_monitor.get_metrics()
+    MetricsExporter.export_to_json(metrics, file_path)

wl_cli/utils/performance/exporter.py

@@ -0,0 +1,38 @@
+"""Performance metrics export functionality."""
+
+import json
+from pathlib import Path
+
+from .models import PerformanceMetrics
+
+
+class MetricsExporter:
+    """Export performance metrics to various formats."""
+
+    @staticmethod
+    def export_to_json(metrics: list[PerformanceMetrics], file_path: Path) -> None:
+        """
+        Export metrics to a JSON file.
+
+        Args:
+            metrics: List of PerformanceMetrics objects
+            file_path: Path to the output file
+        """
+        try:
+            metrics_data = [
+                {
+                    "operation_name": metric.operation_name,
+                    "execution_time": metric.execution_time,
+                    "start_time": metric.start_time,
+                    "end_time": metric.end_time,
+                    "success": metric.success,
+                    "additional_data": metric.additional_data,
+                }
+                for metric in metrics
+            ]
+
+            with open(file_path, "w", encoding="utf-8") as f:
+                json.dump(metrics_data, f, indent=2, ensure_ascii=False)
+        except (OSError, TypeError) as e:
+            # Handle file I/O errors and JSON serialization errors
+            raise OSError(f"Failed to export metrics to {file_path}: {e}")

wl_cli/utils/performance/models.py

@@ -0,0 +1,16 @@
+"""Performance monitoring data models."""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class PerformanceMetrics:
+    """Performance metrics for a single operation."""
+
+    operation_name: str
+    execution_time: float
+    start_time: float
+    end_time: float
+    success: bool
+    additional_data: dict[str, Any] = field(default_factory=dict)

wl_cli/utils/performance/monitor.py

@@ -0,0 +1,161 @@
+"""Core performance monitoring functionality."""
+
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any
+
+from .models import PerformanceMetrics
+
+
+class PerformanceMonitor:
+    """A utility class for monitoring performance of operations."""
+
+    def __init__(self):
+        self._metrics: list[PerformanceMetrics] = []
+        self._active_operations: dict[str, float] = {}
+
+    def start_operation(self, operation_name: str) -> None:
+        """
+        Start timing an operation.
+
+        Args:
+            operation_name: Name of the operation to track
+        """
+        self._active_operations[operation_name] = time.perf_counter()
+
+    def end_operation(
+        self, operation_name: str, success: bool = True, **additional_data: Any
+    ) -> PerformanceMetrics:
+        """
+        End timing an operation and record metrics.
+
+        Args:
+            operation_name: Name of the operation to track
+            success: Whether the operation was successful
+            **additional_data: Additional data to store with the metrics
+
+        Returns:
+            PerformanceMetrics object with the recorded metrics
+        """
+        if operation_name not in self._active_operations:
+            raise ValueError(f"Operation '{operation_name}' was not started")
+
+        start_time = self._active_operations.pop(operation_name)
+        end_time = time.perf_counter()
+        execution_time = end_time - start_time
+
+        metrics = PerformanceMetrics(
+            operation_name=operation_name,
+            execution_time=execution_time,
+            start_time=start_time,
+            end_time=end_time,
+            success=success,
+            additional_data=additional_data,
+        )
+
+        self._metrics.append(metrics)
+        return metrics
+
+    def record_operation(
+        self,
+        operation_name: str,
+        execution_time: float,
+        success: bool = True,
+        **additional_data: Any,
+    ) -> PerformanceMetrics:
+        """
+        Record metrics for an operation without timing it.
+
+        Args:
+            operation_name: Name of the operation to track
+            execution_time: Execution time in seconds
+            success: Whether the operation was successful
+            **additional_data: Additional data to store with the metrics
+
+        Returns:
+            PerformanceMetrics object with the recorded metrics
+        """
+        start_time = time.perf_counter() - execution_time
+        end_time = start_time + execution_time
+
+        metrics = PerformanceMetrics(
+            operation_name=operation_name,
+            execution_time=execution_time,
+            start_time=start_time,
+            end_time=end_time,
+            success=success,
+            additional_data=additional_data,
+        )
+
+        self._metrics.append(metrics)
+        return metrics
+
+    @contextmanager
+    def monitor_operation(self, operation_name: str, **additional_data: Any):
+        """
+        Context manager for monitoring an operation.
+
+        Args:
+            operation_name: Name of the operation to track
+            **additional_data: Additional data to store with the metrics
+        """
+        self.start_operation(operation_name)
+        success = True
+        try:
+            yield
+        except Exception:
+            success = False
+            raise
+        finally:
+            try:
+                self.end_operation(operation_name, success, **additional_data)
+            except ValueError:
+                # Operation was not started, ignore
+                pass
+
+    def get_metrics(self) -> list[PerformanceMetrics]:
+        """
+        Get all recorded metrics.
+
+        Returns:
+            List of PerformanceMetrics objects
+        """
+        return self._metrics.copy()
+
+    def get_average_execution_time(self, operation_name: str) -> float | None:
+        """
+        Get the average execution time for an operation.
+
+        Args:
+            operation_name: Name of the operation
+
+        Returns:
+            Average execution time in seconds, or None if no metrics found
+        """
+        times = [
+            metric.execution_time
+            for metric in self._metrics
+            if metric.operation_name == operation_name
+        ]
+
+        if not times:
+            return None
+
+        return sum(times) / len(times)
+
+    def clear_metrics(self) -> None:
+        """Clear all recorded metrics."""
+        self._metrics.clear()
+        self._active_operations.clear()
+
+    def export_metrics(self, file_path: Path) -> None:
+        """
+        Export metrics to a JSON file.
+
+        Args:
+            file_path: Path to the output file
+        """
+        from .exporter import MetricsExporter
+
+        MetricsExporter.export_to_json(self._metrics, file_path)

wl_cli/utils/performance_monitor.py

@@ -0,0 +1,32 @@
+"""Performance monitoring utilities for WL Commands.
+
+This module serves as the entry point for the modularized performance monitoring functionality.
+主要功能委托给专门的模块以获得更好的组织结构。
+"""
+
+from .performance.decorators import (
+    clear_metrics,
+    end_operation,
+    export_metrics,
+    get_metrics,
+    get_performance_monitor,
+    monitor_operation,
+    monitor_performance,
+    start_operation,
+)
+from .performance.models import PerformanceMetrics
+from .performance.monitor import PerformanceMonitor
+
+# Backward compatibility: re-export all the main components
+__all__ = [
+    "PerformanceMetrics",
+    "PerformanceMonitor",
+    "monitor_performance",
+    "get_performance_monitor",
+    "start_operation",
+    "end_operation",
+    "monitor_operation",
+    "get_metrics",
+    "clear_metrics",
+    "export_metrics",
+]

wl_cli/utils/platform_adapter.py

@@ -0,0 +1,131 @@
+"""Platform adapter utility."""
+
+import os
+import platform
+import sys
+
+
+class PlatformAdapter:
+    """Platform adapter for Windows and Unix-like systems."""
+
+    def __init__(self) -> None:
+        pass
+
+    @staticmethod
+    def get_system() -> str:
+        """Get the current system name."""
+        return platform.system().lower()
+
+    @staticmethod
+    def is_windows() -> bool:
+        """Check if the current system is Windows."""
+        return PlatformAdapter.get_system() == "windows"
+
+    @staticmethod
+    def is_linux() -> bool:
+        """Check if the current system is Linux."""
+        return PlatformAdapter.get_system() == "linux"
+
+    @staticmethod
+    def is_mac() -> bool:
+        """Check if the current system is macOS."""
+        return PlatformAdapter.get_system() == "darwin"
+
+    @staticmethod
+    def get_env() -> dict[str, str]:
+        """Get environment variables for the current platform."""
+        env = os.environ.copy()
+
+        if PlatformAdapter.is_windows():
+            env["PYTHONIOENCODING"] = "utf-8"
+            env["PYTHONLEGACYWINDOWSFSENCODING"] = "1"
+        else:
+            env["PYTHONIOENCODING"] = "utf-8"
+
+        return env
+
+    @staticmethod
+    def get_encoding() -> str:
+        """Get the appropriate encoding for the current platform."""
+        if PlatformAdapter.is_windows():
+            return "utf-8" if sys.platform.startswith("win") else ""
+        return "utf-8"
+
+    @staticmethod
+    def get_platform_specific_path(path: str) -> str:
+        """
+        Get platform-specific path.
+
+        Args:
+            path: Path to convert
+
+        Returns:
+            Platform-specific path
+        """
+        if PlatformAdapter.is_windows():
+            return path.replace("/", "\\")
+        return path.replace("\\", "/")
+
+    @staticmethod
+    def get_shell() -> str:
+        """
+        Get the default shell for the current platform.
+
+        Returns:
+            Default shell executable
+        """
+        if PlatformAdapter.is_windows():
+            return "cmd.exe"
+        elif PlatformAdapter.is_mac():
+            return "/bin/zsh"
+        else:  # Linux
+            return "/bin/bash"
+
+    @staticmethod
+    def get_line_ending() -> str:
+        """
+        Get the line ending for the current platform.
+
+        Returns:
+            Line ending string
+        """
+        if PlatformAdapter.is_windows():
+            return "\r\n"
+        return "\n"
+
+    @staticmethod
+    def get_venv_create_command(venv_path: str) -> list[str]:
+        """Get the primary command that creates a virtual environment.
+
+        Windows invokes uv through the running interpreter (``python -m uv``)
+        because a bare ``uv`` is not guaranteed to be on ``PATH``; Unix-like
+        systems call the ``uv`` command directly.
+
+        Args:
+            venv_path: Destination directory for the virtual environment.
+
+        Returns:
+            The argv list for the first creation attempt.
+        """
+        if PlatformAdapter.is_windows():
+            return [sys.executable, "-m", "uv", "venv", venv_path]
+        return ["uv", "venv", venv_path]
+
+    @staticmethod
+    def get_venv_create_fallback_command(venv_path: str) -> list[str] | None:
+        """Get the retry command for virtual environment creation, if any.
+
+        Only Windows retries: ``python -m uv`` fails with ``No module named
+        uv`` when uv is installed as a standalone executable rather than as a
+        module, and the retry then calls ``uv`` directly. Unix-like systems
+        have no fallback.
+
+        Args:
+            venv_path: Destination directory for the virtual environment.
+
+        Returns:
+            The argv list to retry with, or ``None`` when no retry applies.
+        """
+        if PlatformAdapter.is_windows():
+            return ["uv", "venv", venv_path]
+        return None