exonware-xwlazy 0.1.0.10__py3-none-any.whl → 0.1.0.11__py3-none-any.whl

xwlazy/lazy/lazy_errors.py

@@ -0,0 +1,271 @@
+"""
+#exonware/xwsystem/src/exonware/xwsystem/utils/lazy_package/lazy_errors.py
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.16
+Generation Date: 10-Oct-2025
+
+Errors for Lazy Loading System
+
+This module defines all exception classes for the lazy loading system
+following DEV_GUIDELINES.md structure.
+"""
+
+from typing import Optional, Any
+
+
+# =============================================================================
+# BASE EXCEPTION
+# =============================================================================
+
+class LazySystemError(Exception):
+    """
+    Base exception for all lazy system errors.
+    
+    All lazy system exceptions inherit from this for easy error handling.
+    """
+    
+    def __init__(self, message: str, package_name: Optional[str] = None):
+        """
+        Initialize lazy system error.
+        
+        Args:
+            message: Error message
+            package_name: Optional package name for scoped errors
+        """
+        self.package_name = package_name
+        if package_name:
+            message = f"[{package_name}] {message}"
+        super().__init__(message)
+
+
+# =============================================================================
+# SPECIFIC EXCEPTIONS
+# =============================================================================
+
+class LazyInstallError(LazySystemError):
+    """
+    Raised when package installation fails.
+    
+    Examples:
+        - pip install command fails
+        - Package not found in PyPI
+        - Network error during installation
+    """
+    pass
+
+
+class LazyDiscoveryError(LazySystemError):
+    """
+    Raised when dependency discovery fails.
+    
+    Examples:
+        - Cannot read pyproject.toml
+        - Invalid TOML syntax
+        - Missing dependency configuration
+    """
+    pass
+
+
+class LazyHookError(LazySystemError):
+    """
+    Raised when import hook operation fails.
+    
+    Examples:
+        - Cannot install hook in sys.meta_path
+        - Hook is already installed
+        - Hook interception fails
+    """
+    pass
+
+
+class LazySecurityError(LazySystemError):
+    """
+    Raised when security policy is violated.
+    
+    Examples:
+        - Package not in allow list
+        - Package in deny list
+        - Untrusted package source
+    """
+    pass
+
+
+class ExternallyManagedError(LazyInstallError):
+    """
+    Raised when environment is externally managed (PEP 668).
+    
+    This happens when the Python environment has an EXTERNALLY-MANAGED
+    marker file, preventing pip installations. Common in system Python
+    installations on Linux distributions.
+    
+    Solutions:
+        1. Use a virtual environment
+        2. Use pipx for isolated installations
+        3. Override with --break-system-packages (not recommended)
+    """
+    
+    def __init__(self, package_name: str):
+        """
+        Initialize externally managed error.
+        
+        Args:
+            package_name: Package that cannot be installed
+        """
+        message = (
+            f"Cannot install '{package_name}': Environment is externally managed (PEP 668). "
+            f"Please use a virtual environment or pipx."
+        )
+        super().__init__(message, package_name=None)
+
+
+class DeferredImportError(Exception):
+    """
+    Placeholder for a failed import that will be retried when accessed.
+    
+    This enables two-stage lazy loading:
+    - Stage 1: Import fails → Return DeferredImportError placeholder
+    - Stage 2: On first use → Install missing package and replace with real module
+    
+    Performance optimized:
+    - Zero overhead until user actually accesses the deferred import
+    - Only installs dependencies when truly needed
+    - Caches successful imports to avoid repeated installs
+    
+    Note: This is both an error class and a proxy object. It stays in
+    lazy_errors.py because it represents an error state, but acts as
+    a proxy until resolved.
+    """
+    
+    __slots__ = (
+        '_import_name',
+        '_original_error',
+        '_installer_package',
+        '_retry_attempted',
+        '_real_module',
+        '_async_handle',
+    )
+    
+    def __init__(
+        self,
+        import_name: str,
+        original_error: Exception,
+        installer_package: str,
+        async_handle: Optional[Any] = None,
+    ):
+        """
+        Initialize deferred import placeholder.
+        
+        Args:
+            import_name: Name of the module that failed to import (e.g., 'fastavro')
+            original_error: The original ImportError that was caught
+            installer_package: Package name to use for lazy installation (e.g., 'xwsystem')
+        """
+        self._import_name = import_name
+        self._original_error = original_error
+        self._installer_package = installer_package
+        self._retry_attempted = False
+        self._real_module = None
+        self._async_handle = async_handle
+        super().__init__(f"Deferred import: {import_name}")
+    
+    def _try_install_and_import(self):
+        """
+        Attempt to install missing package and import it.
+        
+        Returns:
+            The real module if installation succeeds
+            
+        Raises:
+            Original ImportError if installation fails or is disabled
+        """
+        # Import here to avoid circular imports
+        from .lazy_core import lazy_import_with_install, is_lazy_install_enabled
+        from .logging_utils import get_logger
+        
+        logger = get_logger("xwlazy.lazy")
+        logger.info(f"[STAGE 2] _try_install_and_import called for '{self._import_name}'")
+        
+        # Return cached module if already installed
+        if self._real_module is not None:
+            logger.info(f"[STAGE 2] Using cached module for '{self._import_name}'")
+            return self._real_module
+        
+        # Only try once to avoid repeated failures
+        if self._retry_attempted:
+            logger.warning(f"[STAGE 2] Already attempted installation for '{self._import_name}', raising original error")
+            raise self._original_error
+        
+        self._retry_attempted = True
+        
+        if self._async_handle is not None:
+            logger.info(f"[STAGE 2] Waiting for async install of '{self._import_name}' to finish")
+            self._async_handle.wait()
+        
+        if not is_lazy_install_enabled(self._installer_package):
+            logger.warning(f"[STAGE 2] Lazy install disabled for {self._installer_package}, cannot load {self._import_name}")
+            raise self._original_error
+        
+        logger.info(f"⏳ [STAGE 2] Installing '{self._import_name}' on first use...")
+        
+        # Try to install and import
+        module, success = lazy_import_with_install(
+            self._import_name,
+            installer_package=self._installer_package
+        )
+        
+        if success and module:
+            self._real_module = module
+            logger.info(f"✅ [STAGE 2] Successfully installed and loaded '{self._import_name}'")
+            return module
+        else:
+            logger.error(f"❌ [STAGE 2] Failed to install '{self._import_name}'")
+            raise self._original_error
+    
+    def __call__(self, *args, **kwargs):
+        """
+        When user tries to instantiate, install dependency first.
+        
+        This enables: serializer = AvroSerializer() → installs fastavro → creates instance
+        """
+        module = self._try_install_and_import()
+        # If module is callable (a class), instantiate it
+        if callable(module):
+            return module(*args, **kwargs)
+        return module
+    
+    def __getattr__(self, name):
+        """
+        When user accesses attributes, install dependency first.
+        
+        This enables: from fastavro import reader → installs fastavro → returns reader
+        """
+        module = self._try_install_and_import()
+        return getattr(module, name)
+    
+    def __repr__(self):
+        """Show helpful message about deferred import."""
+        if self._real_module is not None:
+            return f"<DeferredImport: {self._import_name} (loaded)>"
+        return f"<DeferredImport: {self._import_name} (will install on first use)>"
+
+
+# =============================================================================
+# EXPORT ALL
+# =============================================================================
+
+__all__ = [
+    # Base exception
+    'LazySystemError',
+    # Specific exceptions
+    'LazyInstallError',
+    'LazyDiscoveryError',
+    'LazyHookError',
+    'LazySecurityError',
+    'ExternallyManagedError',
+    # Two-stage loading
+    'DeferredImportError',
+]
+

xwlazy/lazy/lazy_state.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, Optional
+
+
+def _get_base_config_dir() -> Path:
+    """Determine a cross-platform directory for storing lazy configuration."""
+    if os.name == "nt":
+        appdata = os.getenv("APPDATA")
+        if appdata:
+            return Path(appdata) / "exonware" / "lazy"
+        return Path.home() / "AppData" / "Roaming" / "exonware" / "lazy"
+
+    # POSIX-style
+    xdg_config = os.getenv("XDG_CONFIG_HOME")
+    if xdg_config:
+        return Path(xdg_config) / "exonware" / "lazy"
+    return Path.home() / ".config" / "exonware" / "lazy"
+
+
+class LazyStateManager:
+    """Persist and retrieve lazy installation state."""
+
+    def __init__(self, package_name: str) -> None:
+        self._package = package_name.lower()
+        self._state_path = _get_base_config_dir() / "state.json"
+        self._state: Dict[str, Dict[str, bool]] = self._load_state()
+
+    # --------------------------------------------------------------------- #
+    # Persistence helpers
+    # --------------------------------------------------------------------- #
+    def _load_state(self) -> Dict[str, Dict[str, bool]]:
+        if not self._state_path.exists():
+            return {}
+        try:
+            with self._state_path.open("r", encoding="utf-8") as fh:
+                data = json.load(fh)
+                if isinstance(data, dict):
+                    return data
+        except Exception:
+            pass
+        return {}
+
+    def _save_state(self) -> None:
+        self._state_path.parent.mkdir(parents=True, exist_ok=True)
+        with self._state_path.open("w", encoding="utf-8") as fh:
+            json.dump(self._state, fh, indent=2, sort_keys=True)
+
+    def _ensure_entry(self) -> Dict[str, bool]:
+        return self._state.setdefault(self._package, {})
+
+    # --------------------------------------------------------------------- #
+    # Manual state management
+    # --------------------------------------------------------------------- #
+    def get_manual_state(self) -> Optional[bool]:
+        entry = self._state.get(self._package, {})
+        value = entry.get("manual")
+        return bool(value) if isinstance(value, bool) else None
+
+    def set_manual_state(self, value: Optional[bool]) -> None:
+        entry = self._ensure_entry()
+        if value is None:
+            entry.pop("manual", None)
+        else:
+            entry["manual"] = bool(value)
+        self._save_state()
+
+    # --------------------------------------------------------------------- #
+    # Auto detection cache
+    # --------------------------------------------------------------------- #
+    def get_cached_auto_state(self) -> Optional[bool]:
+        entry = self._state.get(self._package, {})
+        value = entry.get("auto")
+        return bool(value) if isinstance(value, bool) else None
+
+    def set_auto_state(self, value: Optional[bool]) -> None:
+        entry = self._ensure_entry()
+        if value is None:
+            entry.pop("auto", None)
+        else:
+            entry["auto"] = bool(value)
+        self._save_state()
+

xwlazy/lazy/logging_utils.py

@@ -0,0 +1,194 @@
+#exonware/xwlazy/src/exonware/xwlazy/lazy/logging_utils.py
+"""
+Lightweight logging helper for the xwlazy lazy subsystem.
+
+Adds category-based filtering so noisy traces (hook/install/audit/etc.) can be
+turned on or off individually via configuration or environment variables.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from datetime import datetime
+from typing import Dict, Optional
+
+_configured = False
+
+_CATEGORY_DEFAULTS: Dict[str, bool] = {
+    "install": True,     # always show installs by default
+    "hook": False,
+    "enhance": False,
+    "audit": False,
+    "sbom": False,
+    "config": False,
+    "discovery": False,
+}
+_category_overrides: Dict[str, bool] = {}
+
+
+def _normalize_category(name: str) -> str:
+    return name.strip().lower()
+
+
+def _load_env_overrides() -> None:
+    for category in _CATEGORY_DEFAULTS:
+        env_key = f"XWLAZY_LOG_{category.upper()}"
+        env_val = os.getenv(env_key)
+        if env_val is None:
+            continue
+        enabled = env_val.strip().lower() not in {"0", "false", "off", "no"}
+        _category_overrides[_normalize_category(category)] = enabled
+
+
+class XWLazyFormatter(logging.Formatter):
+    """Custom formatter for xwlazy that uses exonware.xwlazy [HH:MM:SS]: [FLAG] format."""
+    
+    # Map logging levels to flags
+    LEVEL_FLAGS = {
+        logging.DEBUG: "DEBUG",
+        logging.INFO: "INFO",
+        logging.WARNING: "WARN",
+        logging.ERROR: "ERROR",
+        logging.CRITICAL: "CRITICAL",
+    }
+    
+    # Map flags to emojis
+    EMOJI_MAP = {
+        "WARN": "⚠️",
+        "INFO": "ℹ️",
+        "ACTION": "⚙️",
+        "SUCCESS": "✅",
+        "ERROR": "❌",
+        "FAIL": "⛔",
+        "DEBUG": "🔍",
+        "CRITICAL": "🚨",
+    }
+    
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record with custom format."""
+        # Get flag from level or use INFO as default
+        flag = self.LEVEL_FLAGS.get(record.levelno, "INFO")
+        
+        # Get emoji for flag
+        emoji = self.EMOJI_MAP.get(flag, "ℹ️")
+        
+        # Format time as HH:MM:SS
+        time_str = datetime.now().strftime("%H:%M:%S")
+        
+        # Format message
+        message = record.getMessage()
+        
+        # Return formatted: emoji exonware.xwlazy [HH:MM:SS]: [FLAG] message
+        return f"{emoji} exonware.xwlazy [{time_str}]: [{flag}] {message}"
+
+
+def _ensure_basic_config() -> None:
+    global _configured
+    if _configured:
+        return
+    
+    # Configure root logger with custom formatter
+    root_logger = logging.getLogger()
+    root_logger.setLevel(logging.INFO)
+    
+    # Remove existing handlers to avoid duplicates
+    for handler in root_logger.handlers[:]:
+        root_logger.removeHandler(handler)
+    
+    # Create console handler with custom formatter
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(logging.INFO)
+    console_handler.setFormatter(XWLazyFormatter())
+    root_logger.addHandler(console_handler)
+    
+    _load_env_overrides()
+    _configured = True
+
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """Return a logger configured for the lazy subsystem."""
+    _ensure_basic_config()
+    return logging.getLogger(name or "xwlazy.lazy")
+
+
+def is_log_category_enabled(category: str) -> bool:
+    """Return True if the provided log category is enabled."""
+    _ensure_basic_config()
+    normalized = _normalize_category(category)
+    if normalized in _category_overrides:
+        return _category_overrides[normalized]
+    return _CATEGORY_DEFAULTS.get(normalized, True)
+
+
+def set_log_category(category: str, enabled: bool) -> None:
+    """Enable/disable an individual log category at runtime."""
+    _category_overrides[_normalize_category(category)] = bool(enabled)
+
+
+def set_log_categories(overrides: Dict[str, bool]) -> None:
+    """Bulk update multiple categories."""
+    for category, enabled in overrides.items():
+        set_log_category(category, enabled)
+
+
+def get_log_categories() -> Dict[str, bool]:
+    """Return the effective state for each built-in log category."""
+    _ensure_basic_config()
+    result = {}
+    for category, default_enabled in _CATEGORY_DEFAULTS.items():
+        normalized = _normalize_category(category)
+        result[category] = _category_overrides.get(normalized, default_enabled)
+    return result
+
+
+def log_event(category: str, level_fn, msg: str, *args, **kwargs) -> None:
+    """Emit a log for the given category if it is enabled."""
+    if is_log_category_enabled(category):
+        level_fn(msg, *args, **kwargs)
+
+
+def format_message(flag: str, message: str) -> str:
+    """
+    Format a message with exonware.xwlazy [HH:MM:SS]: [FLAG] format.
+    
+    Args:
+        flag: Message flag (WARN, ACTION, SUCCESS, etc.)
+        message: Message content
+        
+    Returns:
+        Formatted message string
+    """
+    # Map flags to emojis
+    emoji_map = {
+        "WARN": "⚠️",
+        "INFO": "ℹ️",
+        "ACTION": "⚙️",
+        "SUCCESS": "✅",
+        "ERROR": "❌",
+        "FAIL": "⛔",
+        "DEBUG": "🔍",
+        "CRITICAL": "🚨",
+    }
+    emoji = emoji_map.get(flag, "ℹ️")
+    time_str = datetime.now().strftime("%H:%M:%S")
+    return f"{emoji} exonware.xwlazy [{time_str}]: [{flag}] {message}"
+
+
+def print_formatted(flag: str, message: str, same_line: bool = False) -> None:
+    """
+    Print a formatted message with optional same-line support.
+    
+    Args:
+        flag: Message flag (WARN, ACTION, SUCCESS, etc.)
+        message: Message content
+        same_line: If True, use \r to overwrite previous line
+    """
+    formatted = format_message(flag, message)
+    if same_line:
+        sys.stdout.write(f"\r{formatted}")
+        sys.stdout.flush()
+    else:
+        print(formatted)
+