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

exonware/xwlazy/common/logger.py

@@ -0,0 +1,257 @@
+"""
+#exonware/xwlazy/src/exonware/xwlazy/common/logger.py
+
+Logging utilities for xwlazy - shared across package, module, and runtime.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+
+Generation Date: 15-Nov-2025
+
+This module provides unified logging functionality for all xwlazy components.
+All logging code is centralized here to avoid duplication.
+"""
+
+import os
+import sys
+import logging
+import io
+from typing import Dict, Optional
+from datetime import datetime
+
+# =============================================================================
+# CONSTANTS
+# =============================================================================
+
+# Emoji mapping for log flags (shared across formatter and format_message)
+_EMOJI_MAP = {
+    "WARN": "⚠️",
+    "INFO": "ℹ️",
+    "ACTION": "⚙️",
+    "SUCCESS": "✅",
+    "ERROR": "❌",
+    "FAIL": "⛔",
+    "DEBUG": "🔍",
+    "CRITICAL": "🚨",
+}
+
+# Default log category states
+_CATEGORY_DEFAULTS: Dict[str, bool] = {
+    "install": True,
+    "hook": False,
+    "enhance": False,
+    "audit": False,
+    "sbom": False,
+    "config": False,
+    "discovery": False,
+}
+
+# =============================================================================
+# MODULE STATE
+# =============================================================================
+
+_configured = False
+_category_overrides: Dict[str, bool] = {}
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+def _normalize_category(name: str) -> str:
+    """Normalize category name to lowercase."""
+    return name.strip().lower()
+
+def _load_env_overrides() -> None:
+    """Load log category overrides from environment variables."""
+    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
+
+# =============================================================================
+# FORMATTER
+# =============================================================================
+
+class XWLazyFormatter(logging.Formatter):
+    """Custom formatter for xwlazy that uses exonware.xwlazy [HH:MM:SS]: [FLAG] format."""
+    
+    LEVEL_FLAGS = {
+        logging.DEBUG: "DEBUG",
+        logging.INFO: "INFO",
+        logging.WARNING: "WARN",
+        logging.ERROR: "ERROR",
+        logging.CRITICAL: "CRITICAL",
+    }
+    
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record with emoji and timestamp."""
+        flag = self.LEVEL_FLAGS.get(record.levelno, "INFO")
+        emoji = _EMOJI_MAP.get(flag, "ℹ️")
+        time_str = datetime.now().strftime("%H:%M:%S")
+        message = record.getMessage()
+        return f"{emoji} exonware.xwlazy [{time_str}]: [{flag}] {message}"
+
+# =============================================================================
+# CONFIGURATION
+# =============================================================================
+
+def _ensure_basic_config() -> None:
+    """Ensure logging is configured (called once)."""
+    global _configured
+    if _configured:
+        return
+    
+    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)
+    
+    # Add console handler with custom formatter and UTF-8 encoding for Windows
+    # Wrap stdout with UTF-8 encoding to handle emoji characters on Windows
+    if sys.platform == "win32":
+        # On Windows, wrap stdout with UTF-8 encoding
+        try:
+            # Try to set UTF-8 encoding for stdout
+            if hasattr(sys.stdout, 'reconfigure'):
+                sys.stdout.reconfigure(encoding='utf-8', errors='replace')
+            # Create a wrapper stream that handles encoding
+            utf8_stream = io.TextIOWrapper(
+                sys.stdout.buffer,
+                encoding='utf-8',
+                errors='replace',
+                line_buffering=True
+            )
+            console_handler = logging.StreamHandler(utf8_stream)
+        except (AttributeError, OSError):
+            # Fallback to regular stdout if reconfiguration fails
+            console_handler = logging.StreamHandler(sys.stdout)
+    else:
+        console_handler = logging.StreamHandler(sys.stdout)
+    
+    console_handler.setLevel(logging.INFO)
+    console_handler.setFormatter(XWLazyFormatter())
+    root_logger.addHandler(console_handler)
+    
+    # Load environment overrides
+    _load_env_overrides()
+    
+    _configured = True
+
+# =============================================================================
+# PUBLIC API
+# =============================================================================
+
+def get_logger(name: Optional[str] = None) -> logging.Logger:
+    """
+    Return a logger configured for the lazy subsystem.
+    
+    Args:
+        name: Optional logger name (defaults to "xwlazy.lazy")
+        
+    Returns:
+        Configured logger instance
+    """
+    _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.
+    
+    Args:
+        category: Log category name (e.g., "install", "hook")
+        
+    Returns:
+        True if category is enabled, False otherwise
+    """
+    _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.
+    
+    Args:
+        category: Log category name
+        enabled: True to enable, False to disable
+    """
+    _category_overrides[_normalize_category(category)] = bool(enabled)
+
+def set_log_categories(overrides: Dict[str, bool]) -> None:
+    """
+    Bulk update multiple log categories.
+    
+    Args:
+        overrides: Dictionary mapping category names to enabled state
+    """
+    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.
+    
+    Returns:
+        Dictionary mapping category names to enabled state
+    """
+    _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.
+    
+    Args:
+        category: Log category name
+        level_fn: Logging function (e.g., logger.info, logger.warning)
+        msg: Log message format string
+        *args: Positional arguments for message formatting
+        **kwargs: Keyword arguments for message formatting
+    """
+    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: Log flag (e.g., "INFO", "WARN", "ERROR")
+        message: Message text
+        
+    Returns:
+        Formatted message string
+    """
+    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: Log flag (e.g., "INFO", "WARN", "ERROR")
+        message: Message text
+        same_line: If True, use carriage return for same-line output
+    """
+    formatted = format_message(flag, message)
+    if same_line:
+        sys.stdout.write(f"\r{formatted}")
+        sys.stdout.flush()
+    else:
+        print(formatted)
+

exonware/xwlazy/common/services/__init__.py

@@ -0,0 +1,72 @@
+"""
+Common Services
+
+Shared services used by both modules and packages.
+"""
+
+from .dependency_mapper import DependencyMapper
+from .spec_cache import (
+    _spec_cache_get,
+    _spec_cache_put,
+    _spec_cache_clear,
+    _cache_spec_if_missing,
+    get_stdlib_module_set,
+)
+from .state_manager import LazyStateManager
+from .keyword_detection import (
+    enable_keyword_detection,
+    is_keyword_detection_enabled,
+    get_keyword_detection_keyword,
+    check_package_keywords,
+    _detect_lazy_installation,
+    _detect_meta_info_mode,
+)
+from .install_cache_utils import (
+    get_default_cache_dir,
+    get_cache_dir,
+    get_wheel_path,
+    get_install_tree_dir,
+    get_site_packages_dir,
+    pip_install_from_path,
+    ensure_cached_wheel,
+    install_from_cached_tree,
+    materialize_cached_tree,
+    has_cached_install_tree,
+    install_from_cached_wheel,
+)
+from .install_async_utils import (
+    get_package_size_mb,
+    async_install_package,
+    async_uninstall_package,
+)
+
+__all__ = [
+    'DependencyMapper',
+    '_spec_cache_get',
+    '_spec_cache_put',
+    '_spec_cache_clear',
+    '_cache_spec_if_missing',
+    'get_stdlib_module_set',
+    'LazyStateManager',
+    'enable_keyword_detection',
+    'is_keyword_detection_enabled',
+    'get_keyword_detection_keyword',
+    'check_package_keywords',
+    '_detect_lazy_installation',
+    '_detect_meta_info_mode',
+    'get_default_cache_dir',
+    'get_cache_dir',
+    'get_wheel_path',
+    'get_install_tree_dir',
+    'get_site_packages_dir',
+    'pip_install_from_path',
+    'ensure_cached_wheel',
+    'install_from_cached_tree',
+    'materialize_cached_tree',
+    'has_cached_install_tree',
+    'install_from_cached_wheel',
+    'get_package_size_mb',
+    'async_install_package',
+    'async_uninstall_package',
+]
+

exonware/xwlazy/common/services/dependency_mapper.py

@@ -0,0 +1,232 @@
+"""
+Dependency Mapper for package discovery.
+
+This module contains DependencyMapper class extracted from lazy_core.py Section 1.
+"""
+
+import threading
+from typing import Dict, List, Optional, Set, Tuple
+
+# Lazy import to avoid circular dependency
+def _get_logger():
+    """Get logger (lazy import to avoid circular dependency)."""
+    from ...common.logger import get_logger
+    return get_logger("xwlazy.discovery")
+
+logger = None  # Will be initialized on first use
+
+# Import from spec_cache (same directory)
+from .spec_cache import (
+    _cached_stdlib_check,
+    _spec_cache_get,
+    _cache_spec_if_missing,
+    get_stdlib_module_set,
+)
+
+_STDLIB_MODULE_SET = get_stdlib_module_set()
+
+# Import from manifest (package/services - avoid circular import)
+def get_manifest_loader():
+    """Get manifest loader (lazy import to avoid circular dependency)."""
+    from ...package.services.manifest import get_manifest_loader as _get_manifest_loader
+    return _get_manifest_loader()
+
+# Import from discovery (package/services - avoid circular import)
+def get_lazy_discovery():
+    """Get discovery instance."""
+    from ...package.services.discovery import get_lazy_discovery as _get_lazy_discovery
+    return _get_lazy_discovery()
+
+class DependencyMapper:
+    """
+    Maps import names to package names using dynamic discovery.
+    Optimized with caching to avoid repeated file I/O.
+    """
+    
+    __slots__ = (
+        '_discovery',
+        '_package_import_mapping',
+        '_import_package_mapping',
+        '_cached',
+        '_lock',
+        '_package_name',
+        '_manifest_generation',
+        '_manifest_dependencies',
+        '_manifest_signature',
+        '_manifest_empty',
+    )
+    
+    def __init__(self, package_name: str = 'default'):
+        """Initialize dependency mapper."""
+        self._discovery = None  # Lazy init to avoid circular imports
+        self._package_import_mapping: Dict[str, List[str]] = {}
+        self._import_package_mapping: Dict[str, str] = {}
+        self._cached = False
+        self._lock = threading.RLock()
+        self._package_name = package_name
+        self._manifest_generation = -1
+        self._manifest_dependencies: Dict[str, str] = {}
+        self._manifest_signature: Optional[Tuple[str, float, float]] = None
+        self._manifest_empty = False
+
+    def set_package_name(self, package_name: str) -> None:
+        """Update the owning package name (affects manifest lookups)."""
+        normalized = (package_name or 'default').strip().lower() or 'default'
+        if normalized != self._package_name:
+            self._package_name = normalized
+            self._manifest_generation = -1
+            self._manifest_dependencies = {}
+    
+    def _get_discovery(self):
+        """Get discovery instance (lazy init)."""
+        if self._discovery is None:
+            self._discovery = get_lazy_discovery()
+        return self._discovery
+    
+    def _ensure_mappings_cached(self) -> None:
+        """Ensure mappings are cached (lazy initialization)."""
+        if self._cached:
+            return
+        
+        with self._lock:
+            if self._cached:
+                return
+            
+            discovery = self._get_discovery()
+            self._package_import_mapping = discovery.get_package_import_mapping()
+            self._import_package_mapping = discovery.get_import_package_mapping()
+            self._cached = True
+    
+    def _ensure_manifest_cached(self, loader=None) -> None:
+        if loader is None:
+            loader = get_manifest_loader()
+        signature = loader.get_manifest_signature(self._package_name)
+        if signature == self._manifest_signature and (self._manifest_dependencies or self._manifest_empty):
+            return
+        
+        shared = loader.get_shared_dependencies(self._package_name, signature)
+        if shared is not None:
+            self._manifest_generation = loader.generation
+            self._manifest_signature = signature
+            self._manifest_dependencies = shared
+            self._manifest_empty = len(shared) == 0
+            return
+
+        manifest = loader.get_manifest(self._package_name)
+        current_generation = loader.generation
+
+        dependencies: Dict[str, str] = {}
+        manifest_empty = True
+        if manifest and manifest.dependencies:
+            dependencies = {
+                key.lower(): value
+                for key, value in manifest.dependencies.items()
+                if key and value
+            }
+            manifest_empty = False
+
+        self._manifest_generation = current_generation
+        self._manifest_signature = signature
+        self._manifest_dependencies = dependencies
+        self._manifest_empty = manifest_empty
+    
+    @staticmethod
+    def _is_stdlib_or_builtin(module_name: str) -> bool:
+        """Return True if the module is built-in or part of the stdlib."""
+        root = module_name.split('.', 1)[0]
+        needs_cache = False
+        if module_name in _STDLIB_MODULE_SET or root in _STDLIB_MODULE_SET:
+            return True
+        if _cached_stdlib_check(module_name):
+            needs_cache = True
+        if needs_cache:
+            _cache_spec_if_missing(module_name)
+        return needs_cache
+
+    DENY_LIST: Set[str] = {
+        # POSIX-only modules that don't exist on Windows but try to auto-install
+        "pwd",
+        "grp",
+        "spwd",
+        "nis",
+        "termios",
+        "tty",
+        "pty",
+        "fcntl",
+        # Windows-only internals
+        "winreg",
+        "winsound",
+        "_winapi",
+        "_dbm",
+        # Internal optional modules that must never trigger auto-install
+        "compression",
+        "socks",
+        "wimlib",
+        # Optional dependencies with Python 2 compatibility shims (Python 3.8+ only)
+        "inspect2",  # Python 2 compatibility shim, not needed on Python 3.8+
+        "rich",      # Optional CLI enhancement for httpx, not required for core functionality
+    }
+
+    def _should_skip_auto_install(self, import_name: str) -> bool:
+        """Determine whether an import should bypass lazy installation."""
+        global logger
+        if logger is None:
+            logger = _get_logger()
+        
+        if self._is_stdlib_or_builtin(import_name):
+            logger.debug("Skipping lazy install for stdlib module '%s'", import_name)
+            return True
+
+        if import_name in self.DENY_LIST:
+            logger.debug("Skipping lazy install for denied module '%s'", import_name)
+            return True
+
+        return False
+
+    def get_package_name(self, import_name: str) -> Optional[str]:
+        """
+        Get package name from import name.
+        
+        Priority order (manifest takes precedence):
+        1. Skip checks (stdlib, deny list)
+        2. Manifest dependencies (explicit user configuration - highest priority)
+        3. Spec cache (module already exists - skip auto-install)
+        4. Discovery mappings (automatic discovery)
+        """
+        if self._should_skip_auto_install(import_name):
+            return None
+        
+        # Check manifest FIRST - explicit user configuration takes precedence
+        loader = get_manifest_loader()
+        generation_changed = self._manifest_generation != loader.generation
+        manifest_uninitialized = not self._manifest_dependencies and not self._manifest_empty
+        if generation_changed or manifest_uninitialized:
+            self._ensure_manifest_cached(loader)
+        manifest_hit = self._manifest_dependencies.get(import_name.lower())
+        if manifest_hit:
+            return manifest_hit
+        
+        # Check spec cache - if module already exists, skip auto-install
+        if _spec_cache_get(import_name):
+            return None
+
+        self._ensure_mappings_cached()
+        return self._import_package_mapping.get(import_name, import_name)
+    
+    def get_import_names(self, package_name: str) -> List[str]:
+        """Get all possible import names for a package."""
+        self._ensure_mappings_cached()
+        return self._package_import_mapping.get(package_name, [package_name])
+    
+    def get_package_import_mapping(self) -> Dict[str, List[str]]:
+        """Get complete package to import names mapping."""
+        self._ensure_mappings_cached()
+        return self._package_import_mapping.copy()
+    
+    def get_import_package_mapping(self) -> Dict[str, str]:
+        """Get complete import to package name mapping."""
+        self._ensure_mappings_cached()
+        return self._import_package_mapping.copy()
+
+__all__ = ['DependencyMapper']
+