exonware-xwlazy 0.1.0.22__py3-none-any.whl → 0.1.0.23__py3-none-any.whl

exonware/xwlazy/module/partial_module_detector.py

@@ -0,0 +1,275 @@
+"""
+Partial Module Detection Strategies
+
+Detects if a module in sys.modules is partially initialized (still being imported).
+This prevents returning partially initialized modules that cause ImportErrors.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+
+Generation Date: 27-Dec-2025
+"""
+
+import sys
+import threading
+from types import ModuleType
+from typing import Optional
+from enum import Enum
+
+class DetectionStrategy(Enum):
+    """Different strategies for detecting partially initialized modules."""
+    FRAME_STACK = "frame_stack"  # Check call stack for import functions
+    ATTRIBUTE_CHECK = "attribute_check"  # Check if expected attributes exist
+    IMPORT_LOCK = "import_lock"  # Use importlib's import lock state
+    MODULE_STATE = "module_state"  # Check module's __spec__ and loader state
+    HYBRID = "hybrid"  # Combine multiple strategies
+
+# Track modules currently being imported (thread-safe)
+_importing_modules: set[str] = set()
+_import_lock = threading.RLock()
+
+def mark_module_importing(module_name: str) -> None:
+    """Mark a module as currently being imported."""
+    with _import_lock:
+        _importing_modules.add(module_name)
+
+def unmark_module_importing(module_name: str) -> None:
+    """Unmark a module as no longer being imported."""
+    with _import_lock:
+        _importing_modules.discard(module_name)
+
+def is_module_importing(module_name: str) -> bool:
+    """Check if a module is currently being imported."""
+    with _import_lock:
+        return module_name in _importing_modules
+
+class PartialModuleDetector:
+    """
+    Modular detector for partially initialized modules.
+    
+    Uses different strategies to detect if a module in sys.modules
+    is still being initialized and shouldn't be returned yet.
+    """
+    
+    def __init__(self, strategy: DetectionStrategy = DetectionStrategy.HYBRID):
+        self.strategy = strategy
+    
+    def is_partially_initialized(self, module_name: str, module: ModuleType) -> bool:
+        """
+        Check if module is partially initialized (still being imported).
+        
+        Args:
+            module_name: Name of the module
+            module: Module object from sys.modules
+            
+        Returns:
+            True if module is partially initialized, False if fully loaded
+        """
+        if self.strategy == DetectionStrategy.FRAME_STACK:
+            return self._check_frame_stack(module_name)
+        elif self.strategy == DetectionStrategy.ATTRIBUTE_CHECK:
+            return self._check_attributes(module_name, module)
+        elif self.strategy == DetectionStrategy.IMPORT_LOCK:
+            return self._check_import_lock(module_name)
+        elif self.strategy == DetectionStrategy.MODULE_STATE:
+            return self._check_module_state(module_name, module)
+        elif self.strategy == DetectionStrategy.HYBRID:
+            return self._check_hybrid(module_name, module)
+        else:
+            return False
+    
+    def _check_frame_stack(self, module_name: str) -> bool:
+        """
+        Strategy 1: Check call stack for import-related functions.
+        
+        If we're in _find_and_load, _load_unlocked, or exec_module,
+        the module is likely still being imported.
+        
+        CRITICAL: This checks if the CURRENT import call is for this module,
+        not just if we're in an import function.
+        """
+        try:
+            # Start from frame 2 (skip our own function and the caller)
+            frame = sys._getframe(2)
+            depth = 0
+            max_depth = 30  # Increased depth to catch deeper import chains
+            
+            while frame and depth < max_depth:
+                code = frame.f_code
+                func_name = code.co_name
+                
+                # Check for import-related functions in Python's importlib
+                import_keywords = [
+                    '_find_and_load', '_load_unlocked', 'exec_module',
+                    '_call_with_frames_removed', '_load_module_spec',
+                    '_intercepting_import', '__import__'
+                ]
+                
+                if any(keyword in func_name for keyword in import_keywords):
+                    # Check if this module is in the frame's locals or globals
+                    if hasattr(frame, 'f_locals'):
+                        locals_dict = frame.f_locals
+                        # Check various ways module name might appear
+                        frame_module_name = (
+                            locals_dict.get('name') or
+                            locals_dict.get('fullname') or
+                            locals_dict.get('__name__') or
+                            (locals_dict.get('module') and getattr(locals_dict.get('module'), '__name__', None))
+                        )
+                        
+                        if frame_module_name == module_name:
+                            return True
+                    
+                    # Also check globals
+                    if hasattr(frame, 'f_globals'):
+                        globals_dict = frame.f_globals
+                        if '__name__' in globals_dict and globals_dict.get('__name__') == module_name:
+                            return True
+                
+                frame = frame.f_back
+                depth += 1
+        except (AttributeError, ValueError):
+            # Frame inspection failed, assume not importing
+            pass
+        
+        return False
+    
+    def _check_attributes(self, module_name: str, module: ModuleType) -> bool:
+        """
+        Strategy 2: Check if module has expected attributes.
+        
+        A fully initialized module should have certain attributes.
+        If key attributes are missing, it might be partially initialized.
+        
+        CRITICAL: We need to be careful - some modules legitimately don't have
+        __file__ (namespace packages, built-ins). We only flag as partial if
+        we're CERTAIN it's not fully initialized.
+        """
+        module_dict = getattr(module, '__dict__', {})
+        
+        # Check for placeholder patterns (lazy loaders often add __getattr__)
+        if hasattr(module, '__getattr__'):
+            # If it has __getattr__ but very few attributes, it's likely a placeholder
+            if len(module_dict) <= 5:  # Only __name__, __loader__, __spec__, __getattr__, etc.
+                if not hasattr(module, '__file__') and not hasattr(module, '__path__'):
+                    # Not a namespace package and no file - likely placeholder
+                    return True
+        
+        # Check if module has __spec__ but loader hasn't executed yet
+        if hasattr(module, '__spec__') and module.__spec__ is not None:
+            spec = module.__spec__
+            # If loader exists but module dict is very small, it might not be fully loaded
+            if hasattr(spec, 'loader') and spec.loader is not None:
+                # Check if module dict is suspiciously small (only metadata, no actual content)
+                if len(module_dict) <= 3:
+                    # Only has __name__, __loader__, __spec__ - likely not executed
+                    if not hasattr(module, '__file__') and not hasattr(module, '__path__'):
+                        # Not a namespace package - likely partial
+                        return True
+        
+        # If module is in sys.modules but has no meaningful content, it's likely partial
+        # This is a heuristic - be conservative
+        if module_name in sys.modules:
+            # Check if module has been executed by looking for non-metadata attributes
+            metadata_attrs = {'__name__', '__loader__', '__spec__', '__package__', '__file__', '__path__', '__cached__'}
+            content_attrs = set(module_dict.keys()) - metadata_attrs
+            if len(content_attrs) == 0 and len(module_dict) > 0:
+                # Has metadata but no content - might be partial
+                # But be conservative - only flag if we're sure
+                if hasattr(module, '__loader__') and module.__loader__ is not None:
+                    # Has loader but no content - likely partial
+                    return True
+        
+        return False
+    
+    def _check_import_lock(self, module_name: str) -> bool:
+        """
+        Strategy 3: Use our own import tracking.
+        
+        Check if module is marked as currently being imported.
+        """
+        return is_module_importing(module_name)
+    
+    def _check_module_state(self, module_name: str, module: ModuleType) -> bool:
+        """
+        Strategy 4: Check module's internal state.
+        
+        Look at __spec__, __loader__, and other state indicators.
+        """
+        # If module doesn't have __spec__, it's likely not fully initialized
+        if not hasattr(module, '__spec__') or module.__spec__ is None:
+            # Exception: Some built-in modules don't have __spec__
+            if module_name not in sys.builtin_module_names:
+                return True
+        
+        # Check if module has __loader__ but loader hasn't executed
+        if hasattr(module, '__loader__') and module.__loader__ is not None:
+            loader = module.__loader__
+            # If loader has exec_module but module doesn't have expected attributes,
+            # it might not be fully executed
+            if hasattr(loader, 'exec_module'):
+                # Check if module has been executed by looking for common attributes
+                # This is heuristic - modules should have some content after execution
+                module_dict = getattr(module, '__dict__', {})
+                # If dict is mostly empty (only has __name__, __loader__, __spec__),
+                # it might not be fully initialized
+                if len(module_dict) <= 3:
+                    # Check if it's a legitimate empty module
+                    if '__file__' not in module_dict and '__path__' not in module_dict:
+                        return True
+        
+        return False
+    
+    def _check_hybrid(self, module_name: str, module: ModuleType) -> bool:
+        """
+        Strategy 5: Hybrid - combine multiple strategies.
+        
+        Returns True if ANY strategy indicates partial initialization.
+        This is the most conservative approach.
+        
+        NOTE: We check frame stack FIRST because it's most accurate for detecting
+        modules currently being imported. Import lock is secondary.
+        """
+        # Check frame stack first (most accurate for detecting active imports)
+        if self._check_frame_stack(module_name):
+            return True
+        
+        # Check attributes (fast, reliable)
+        if self._check_attributes(module_name, module):
+            return True
+        
+        # Check module state (medium speed)
+        if self._check_module_state(module_name, module):
+            return True
+        
+        # Check import lock last (may have false positives)
+        # Only use if other checks are inconclusive
+        if is_module_importing(module_name):
+            # Double-check with frame stack to avoid false positives
+            if self._check_frame_stack(module_name):
+                return True
+        
+        return False
+
+# Global detector instance (defaults to HYBRID strategy)
+_default_detector = PartialModuleDetector(DetectionStrategy.HYBRID)
+
+def is_partially_initialized(module_name: str, module: ModuleType, 
+                            strategy: Optional[DetectionStrategy] = None) -> bool:
+    """
+    Convenience function to check if module is partially initialized.
+    
+    Args:
+        module_name: Name of the module
+        module: Module object from sys.modules
+        strategy: Optional strategy override
+        
+    Returns:
+        True if module is partially initialized
+    """
+    if strategy:
+        detector = PartialModuleDetector(strategy)
+        return detector.is_partially_initialized(module_name, module)
+    return _default_detector.is_partially_initialized(module_name, module)
+

exonware/xwlazy/module/strategies/module_helper_lazy.py

@@ -14,7 +14,7 @@ import importlib
 import importlib.util
 import threading
 from types import ModuleType
-from typing import Any, Optional, Dict
+from typing import Any, Optional
 from ...module.base import AModuleHelperStrategy
 from ..data import ModuleData
 
@@ -28,8 +28,8 @@ class LazyHelper(AModuleHelperStrategy):
     
     def __init__(self):
         """Initialize lazy helper."""
-        self._cache: Dict[str, ModuleType] = {}
-        self._loading: Dict[str, bool] = {}
+        self._cache: dict[str, ModuleType] = {}
+        self._loading: dict[str, bool] = {}
         self._lock = threading.RLock()
     
     def load(self, module_path: str, package_helper: Any) -> ModuleType:

exonware/xwlazy/package/base.py

@@ -15,7 +15,7 @@ This module defines the abstract base class for package operations.
 import threading
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Dict, List, Optional, Any, Set, Tuple
+from typing import Optional, Any
 from types import ModuleType
 
 from ..defs import (
@@ -31,6 +31,7 @@ from ..contracts import (
     IDiscoveryStrategy,
     IPolicyStrategy,
     IMappingStrategy,
+    IInstallStrategy,
 )
 
 # =============================================================================
@@ -78,24 +79,24 @@ class APackageHelper(IPackageHelper, ABC):
         """
         # From APackageDiscovery
         self.project_root = Path(project_root) if project_root else self._find_project_root()
-        self.discovered_dependencies: Dict[str, DependencyInfo] = {}
-        self._discovery_sources: List[str] = []
-        self._cached_dependencies: Dict[str, str] = {}
-        self._file_mtimes: Dict[str, float] = {}
+        self.discovered_dependencies: dict[str, DependencyInfo] = {}
+        self._discovery_sources: list[str] = []
+        self._cached_dependencies: dict[str, str] = {}
+        self._file_mtimes: dict[str, float] = {}
         self._cache_valid = False
         
         # From APackageInstaller
         self._package_name = package_name
         self._enabled = False
         self._mode = LazyInstallMode.SMART
-        self._installed_packages: Set[str] = set()
-        self._failed_packages: Set[str] = set()
+        self._installed_packages: set[str] = set()
+        self._failed_packages: set[str] = set()
         
         # From APackageCache
-        self._cache: Dict[str, Any] = {}
+        self._cache: dict[str, Any] = {}
         
         # From APackageHelper
-        self._uninstalled_packages: Set[str] = set()
+        self._uninstalled_packages: set[str] = set()
         
         # Common
         self._lock = threading.RLock()
@@ -105,15 +106,15 @@ class APackageHelper(IPackageHelper, ABC):
     # ========================================================================
     
     def _find_project_root(self) -> Path:
-        """Find the project root directory by looking for markers."""
-        current = Path(__file__).parent.parent.parent
-        while current != current.parent:
-            if (current / 'pyproject.toml').exists() or (current / 'setup.py').exists():
-                return current
-            current = current.parent
-        return Path.cwd()
+        """
+        Find the project root directory by looking for markers.
+        
+        Uses the shared utility function from common.utils.
+        """
+        from ..common.utils import find_project_root
+        return find_project_root()
     
-    def discover_all_dependencies(self) -> Dict[str, str]:
+    def discover_all_dependencies(self) -> dict[str, str]:
         """
         Template method: Discover all dependencies from all sources.
         
@@ -186,7 +187,7 @@ class APackageHelper(IPackageHelper, ABC):
         """Update file modification times for cache validation (abstract step)."""
         pass
     
-    def get_discovery_sources(self) -> List[str]:
+    def get_discovery_sources(self) -> list[str]:
         """Get list of sources used for discovery."""
         return self._discovery_sources.copy()
     
@@ -194,9 +195,17 @@ class APackageHelper(IPackageHelper, ABC):
     # Package Installation Methods (from APackageInstaller)
     # ========================================================================
     
-    def get_package_name(self) -> str:
-        """Get the package name this instance is for."""
-        return self._package_name
+    def get_package_name(self, import_name: Optional[str] = None) -> Optional[str]:
+        """
+        Get package name.
+        If import_name is None, returns the package name this instance is for.
+        If import_name is provided, maps it to a package name (via IDependencyMapper).
+        """
+        if import_name is None:
+            return self._package_name
+        
+        # For IDependencyMapper implementation
+        raise NotImplementedError("Subclasses must implement get_package_name(import_name)")
     
     def set_mode(self, mode: LazyInstallMode) -> None:
         """Set the installation mode."""
@@ -236,7 +245,7 @@ class APackageHelper(IPackageHelper, ABC):
         pass
     
     @abstractmethod
-    def _check_security_policy(self, package_name: str) -> Tuple[bool, str]:
+    def _check_security_policy(self, package_name: str) -> tuple[bool, str]:
         """
         Check security policy for package (abstract method).
         
@@ -249,7 +258,7 @@ class APackageHelper(IPackageHelper, ABC):
         pass
     
     @abstractmethod
-    def _run_pip_install(self, package_name: str, args: List[str]) -> bool:
+    def _run_pip_install(self, package_name: str, args: list[str]) -> bool:
         """
         Run pip install with arguments (abstract method).
         
@@ -262,7 +271,7 @@ class APackageHelper(IPackageHelper, ABC):
         """
         pass
     
-    def get_stats(self) -> Dict[str, Any]:
+    def get_stats(self) -> dict[str, Any]:
         """Get installation statistics."""
         with self._lock:
             return {
@@ -548,7 +557,7 @@ class APackageHelper(IPackageHelper, ABC):
     # Note: Many methods from IPackageHelper are already implemented above.
     # The following are stubs that need concrete implementations:
     
-    def install_and_import(self, module_name: str, package_name: Optional[str] = None) -> Tuple[Optional[ModuleType], bool]:
+    def install_and_import(self, module_name: str, package_name: Optional[str] = None) -> tuple[Optional[ModuleType], bool]:
         """Install package and import module (from IPackageInstaller)."""
         raise NotImplementedError("Subclasses must implement install_and_import")
     
@@ -556,15 +565,15 @@ class APackageHelper(IPackageHelper, ABC):
         """Get package name for a given import name (from IPackageDiscovery)."""
         raise NotImplementedError("Subclasses must implement get_package_for_import")
     
-    def get_imports_for_package(self, package_name: str) -> List[str]:
+    def get_imports_for_package(self, package_name: str) -> list[str]:
         """Get all possible import names for a package (from IPackageDiscovery)."""
         raise NotImplementedError("Subclasses must implement get_imports_for_package")
     
-    def get_package_name(self, import_name: str) -> Optional[str]:
-        """Get package name for an import name (from IDependencyMapper)."""
-        raise NotImplementedError("Subclasses must implement get_package_name")
+    # def get_package_name(self, import_name: str) -> Optional[str]:
+    #    """Get package name for an import name (from IDependencyMapper)."""
+    #    raise NotImplementedError("Subclasses must implement get_package_name")
     
-    def get_import_names(self, package_name: str) -> List[str]:
+    def get_import_names(self, package_name: str) -> list[str]:
         """Get all import names for a package (from IDependencyMapper)."""
         raise NotImplementedError("Subclasses must implement get_import_names")
     
@@ -591,15 +600,15 @@ class APackageHelper(IPackageHelper, ABC):
         """Get full mode configuration for a package (from IConfigManager)."""
         raise NotImplementedError("Subclasses must implement get_mode_config")
     
-    def get_manifest_signature(self, package_name: str) -> Optional[Tuple[str, float, float]]:
+    def get_manifest_signature(self, package_name: str) -> Optional[tuple[str, float, float]]:
         """Get manifest file signature (from IManifestLoader)."""
         raise NotImplementedError("Subclasses must implement get_manifest_signature")
     
-    def get_shared_dependencies(self, package_name: str, signature: Optional[Tuple[str, float, float]] = None) -> Dict[str, str]:
+    def get_shared_dependencies(self, package_name: str, signature: Optional[tuple[str, float, float]] = None) -> dict[str, str]:
         """Get shared dependencies from manifest (from IManifestLoader)."""
         raise NotImplementedError("Subclasses must implement get_shared_dependencies")
     
-    def get_watched_prefixes(self, package_name: str) -> Tuple[str, ...]:
+    def get_watched_prefixes(self, package_name: str) -> tuple[str, ...]:
         """Get watched prefixes from manifest (from IManifestLoader)."""
         raise NotImplementedError("Subclasses must implement get_watched_prefixes")
 
@@ -662,12 +671,12 @@ class APackageManagerStrategy(IPackageManagerStrategy, ABC):
         ...
     
     @abstractmethod
-    def discover_dependencies(self) -> Dict[str, str]:
+    def discover_dependencies(self) -> dict[str, str]:
         """Discover dependencies."""
         ...
     
     @abstractmethod
-    def check_security_policy(self, package_name: str) -> Tuple[bool, str]:
+    def check_security_policy(self, package_name: str) -> tuple[bool, str]:
         """Check security policy."""
         ...
 
@@ -683,7 +692,7 @@ class AInstallExecutionStrategy(IInstallExecutionStrategy, ABC):
     """
     
     @abstractmethod
-    def execute_install(self, package_name: str, policy_args: List[str]) -> Any:
+    def execute_install(self, package_name: str, policy_args: list[str]) -> Any:
         """Execute installation of a package."""
         ...
     
@@ -714,7 +723,7 @@ class AInstallTimingStrategy(IInstallTimingStrategy, ABC):
         ...
     
     @abstractmethod
-    def get_install_priority(self, packages: List[str]) -> List[str]:
+    def get_install_priority(self, packages: list[str]) -> list[str]:
         """Get priority order for installing packages."""
         ...
 
@@ -730,7 +739,7 @@ class ADiscoveryStrategy(IDiscoveryStrategy, ABC):
     """
     
     @abstractmethod
-    def discover(self, project_root: Any) -> Dict[str, str]:
+    def discover(self, project_root: Any) -> dict[str, str]:
         """Discover dependencies from sources."""
         ...
     
@@ -751,12 +760,12 @@ class APolicyStrategy(IPolicyStrategy, ABC):
     """
     
     @abstractmethod
-    def is_allowed(self, package_name: str) -> Tuple[bool, str]:
+    def is_allowed(self, package_name: str) -> tuple[bool, str]:
         """Check if package is allowed to be installed."""
         ...
     
     @abstractmethod
-    def get_pip_args(self, package_name: str) -> List[str]:
+    def get_pip_args(self, package_name: str) -> list[str]:
         """Get pip arguments based on policy."""
         ...
 
@@ -777,7 +786,7 @@ class AMappingStrategy(IMappingStrategy, ABC):
         ...
     
     @abstractmethod
-    def map_package_to_imports(self, package_name: str) -> List[str]:
+    def map_package_to_imports(self, package_name: str) -> list[str]:
         """Map package name to possible import names."""
         ...
 
@@ -794,5 +803,61 @@ __all__ = [
     'ADiscoveryStrategy',
     'APolicyStrategy',
     'AMappingStrategy',
+    # Enhanced Strategy Interfaces for Runtime Swapping
+    'AInstallStrategy',
 ]
 
+# =============================================================================
+# ABSTRACT INSTALLATION STRATEGY (Enhanced for Runtime Swapping)
+# =============================================================================
+
+class AInstallStrategy(IInstallStrategy, ABC):
+    """
+    Abstract base class for installation strategies.
+    
+    Enables runtime strategy swapping for different installation methods
+    (pip, wheel, async, cached, etc.).
+    """
+    
+    @abstractmethod
+    def install(self, package_name: str, version: Optional[str] = None) -> bool:
+        """
+        Install a package.
+        
+        Args:
+            package_name: Package name to install
+            version: Optional version specification
+            
+        Returns:
+            True if installation successful, False otherwise
+        """
+        ...
+    
+    def can_install(self, package_name: str) -> bool:
+        """
+        Check if this strategy can install a package.
+        
+        Default implementation returns True.
+        Override for strategy-specific logic.
+        
+        Args:
+            package_name: Package name to check
+            
+        Returns:
+            True if can install, False otherwise
+        """
+        return True
+    
+    @abstractmethod
+    def uninstall(self, package_name: str) -> bool:
+        """
+        Uninstall a package.
+        
+        Args:
+            package_name: Package name to uninstall
+            
+        Returns:
+            True if uninstallation successful, False otherwise
+        """
+        ...
+

exonware/xwlazy/package/conf.py

@@ -23,7 +23,7 @@ import subprocess
 import sys
 import types
 import warnings
-from typing import Any, Dict, Optional
+from typing import Any, Optional
 
 # Import from new structure
 from .services.host_packages import refresh_host_package
@@ -56,14 +56,14 @@ class _PackageConfig:
         """Enable/disable lazy mode for this package."""
         if value:
             # Default to "smart" mode when enabling lazy install
-            config_package_lazy_install_enabled(self._package_name, True, mode="smart", install_hook=False)
-            install_import_hook(self._package_name)
+            # config_package_lazy_install_enabled will register package and install global hook
+            config_package_lazy_install_enabled(self._package_name, True, mode="smart", install_hook=True)
             refresh_host_package(self._package_name)
         else:
             config_package_lazy_install_enabled(self._package_name, False, install_hook=False)
             uninstall_import_hook(self._package_name)
 
-    def lazy_install_status(self) -> Dict[str, Any]:
+    def lazy_install_status(self) -> dict[str, Any]:
         """Return runtime status for this package."""
         return {
             "package": self._package_name,
@@ -112,7 +112,7 @@ class _LazyConfModule(types.ModuleType):
 
     def __init__(self, name: str, doc: Optional[str]) -> None:
         super().__init__(name, doc)
-        self._package_configs: Dict[str, _PackageConfig] = {}
+        self._package_configs: dict[str, _PackageConfig] = {}
         self._suppress_warnings: bool = True  # Default: suppress warnings
         self._original_stderr: Optional[Any] = None
         self._filtered_stderr: Optional[_FilteredStderr] = None
@@ -168,7 +168,7 @@ class _LazyConfModule(types.ModuleType):
         except Exception as exc:  # pragma: no cover
             print(f"[WARN] Could not uninstall exonware-xwlazy: {exc}")
 
-    def _get_global_lazy_status(self) -> Dict[str, Any]:
+    def _get_global_lazy_status(self) -> dict[str, Any]:
         """Return aggregate status for DX tooling."""
         installed = self._is_xwlazy_installed()
         # Check all known packages, not just those in _package_configs