solokit 0.1.1__py3-none-any.whl

solokit/core/file_ops.py

@@ -0,0 +1,309 @@
+"""File operations utilities
+
+Centralized file I/O operations with consistent error handling and atomicity guarantees.
+"""
+
+import json
+import logging
+import shutil
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from solokit.core.exceptions import (
+    ErrorCode,
+    FileOperationError,
+    SystemError,
+)
+from solokit.core.exceptions import (
+    FileNotFoundError as SolokitFileNotFoundError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class JSONFileOperations:
+    """Centralized JSON file I/O with atomic writes and error handling"""
+
+    @staticmethod
+    def load_json(
+        file_path: Path,
+        default: Optional[dict[str, Any]] = None,
+        validator: Optional[Callable[[dict], bool]] = None,
+    ) -> dict[str, Any]:
+        """
+        Load JSON file with optional default and validation
+
+        Args:
+            file_path: Path to JSON file
+            default: Default value if file doesn't exist (None raises error)
+            validator: Optional validation function that returns True if data is valid
+
+        Returns:
+            Loaded JSON data as dict
+
+        Raises:
+            FileOperationError: If file not found and no default provided
+            FileOperationError: If JSON is invalid
+            FileOperationError: If validation fails
+
+        Examples:
+            >>> # Load required file (raises if missing)
+            >>> data = JSONFileOperations.load_json(Path("config.json"))
+            >>> # Load with default
+            >>> data = JSONFileOperations.load_json(Path("optional.json"), default={})
+            >>> # Load with validation
+            >>> validator = lambda d: "version" in d
+            >>> data = JSONFileOperations.load_json(Path("config.json"), validator=validator)
+        """
+        if not file_path.exists():
+            if default is not None:
+                logger.debug(f"File not found, using default: {file_path}")
+                return default
+            raise FileOperationError(
+                operation="read",
+                file_path=str(file_path),
+                details="File does not exist",
+            )
+
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                data: dict[str, Any] = json.load(f)
+        except json.JSONDecodeError as e:
+            raise FileOperationError(
+                operation="parse",
+                file_path=str(file_path),
+                details=f"Invalid JSON: {e}",
+                cause=e,
+            ) from e
+        except OSError as e:
+            raise FileOperationError(
+                operation="read",
+                file_path=str(file_path),
+                details=str(e),
+                cause=e,
+            ) from e
+        except Exception as e:
+            raise SystemError(
+                message=f"Unexpected error reading {file_path}",
+                code=ErrorCode.FILE_OPERATION_FAILED,
+                context={"file_path": str(file_path), "operation": "read"},
+                cause=e,
+            ) from e
+
+        if validator and not validator(data):
+            raise FileOperationError(
+                operation="validate",
+                file_path=str(file_path),
+                details="Validation function returned False",
+            )
+
+        logger.debug(f"Loaded JSON from {file_path}")
+        return data
+
+    @staticmethod
+    def save_json(
+        file_path: Path,
+        data: dict[str, Any],
+        indent: int = 2,
+        atomic: bool = True,
+        create_dirs: bool = True,
+    ) -> None:
+        """
+        Save data to JSON file with atomic write option
+
+        Args:
+            file_path: Path to JSON file
+            data: Data to save
+            indent: JSON indentation (default 2)
+            atomic: Use atomic write via temp file (default True)
+            create_dirs: Create parent directories if needed (default True)
+
+        Raises:
+            FileOperationError: If save fails
+
+        Examples:
+            >>> # Save with atomic write (default)
+            >>> JSONFileOperations.save_json(Path("data.json"), {"key": "value"})
+            >>> # Save without atomic write
+            >>> JSONFileOperations.save_json(Path("data.json"), data, atomic=False)
+            >>> # Save with custom indent
+            >>> JSONFileOperations.save_json(Path("data.json"), data, indent=4)
+        """
+        try:
+            if create_dirs:
+                file_path.parent.mkdir(parents=True, exist_ok=True)
+
+            if atomic:
+                # Atomic write via temp file
+                temp_path = file_path.with_suffix(file_path.suffix + ".tmp")
+                with open(temp_path, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=indent, default=str)
+                temp_path.replace(file_path)
+            else:
+                # Direct write
+                with open(file_path, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=indent, default=str)
+
+            logger.debug(f"Saved JSON to {file_path}")
+
+        except OSError as e:
+            raise FileOperationError(
+                operation="write",
+                file_path=str(file_path),
+                details=str(e),
+                cause=e,
+            ) from e
+        except Exception as e:
+            raise SystemError(
+                message=f"Unexpected error saving to {file_path}",
+                code=ErrorCode.FILE_OPERATION_FAILED,
+                context={
+                    "file_path": str(file_path),
+                    "operation": "write",
+                    "atomic": atomic,
+                },
+                cause=e,
+            ) from e
+
+    @staticmethod
+    def load_json_safe(file_path: Path, default: dict[str, Any]) -> dict[str, Any]:
+        """
+        Load JSON with guaranteed return (never raises)
+
+        Logs errors but always returns a value.
+        Convenience method for cases where failures should be silent.
+
+        Args:
+            file_path: Path to JSON file
+            default: Default value to return if load fails
+
+        Returns:
+            Loaded JSON data or default value
+
+        Examples:
+            >>> # Always returns a dict, never raises
+            >>> data = JSONFileOperations.load_json_safe(Path("config.json"), {})
+        """
+        try:
+            return JSONFileOperations.load_json(file_path)
+        except FileOperationError as e:
+            logger.warning(f"Using default for {file_path}: {e}")
+            return default
+
+
+# Convenience functions for backward compatibility
+def load_json(file_path: Path) -> dict[str, Any]:
+    """Load JSON file
+
+    Backward compatibility wrapper. Raises FileOperationError if file not found.
+
+    Args:
+        file_path: Path to JSON file
+
+    Returns:
+        Loaded JSON data
+
+    Raises:
+        FileOperationError: If file not found or JSON is invalid
+    """
+    return JSONFileOperations.load_json(file_path)
+
+
+def save_json(file_path: Path, data: dict[str, Any], indent: int = 2) -> None:
+    """Save data to JSON file with atomic write
+
+    Backward compatibility wrapper.
+
+    Args:
+        file_path: Path to JSON file
+        data: Data to save
+        indent: JSON indentation (default 2)
+
+    Raises:
+        FileOperationError: If save fails
+    """
+    JSONFileOperations.save_json(file_path, data, indent=indent)
+
+
+def ensure_directory(path: Path) -> None:
+    """Ensure directory exists"""
+    path.mkdir(parents=True, exist_ok=True)
+
+
+def backup_file(file_path: Path) -> Path:
+    """Create backup of a file
+
+    Args:
+        file_path: Path to file to backup
+
+    Returns:
+        Path to backup file
+
+    Raises:
+        SolokitFileNotFoundError: If source file doesn't exist
+        FileOperationError: If backup operation fails
+    """
+    if not file_path.exists():
+        raise SolokitFileNotFoundError(file_path=str(file_path), file_type="backup source")
+
+    try:
+        backup_path = file_path.with_suffix(f"{file_path.suffix}.backup")
+        shutil.copy2(file_path, backup_path)
+        return backup_path
+    except OSError as e:
+        raise FileOperationError(
+            operation="backup",
+            file_path=str(file_path),
+            details=str(e),
+            cause=e,
+        ) from e
+
+
+def read_file(file_path: Path) -> str:
+    """Read file contents
+
+    Args:
+        file_path: Path to file to read
+
+    Returns:
+        File contents as string
+
+    Raises:
+        SolokitFileNotFoundError: If file doesn't exist
+        FileOperationError: If read operation fails
+    """
+    if not file_path.exists():
+        raise SolokitFileNotFoundError(file_path=str(file_path), file_type="text file")
+
+    try:
+        with open(file_path) as f:
+            return f.read()
+    except OSError as e:
+        raise FileOperationError(
+            operation="read",
+            file_path=str(file_path),
+            details=str(e),
+            cause=e,
+        ) from e
+
+
+def write_file(file_path: Path, content: str) -> None:
+    """Write content to file
+
+    Args:
+        file_path: Path to file to write
+        content: Content to write
+
+    Raises:
+        FileOperationError: If write operation fails
+    """
+    try:
+        with open(file_path, "w") as f:
+            f.write(content)
+    except OSError as e:
+        raise FileOperationError(
+            operation="write",
+            file_path=str(file_path),
+            details=str(e),
+            cause=e,
+        ) from e

solokit/core/logging_config.py

@@ -0,0 +1,166 @@
+"""Centralized logging configuration for Solokit."""
+
+import json
+import logging
+import sys
+from collections.abc import Callable
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Optional
+
+
+class StructuredFormatter(logging.Formatter):
+    """Format logs as structured JSON."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        Format log record as JSON.
+
+        Args:
+            record: Log record to format
+
+        Returns:
+            JSON-formatted log string
+        """
+        log_data = {
+            "timestamp": datetime.utcnow().isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+            "module": record.module,
+            "function": record.funcName,
+            "line": record.lineno,
+        }
+
+        # Add extra fields if present
+        if hasattr(record, "context"):
+            log_data["context"] = record.context
+
+        # Add exception info if present
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+
+        return json.dumps(log_data)
+
+
+class HumanReadableFormatter(logging.Formatter):
+    """Format logs for human reading."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        """
+        Format log record for console.
+
+        Args:
+            record: Log record to format
+
+        Returns:
+            Human-readable log string
+        """
+        timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+        level = record.levelname
+        name = record.name
+        message = record.getMessage()
+
+        # Color code by level
+        level_colors = {
+            "DEBUG": "\033[36m",  # Cyan
+            "INFO": "\033[32m",  # Green
+            "WARNING": "\033[33m",  # Yellow
+            "ERROR": "\033[31m",  # Red
+            "CRITICAL": "\033[35m",  # Magenta
+        }
+        color = level_colors.get(level, "")
+        reset = "\033[0m"
+
+        formatted = f"{timestamp} {color}{level:8}{reset} {name} - {message}"
+
+        # Add exception if present
+        if record.exc_info:
+            formatted += "\n" + self.formatException(record.exc_info)
+
+        return formatted
+
+
+def setup_logging(
+    level: str = "INFO",
+    log_file: Optional[Path] = None,
+    structured: bool = False,
+) -> None:
+    """
+    Configure logging for the application.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        log_file: Optional file path for log output
+        structured: Use structured JSON logging (default: False)
+    """
+    root_logger = logging.getLogger("solokit")
+    root_logger.setLevel(getattr(logging, level.upper()))
+
+    # Remove existing handlers
+    root_logger.handlers.clear()
+
+    # Console handler
+    console_handler = logging.StreamHandler(sys.stderr)
+    if structured:
+        console_handler.setFormatter(StructuredFormatter())
+    else:
+        console_handler.setFormatter(HumanReadableFormatter())
+    root_logger.addHandler(console_handler)
+
+    # File handler if specified
+    if log_file:
+        log_file.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.FileHandler(log_file)
+        if structured:
+            file_handler.setFormatter(StructuredFormatter())
+        else:
+            file_handler.setFormatter(HumanReadableFormatter())
+        root_logger.addHandler(file_handler)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger for a module.
+
+    Args:
+        name: Logger name (usually __name__)
+
+    Returns:
+        Configured logger instance
+    """
+    return logging.getLogger(f"solokit.{name}")
+
+
+class LogContext:
+    """Context manager for adding context to logs."""
+
+    def __init__(self, logger: logging.Logger, **context: Any):
+        """
+        Initialize with logger and context data.
+
+        Args:
+            logger: Logger instance to add context to
+            **context: Key-value pairs to add as context
+        """
+        self.logger = logger
+        self.context = context
+        self.old_factory: Optional[Callable[..., logging.LogRecord]] = None
+
+    def __enter__(self) -> "LogContext":
+        """Add context to log records."""
+        old_factory = logging.getLogRecordFactory()
+
+        def record_factory(*args: Any, **kwargs: Any) -> logging.LogRecord:
+            record = old_factory(*args, **kwargs)
+            record.context = self.context
+            return record
+
+        logging.setLogRecordFactory(record_factory)
+        self.old_factory = old_factory
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Restore original factory."""
+        if self.old_factory is not None:
+            logging.setLogRecordFactory(self.old_factory)

solokit/core/output.py

@@ -0,0 +1,99 @@
+"""User output handler separate from diagnostic logging."""
+
+import sys
+
+
+class OutputHandler:
+    """Handle user-facing output separate from logs."""
+
+    def __init__(self, quiet: bool = False):
+        """
+        Initialize output handler.
+
+        Args:
+            quiet: Suppress all non-error output
+        """
+        self.quiet = quiet
+
+    def info(self, message: str) -> None:
+        """
+        Display info message to user.
+
+        Args:
+            message: Message to display
+        """
+        if not self.quiet:
+            print(message)
+
+    def success(self, message: str) -> None:
+        """
+        Display success message to user.
+
+        Args:
+            message: Success message to display
+        """
+        if not self.quiet:
+            print(f"✅ {message}")
+
+    def warning(self, message: str) -> None:
+        """
+        Display warning message to user.
+
+        Args:
+            message: Warning message to display
+        """
+        if not self.quiet:
+            print(f"⚠️  {message}")
+
+    def error(self, message: str) -> None:
+        """
+        Display error message to user.
+
+        Args:
+            message: Error message to display
+        """
+        print(f"❌ {message}", file=sys.stderr)
+
+    def progress(self, message: str) -> None:
+        """
+        Display progress message to user.
+
+        Args:
+            message: Progress message to display
+        """
+        if not self.quiet:
+            print(f"⏳ {message}")
+
+    def section(self, title: str) -> None:
+        """
+        Display section header.
+
+        Args:
+            title: Section title
+        """
+        if not self.quiet:
+            print(f"\n=== {title} ===\n")
+
+
+# Global output handler
+_output_handler = OutputHandler()
+
+
+def get_output() -> OutputHandler:
+    """
+    Get the global output handler.
+
+    Returns:
+        Global OutputHandler instance
+    """
+    return _output_handler
+
+
+def set_quiet(quiet: bool) -> None:
+    """
+    Set quiet mode for output handler.
+
+    Args:
+        quiet: True to suppress output, False to enable
+    """
+    _output_handler.quiet = quiet

solokit/core/performance.py

@@ -0,0 +1,57 @@
+"""Performance monitoring and profiling"""
+
+import time
+from functools import wraps
+from typing import Any, Callable, Optional, TypeVar, cast
+
+from solokit.core.logging_config import get_logger
+
+logger = get_logger(__name__)
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def measure_time(operation: Optional[str] = None) -> Callable[[F], F]:
+    """Decorator to measure function execution time"""
+
+    def decorator(func: F) -> F:
+        op_name = operation or f"{func.__module__}.{func.__name__}"
+
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            start = time.time()
+            try:
+                result = func(*args, **kwargs)
+                return result
+            finally:
+                duration = time.time() - start
+                if duration > 1.0:  # Warn if > 1s
+                    logger.warning(f"Slow operation: {op_name} took {duration:.3f}s")
+                elif duration > 0.1:  # Log if > 100ms
+                    logger.info(f"Performance: {op_name} took {duration:.3f}s")
+
+        return cast(F, wrapper)
+
+    return decorator
+
+
+class Timer:
+    """Context manager for timing code blocks"""
+
+    def __init__(self, name: str):
+        """Initialize timer with name"""
+        self.name = name
+        self.start: Optional[float] = None
+        self.duration: Optional[float] = None
+
+    def __enter__(self) -> "Timer":
+        """Start timer"""
+        self.start = time.time()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """End timer and log"""
+        if self.start is not None:
+            self.duration = time.time() - self.start
+            if self.duration > 0.1:
+                logger.info(f"Performance: {self.name} took {self.duration:.3f}s")