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

xwlazy/lazy/__init__.py

@@ -0,0 +1,301 @@
+"""
+#exonware/xwsystem/src/exonware/xwsystem/utils/lazy_package/__init__.py
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.16
+Generation Date: 10-Oct-2025
+
+Lazy Package - Unified Lazy Loading System
+
+This package provides per-package lazy loading with automatic installation
+of missing dependencies. It consolidates all lazy loading functionality into
+a clean, well-structured module following DEV_GUIDELINES.md.
+
+Design Patterns:
+- Facade: Unified API (LazySystemFacade, LazyModeFacade)
+- Strategy: Pluggable discovery/installation/caching strategies
+- Template Method: Base classes define common workflows
+- Singleton: Global instances for system-wide state
+- Registry: Per-package isolation (LazyInstallerRegistry)
+- Observer: Performance monitoring
+- Proxy: Deferred loading (LazyLoader, DeferredImportError)
+- Factory: Handler creation
+
+Core Goal: Per-Package Lazy Loading
+Each package (xwsystem, xwnode, xwdata) can independently enable lazy mode.
+Only packages installed with [lazy] extra get auto-installation.
+
+Quick Start:
+    # In your package's __init__.py
+    from xwlazy.lazy import config_package_lazy_install_enabled
+    config_package_lazy_install_enabled("yourpackage")  # Auto-detect from pip install
+
+Usage:
+    # Then just use normal Python imports!
+    import fastavro  # Missing? Auto-installed! ✨
+    import pandas    # Missing? Auto-installed! ✨
+"""
+
+# Import all from submodules
+from .lazy_contracts import (
+    # Enums
+    LazyInstallMode,
+    PathType,
+    # Dataclasses
+    DependencyInfo,
+    # Interfaces
+    IPackageDiscovery,
+    IPackageInstaller,
+    IImportHook,
+    IPackageCache,
+    ILazyLoader,
+)
+
+from .lazy_errors import (
+    # Exceptions
+    LazySystemError,
+    LazyInstallError,
+    LazyDiscoveryError,
+    LazyHookError,
+    LazySecurityError,
+    ExternallyManagedError,
+    DeferredImportError,
+)
+
+from .lazy_base import (
+    # Abstract base classes
+    APackageDiscovery,
+    APackageInstaller,
+    AImportHook,
+    APackageCache,
+    ALazyLoader,
+)
+
+from .lazy_core import (
+    # Core classes
+    DependencyMapper,
+    LazyDiscovery,
+    LazyInstaller,
+    LazyInstallPolicy,
+    LazyInstallerRegistry,
+    LazyImportHook,
+    LazyMetaPathFinder,
+    LazyLoader,
+    LazyImporter,
+    LazyModuleRegistry,
+    LazyPerformanceMonitor,
+    LazyInstallConfig,
+    LazyModeFacade,
+    WatchedPrefixRegistry,
+    AsyncInstallHandle,
+    
+    # Discovery functions
+    get_lazy_discovery,
+    discover_dependencies,
+    export_dependency_mappings,
+    
+    # Install functions
+    enable_lazy_install,
+    disable_lazy_install,
+    is_lazy_install_enabled,
+    set_lazy_install_mode,
+    get_lazy_install_mode,
+    install_missing_package,
+    install_and_import,
+    get_lazy_install_stats,
+    get_all_lazy_install_stats,
+    lazy_import_with_install,
+    xwimport,
+    
+    # Hook functions
+    install_import_hook,
+    uninstall_import_hook,
+    is_import_hook_installed,
+    
+    # Lazy loading functions
+    enable_lazy_imports,
+    disable_lazy_imports,
+    is_lazy_import_enabled,
+    lazy_import,
+    register_lazy_module,
+    preload_module,
+    get_lazy_module,
+    get_loading_stats,
+    preload_frequently_used,
+    get_lazy_import_stats,
+    
+    # Lazy mode facade functions
+    enable_lazy_mode,
+    disable_lazy_mode,
+    is_lazy_mode_enabled,
+    get_lazy_mode_stats,
+    configure_lazy_mode,
+    preload_modules,
+    optimize_lazy_mode,
+    
+    # Configuration
+    config_package_lazy_install_enabled,
+    sync_manifest_configuration,
+    refresh_lazy_manifests,
+    
+    # Security & Policy
+    set_package_allow_list,
+    set_package_deny_list,
+    add_to_package_allow_list,
+    add_to_package_deny_list,
+    set_package_index_url,
+    set_package_extra_index_urls,
+    add_package_trusted_host,
+    set_package_lockfile,
+    generate_package_sbom,
+    check_externally_managed_environment,
+
+    # Registration helpers
+    register_lazy_module_prefix,
+    register_lazy_module_methods,
+)
+
+from .config import LazyConfig, DEFAULT_LAZY_CONFIG
+from .host_conf import get_conf_module
+from .host_packages import register_host_package, refresh_host_package
+from .logging_utils import (
+    get_log_categories,
+    is_log_category_enabled,
+    set_log_categories,
+    set_log_category,
+)
+
+# Version info
+__version__ = "0.0.1.382"
+__author__ = "Eng. Muhammad AlShehri"
+__email__ = "connect@exonware.com"
+__company__ = "eXonware.com"
+
+# Export all
+__all__ = [
+    # Enums
+    'LazyInstallMode',
+    'PathType',
+    
+    # Dataclasses
+    'DependencyInfo',
+    
+    # Interfaces
+    'IPackageDiscovery',
+    'IPackageInstaller',
+    'IImportHook',
+    'IPackageCache',
+    'ILazyLoader',
+    
+    # Exceptions
+    'LazySystemError',
+    'LazyInstallError',
+    'LazyDiscoveryError',
+    'LazyHookError',
+    'LazySecurityError',
+    'ExternallyManagedError',
+    'DeferredImportError',
+    
+    # Abstract base classes
+    'APackageDiscovery',
+    'APackageInstaller',
+    'AImportHook',
+    'APackageCache',
+    'ALazyLoader',
+    
+    # Core classes
+    'DependencyMapper',
+    'LazyDiscovery',
+    'LazyInstaller',
+    'LazyInstallPolicy',
+    'LazyInstallerRegistry',
+    'LazyImportHook',
+    'LazyMetaPathFinder',
+    'LazyLoader',
+    'LazyImporter',
+    'LazyModuleRegistry',
+    'LazyPerformanceMonitor',
+    'LazyInstallConfig',
+    'LazyModeFacade',
+    'WatchedPrefixRegistry',
+    'AsyncInstallHandle',
+    
+    # Discovery functions
+    'get_lazy_discovery',
+    'discover_dependencies',
+    'export_dependency_mappings',
+    
+    # Install functions
+    'enable_lazy_install',
+    'disable_lazy_install',
+    'is_lazy_install_enabled',
+    'set_lazy_install_mode',
+    'get_lazy_install_mode',
+    'install_missing_package',
+    'install_and_import',
+    'get_lazy_install_stats',
+    'get_all_lazy_install_stats',
+    'lazy_import_with_install',
+    'xwimport',
+    
+    # Hook functions
+    'install_import_hook',
+    'uninstall_import_hook',
+    'is_import_hook_installed',
+    
+    # Lazy loading functions
+    'enable_lazy_imports',
+    'disable_lazy_imports',
+    'is_lazy_import_enabled',
+    'lazy_import',
+    'register_lazy_module',
+    'preload_module',
+    'get_lazy_module',
+    'get_loading_stats',
+    'preload_frequently_used',
+    'get_lazy_import_stats',
+    
+    # Lazy mode facade functions
+    'enable_lazy_mode',
+    'disable_lazy_mode',
+    'is_lazy_mode_enabled',
+    'get_lazy_mode_stats',
+    'configure_lazy_mode',
+    'preload_modules',
+    'optimize_lazy_mode',
+    
+    # Configuration
+    'config_package_lazy_install_enabled',
+    'sync_manifest_configuration',
+    'refresh_lazy_manifests',
+    'LazyConfig',
+    'DEFAULT_LAZY_CONFIG',
+    
+    # Security & Policy
+    'set_package_allow_list',
+    'set_package_deny_list',
+    'add_to_package_allow_list',
+    'add_to_package_deny_list',
+    'set_package_index_url',
+    'set_package_extra_index_urls',
+    'add_package_trusted_host',
+    'set_package_lockfile',
+    'generate_package_sbom',
+    'check_externally_managed_environment',
+
+    # Registration helpers
+    'register_lazy_module_prefix',
+    'register_lazy_module_methods',
+    'register_host_package',
+    'refresh_host_package',
+    'get_conf_module',
+
+    # Logging helpers
+    'get_log_categories',
+    'is_log_category_enabled',
+    'set_log_categories',
+    'set_log_category',
+]
+

xwlazy/lazy/bootstrap.py

@@ -0,0 +1,106 @@
+#exonware/xwlazy/src/exonware/xwlazy/lazy/bootstrap.py
+"""
+Early bootstrap utilities for lazily installing import hooks.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import os
+import sys
+from typing import Optional
+
+
+def _env_enabled(env_value: Optional[str]) -> Optional[bool]:
+    if not env_value:
+        return None
+    normalized = env_value.strip().lower()
+    if normalized in ('true', '1', 'yes', 'on'):
+        return True
+    if normalized in ('false', '0', 'no', 'off'):
+        return False
+    return None
+
+
+def bootstrap_lazy_mode(package_name: str) -> None:
+    """
+    Detect whether lazy mode should be enabled for ``package_name`` and bootstrap hooks.
+    """
+    package_name = package_name.lower()
+    env_value = os.environ.get(f"{package_name.upper()}_LAZY_INSTALL")
+    env_enabled = _env_enabled(env_value)
+    enabled = env_enabled
+
+    if enabled is None:
+        try:
+            from xwlazy.lazy.lazy_core import _detect_lazy_installation
+            enabled = _detect_lazy_installation(package_name)
+        except Exception as exc:  # pragma: no cover
+            logging.getLogger("xwlazy.lazy.bootstrap").debug(
+                "Lazy detection failed: %s", exc, exc_info=True
+            )
+            enabled = False
+
+    if not enabled:
+        return
+
+    try:
+        from xwlazy.lazy.lazy_core import config_package_lazy_install_enabled
+
+        config_package_lazy_install_enabled(
+            package_name,
+            enabled=True,
+            install_hook=True,
+        )
+    except Exception as exc:  # pragma: no cover
+        logging.getLogger("xwlazy.lazy.bootstrap").debug(
+            "Lazy bootstrap failed for %s: %s", package_name, exc, exc_info=True
+        )
+
+
+def bootstrap_lazy_mode_deferred(package_name: str) -> None:
+    """
+    Schedule lazy mode bootstrap to run AFTER the calling package finishes importing.
+    
+    This avoids hook interference with the package's own imports (e.g., requests/certifi in xwsystem).
+    Uses a post-import hook to detect when the package module is fully loaded.
+    """
+    package_name_lower = package_name.lower()
+    package_module_name = f"exonware.{package_name_lower}"
+    
+    # Store original __import__ to restore later
+    original_import = __builtins__.__import__ if hasattr(__builtins__, '__import__') else __import__
+    
+    def _import_hook(name, *args, **kwargs):
+        # Call original import first
+        result = original_import(name, *args, **kwargs)
+        
+        # Check if the target package just finished importing
+        if name == package_module_name or name.startswith(f"{package_module_name}."):
+            # Check if package root is now fully in sys.modules
+            if package_module_name in sys.modules:
+                # Package is loaded, install hook on next event loop iteration
+                import threading
+                def _install_hook():
+                    # Restore original import
+                    if hasattr(__builtins__, '__import__'):
+                        __builtins__.__import__ = original_import
+                    else:
+                        import builtins
+                        builtins.__import__ = original_import
+                    # Now install the lazy hook
+                    bootstrap_lazy_mode(package_name_lower)
+                
+                # Schedule for immediate execution after current import completes
+                threading.Timer(0.0, _install_hook).start()
+        
+        return result
+    
+    # Install temporary import hook
+    if hasattr(__builtins__, '__import__'):
+        __builtins__.__import__ = _import_hook
+    else:
+        import builtins
+        builtins.__import__ = _import_hook
+

xwlazy/lazy/config.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+"""Configuration helpers for the lazy-loading subsystem."""
+
+from dataclasses import dataclass, field
+from typing import Tuple
+
+from .lazy_core import (
+    config_package_lazy_install_enabled,
+    disable_lazy_mode,
+    enable_lazy_mode,
+    is_import_hook_installed,
+    is_lazy_install_enabled,
+    is_lazy_mode_enabled,
+    install_import_hook,
+)
+
+
+@dataclass
+class LazyConfig:
+    """Bridge configuration settings with the lazy package implementation."""
+
+    packages: Tuple[str, ...] = field(
+        default_factory=lambda: ("default",)
+    )
+
+    def __post_init__(self) -> None:
+        self.packages = tuple(package.lower() for package in self.packages)
+
+    # High-level API -----------------------------------------------------
+    @property
+    def lazy_import(self) -> bool:
+        """Return whether lazy mode is currently active."""
+        return is_lazy_mode_enabled()
+
+    @lazy_import.setter
+    def lazy_import(self, value: bool) -> None:
+        self.set_lazy_import(bool(value))
+
+    def set_lazy_import(
+        self,
+        enabled: bool,
+        *,
+        lazy_imports: bool = True,
+        lazy_install: bool = True,
+        install_hook: bool = True,
+        mode: str = "auto",
+    ) -> None:
+        """
+        Toggle lazy mode with optional fine-grained controls.
+        
+        Includes re-hooking support: If lazy is enabled and install_hook is True,
+        ensures the import hook is installed even if it wasn't installed initially.
+        """
+        if enabled:
+            self._configure_packages(True, mode=mode, install_hook=install_hook)
+            enable_lazy_mode(
+                package_name=self.packages[0],
+                enable_lazy_imports=lazy_imports,
+                enable_lazy_install=lazy_install,
+                install_hook=install_hook,
+                lazy_install_mode=mode,
+            )
+            # Re-hook: Install hook if lazy is enabled and hook not already installed
+            # Root cause: Hook not installed when lazy enabled after package load
+            # Priority impact: Usability (#2) - Users expect lazy to work when enabled
+            if install_hook:
+                self._ensure_hook_installed()
+        else:
+            disable_lazy_mode()
+            self._configure_packages(False, install_hook=False)
+
+    def enable(
+        self,
+        *,
+        lazy_imports: bool = True,
+        lazy_install: bool = True,
+        install_hook: bool = True,
+        mode: str = "auto",
+    ) -> None:
+        """Enable lazy mode using the provided options."""
+        self.set_lazy_import(
+            True,
+            lazy_imports=lazy_imports,
+            lazy_install=lazy_install,
+            install_hook=install_hook,
+            mode=mode,
+        )
+
+    def disable(self) -> None:
+        """Disable lazy mode entirely."""
+        self.set_lazy_import(False)
+
+    # DX: Status check methods -------------------------------------------
+    def get_lazy_status(self) -> dict:
+        """
+        Get detailed lazy installation status (DX enhancement).
+        
+        Returns:
+            Dictionary with lazy mode status information
+        """
+        try:
+            primary_package = self.packages[0] if self.packages else "default"
+            return {
+                'enabled': self.lazy_import,
+                'hook_installed': is_import_hook_installed(primary_package),
+                'lazy_install_enabled': is_lazy_install_enabled(primary_package),
+                'active': self.lazy_import and is_import_hook_installed(primary_package)
+            }
+        except Exception:
+            return {
+                'enabled': self.lazy_import,
+                'hook_installed': False,
+                'lazy_install_enabled': False,
+                'active': False,
+                'error': 'Could not check hook status'
+            }
+    
+    def is_lazy_active(self) -> bool:
+        """
+        Check if lazy mode is active (DX enhancement).
+        
+        Returns:
+            True if lazy mode is enabled and hook is installed
+        """
+        try:
+            primary_package = self.packages[0] if self.packages else "default"
+            return self.lazy_import and is_import_hook_installed(primary_package)
+        except Exception:
+            return False
+
+    # Internal helpers ---------------------------------------------------
+    def _configure_packages(
+        self,
+        enabled: bool,
+        *,
+        mode: str = "auto",
+        install_hook: bool = True,
+    ) -> None:
+        for package in self.packages:
+            config_package_lazy_install_enabled(
+                package,
+                enabled,
+                mode,
+                install_hook=install_hook,
+            )
+    
+    def _ensure_hook_installed(self) -> None:
+        """
+        Ensure import hook is installed for primary package.
+        
+        Re-hooking support: Install hook if not already installed.
+        """
+        try:
+            primary_package = self.packages[0] if self.packages else "default"
+            if not is_import_hook_installed(primary_package):
+                install_import_hook(primary_package)
+        except Exception:
+            # Fail silently - hook installation failure shouldn't break package
+            pass
+
+
+DEFAULT_LAZY_CONFIG = LazyConfig()