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

exonware/__init__.py

@@ -10,7 +10,7 @@ This is a namespace package allowing multiple exonware subpackages
 to coexist (xwsystem, xwnode, xwdata, xwlazy, etc.)
 """
 
-# Make this a namespace package - DO NOT set __path__
+# Make this a namespace package FIRST
 # This allows both exonware.xwsystem and exonware.xwlazy to coexist
 __path__ = __import__('pkgutil').extend_path(__path__, __name__)
 
@@ -21,3 +21,22 @@ __author__ = 'Eng. Muhammad AlShehri'
 __email__ = 'connect@exonware.com'
 __company__ = 'eXonware.com'
 
+# NOW enable lazy mode (after namespace package is set up)
+import sys
+import importlib
+try:
+    # Use importlib to import after namespace is ready
+    if 'exonware.xwlazy' not in sys.modules:
+        xwlazy_module = importlib.import_module('exonware.xwlazy')
+        auto_enable_lazy = getattr(xwlazy_module, 'auto_enable_lazy', None)
+        if auto_enable_lazy:
+            auto_enable_lazy("xwsystem", mode="smart")
+            print("✅ Lazy mode enabled for xwsystem")
+    else:
+        # Module already loaded, use it directly
+        from exonware.xwlazy import auto_enable_lazy
+        auto_enable_lazy("xwsystem", mode="smart")
+        print("✅ Lazy mode enabled for xwsystem")
+except (ImportError, AttributeError):
+    print("❌ Lazy mode not enabled for xwsystem (xwlazy not installed)")
+    pass  # xwlazy not installed - silently continue

exonware/xwlazy/__init__.py

@@ -63,6 +63,10 @@ from .facade import (
     configure_lazy_mode,
     preload_modules,
     optimize_lazy_mode,
+    # One-line activation API
+    auto_enable_lazy,
+    # Lazy-loader compatible API
+    attach,
     # Public API functions
     enable_lazy_install,
     disable_lazy_install,
@@ -167,6 +171,10 @@ def __getattr__(name: str) -> Any:
     elif name == "XWRuntimeHelper":
         from .runtime import XWRuntimeHelper
         return XWRuntimeHelper
+    elif name == "manifest":
+        # Import manifest module for lazy access
+        from .package.services import manifest
+        return manifest
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 # Import core classes for advanced usage
@@ -210,7 +218,7 @@ from .module.importer_engine import (
     _mark_import_started,
     _mark_import_finished,
     _lazy_aware_import_module,
-    _patch_import_module,
+    # _patch_import_module removed - deprecated, use sys.meta_path hooks instead
     _unpatch_import_module,
 )
 
@@ -245,6 +253,10 @@ __all__ = [
     "configure_lazy_mode",
     "preload_modules",
     "optimize_lazy_mode",
+    # One-line activation API
+    "auto_enable_lazy",
+    # Lazy-loader compatible API
+    "attach",
     # Public API functions
     "enable_lazy_install",
     "disable_lazy_install",
@@ -361,7 +373,7 @@ __all__ = [
     "_mark_import_started",
     "_mark_import_finished",
     "_lazy_aware_import_module",
-    "_patch_import_module",
+    # "_patch_import_module",  # Removed - deprecated, use sys.meta_path hooks instead
     "_unpatch_import_module",
 ]
 

exonware/xwlazy/common/__init__.py

@@ -28,6 +28,11 @@ from .cache import (
     InstallationCache,
 )
 
+from .utils import (
+    find_project_root,
+    find_config_file,
+)
+
 __all__ = [
     # Logger
     'get_logger',
@@ -43,5 +48,8 @@ __all__ = [
     'MultiTierCache',
     'BytecodeCache',
     'InstallationCache',
+    # Utils
+    'find_project_root',
+    'find_config_file',
 ]
 

exonware/xwlazy/common/base.py

@@ -12,13 +12,21 @@ Abstract base classes for shared/common strategies.
 
 from abc import ABC, abstractmethod
 from typing import Optional, Any
-from ..contracts import ICachingStrategy
+from ..contracts import ICachingStrategy, ICacheStrategy
 
 # =============================================================================
 # ABSTRACT CACHING STRATEGY
 # =============================================================================
 
 class ACachingStrategy(ICachingStrategy, ABC):
+    """
+    Abstract base class for caching strategies (legacy name).
+    
+    Note: Use ACacheStrategy for new code (ICacheStrategy interface).
+    """
+    pass
+
+class ACacheStrategy(ICacheStrategy, ABC):
     """
     Abstract base class for caching strategies.
     
@@ -51,6 +59,7 @@ class ACachingStrategy(ICachingStrategy, ABC):
 # =============================================================================
 
 __all__ = [
-    'ACachingStrategy',
+    'ACachingStrategy',  # Legacy name
+    'ACacheStrategy',    # New name for ICacheStrategy interface
 ]
 

exonware/xwlazy/common/cache.py

@@ -23,7 +23,7 @@ import importlib
 import importlib.util
 import threading
 from pathlib import Path
-from typing import Dict, List, Optional, Tuple, Any, Set
+from typing import Optional, Any
 from collections import OrderedDict
 from queue import Queue
 
@@ -59,7 +59,7 @@ class MultiTierCache:
         self._l2_dir = l2_dir or Path.home() / ".xwlazy_cache"
         self._l2_dir.mkdir(parents=True, exist_ok=True)
         self._enable_l3 = enable_l3
-        self._l3_patterns: Dict[str, Tuple[int, float]] = {}
+        self._l3_patterns: dict[str, tuple[int, float]] = {}
         self._lock = threading.RLock()
         
         self._l2_write_queue: Queue = Queue()
@@ -192,7 +192,7 @@ class MultiTierCache:
                 for old_key, _ in sorted_patterns[:1000]:
                     del self._l3_patterns[old_key]
     
-    def get_predictive_keys(self, limit: int = 10) -> List[str]:
+    def get_predictive_keys(self, limit: int = 10) -> list[str]:
         """
         Get keys likely to be accessed soon (for preloading).
         
@@ -370,7 +370,7 @@ class InstallationCache:
         
         self._cache_file = cache_file
         self._lock = threading.RLock()
-        self._cache: Dict[str, Dict[str, Any]] = {}
+        self._cache: dict[str, dict[str, Any]] = {}
         self._dirty = False
         
         # Load cache on init
@@ -487,7 +487,7 @@ class InstallationCache:
             self._dirty = True
             self._save_cache()
     
-    def get_all_installed(self) -> Set[str]:
+    def get_all_installed(self) -> set[str]:
         """
         Get set of all packages marked as installed.
         

exonware/xwlazy/common/logger.py

@@ -17,7 +17,7 @@ import os
 import sys
 import logging
 import io
-from typing import Dict, Optional
+from typing import Optional
 from datetime import datetime
 
 # =============================================================================
@@ -37,7 +37,7 @@ _EMOJI_MAP = {
 }
 
 # Default log category states
-_CATEGORY_DEFAULTS: Dict[str, bool] = {
+_CATEGORY_DEFAULTS: dict[str, bool] = {
     "install": True,
     "hook": False,
     "enhance": False,
@@ -52,7 +52,7 @@ _CATEGORY_DEFAULTS: Dict[str, bool] = {
 # =============================================================================
 
 _configured = False
-_category_overrides: Dict[str, bool] = {}
+_category_overrides: dict[str, bool] = {}
 
 # =============================================================================
 # HELPER FUNCTIONS
@@ -186,7 +186,7 @@ def set_log_category(category: str, enabled: bool) -> None:
     """
     _category_overrides[_normalize_category(category)] = bool(enabled)
 
-def set_log_categories(overrides: Dict[str, bool]) -> None:
+def set_log_categories(overrides: dict[str, bool]) -> None:
     """
     Bulk update multiple log categories.
     
@@ -196,7 +196,7 @@ def set_log_categories(overrides: Dict[str, bool]) -> None:
     for category, enabled in overrides.items():
         set_log_category(category, enabled)
 
-def get_log_categories() -> Dict[str, bool]:
+def get_log_categories() -> dict[str, bool]:
     """
     Return the effective state for each built-in log category.
     

exonware/xwlazy/common/services/dependency_mapper.py

@@ -5,7 +5,7 @@ This module contains DependencyMapper class extracted from lazy_core.py Section
 """
 
 import threading
-from typing import Dict, List, Optional, Set, Tuple
+from typing import Optional
 
 # Lazy import to avoid circular dependency
 def _get_logger():
@@ -59,14 +59,14 @@ class DependencyMapper:
     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._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_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:
@@ -115,7 +115,7 @@ class DependencyMapper:
         manifest = loader.get_manifest(self._package_name)
         current_generation = loader.generation
 
-        dependencies: Dict[str, str] = {}
+        dependencies: dict[str, str] = {}
         manifest_empty = True
         if manifest and manifest.dependencies:
             dependencies = {
@@ -143,7 +143,7 @@ class DependencyMapper:
             _cache_spec_if_missing(module_name)
         return needs_cache
 
-    DENY_LIST: Set[str] = {
+    DENY_LIST: set[str] = {
         # POSIX-only modules that don't exist on Windows but try to auto-install
         "pwd",
         "grp",
@@ -191,7 +191,9 @@ class DependencyMapper:
         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)
+        4. Discovery mappings (automatic discovery from project configs)
+        5. Common mappings (quick access list - works without project configs)
+        6. Fallback to import_name itself
         """
         if self._should_skip_auto_install(import_name):
             return None
@@ -206,24 +208,40 @@ class DependencyMapper:
         if manifest_hit:
             return manifest_hit
         
-        # Check spec cache - if module already exists, skip auto-install
+        # Check common mappings BEFORE spec cache (common mappings are reliable)
+        # This is important for exonware projects to work immediately
+        # Common mappings take precedence over spec cache because spec cache can be stale
+        discovery = self._get_discovery()
+        common_mappings = getattr(discovery, 'COMMON_MAPPINGS', {})
+        common_hit = common_mappings.get(import_name)
+        if common_hit:
+            return common_hit
+        
+        # Check spec cache - if module already exists AND we don't have a common mapping, skip auto-install
+        # Note: We check this AFTER common mappings because spec cache can be stale after uninstallation
         if _spec_cache_get(import_name):
             return None
 
+        # Try discovery mappings (from project configs)
         self._ensure_mappings_cached()
-        return self._import_package_mapping.get(import_name, import_name)
+        discovery_hit = self._import_package_mapping.get(import_name)
+        if discovery_hit:
+            return discovery_hit
+        
+        # Fallback: assume import name matches package name
+        return import_name
     
-    def get_import_names(self, package_name: str) -> List[str]:
+    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]]:
+    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]:
+    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()

exonware/xwlazy/common/services/install_async_utils.py

@@ -31,6 +31,11 @@ def _ensure_logging_initialized():
     global logger
     if logger is None:
         logger = _get_logger()
+        # Fallback if get_logger returns None (should not happen but safety first)
+        if logger is None:
+            import logging
+            logger = logging.getLogger("xwlazy.install_async_utils.fallback")
+            logger.addHandler(logging.NullHandler())
 
 async def get_package_size_mb(package_name: str) -> Optional[float]:
     """

exonware/xwlazy/common/services/install_cache_utils.py

@@ -19,7 +19,7 @@ import tempfile
 import subprocess
 import zipfile
 from pathlib import Path
-from typing import Optional, List
+from typing import Optional
 from contextlib import suppress
 
 # Lazy imports
@@ -77,7 +77,7 @@ def get_site_packages_dir() -> Path:
     path.mkdir(parents=True, exist_ok=True)
     return path
 
-def pip_install_from_path(wheel_path: Path, policy_args: Optional[List[str]] = None) -> bool:
+def pip_install_from_path(wheel_path: Path, policy_args: Optional[list[str]] = None) -> bool:
     """Install a wheel file using pip."""
     try:
         pip_args = [
@@ -104,7 +104,7 @@ def pip_install_from_path(wheel_path: Path, policy_args: Optional[List[str]] = N
 
 def ensure_cached_wheel(
     package_name: str,
-    policy_args: Optional[List[str]] = None,
+    policy_args: Optional[list[str]] = None,
     cache_dir: Optional[Path] = None
 ) -> Optional[Path]:
     """Ensure a wheel is cached, downloading it if necessary."""
@@ -220,7 +220,7 @@ def has_cached_install_tree(
 
 def install_from_cached_wheel(
     package_name: str,
-    policy_args: Optional[List[str]] = None,
+    policy_args: Optional[list[str]] = None,
     cache_dir: Optional[Path] = None
 ) -> bool:
     """Install from a cached wheel file."""

exonware/xwlazy/common/services/spec_cache.py

@@ -21,7 +21,7 @@ import importlib
 import importlib.machinery
 import importlib.util
 from pathlib import Path
-from typing import Optional, Tuple
+from typing import Optional
 from collections import OrderedDict
 from functools import lru_cache
 
@@ -31,7 +31,7 @@ _SPEC_CACHE_TTL = float(os.environ.get("XWLAZY_SPEC_CACHE_TTL", "60") or 60.0)
 
 # Cache storage
 _spec_cache_lock = threading.RLock()
-_spec_cache: OrderedDict[str, Tuple[importlib.machinery.ModuleSpec, float]] = OrderedDict()
+_spec_cache: OrderedDict[str, tuple[importlib.machinery.ModuleSpec, float]] = OrderedDict()
 
 # Multi-level cache: L1 (in-memory) + L2 (disk)
 _CACHE_L2_DIR = Path(

exonware/xwlazy/common/services/state_manager.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 import os
 from pathlib import Path
-from typing import Dict, Optional
+from typing import Optional
 
 def _get_base_config_dir() -> Path:
     """Determine a cross-platform directory for storing lazy configuration."""
@@ -25,12 +25,12 @@ class LazyStateManager:
     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()
+        self._state: dict[str, dict[str, bool]] = self._load_state()
 
     # --------------------------------------------------------------------- #
     # Persistence helpers
     # --------------------------------------------------------------------- #
-    def _load_state(self) -> Dict[str, Dict[str, bool]]:
+    def _load_state(self) -> dict[str, dict[str, bool]]:
         if not self._state_path.exists():
             return {}
         try:
@@ -47,7 +47,7 @@ class LazyStateManager:
         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]:
+    def _ensure_entry(self) -> dict[str, bool]:
         return self._state.setdefault(self._package, {})
 
     # --------------------------------------------------------------------- #

exonware/xwlazy/common/strategies/caching_dict.py

@@ -11,7 +11,7 @@ Simple dict-based cache implementation.
 Works with ANY data type (modules, packages, etc.).
 """
 
-from typing import Dict, Optional, Any
+from typing import Optional, Any
 from ...common.base import ACachingStrategy
 
 class DictCache(ACachingStrategy):
@@ -24,7 +24,7 @@ class DictCache(ACachingStrategy):
     
     def __init__(self):
         """Initialize dict cache."""
-        self._cache: Dict[str, Any] = {}
+        self._cache: dict[str, Any] = {}
     
     def get(self, key: str) -> Optional[Any]:
         """Get value from cache."""

exonware/xwlazy/common/strategies/caching_lfu.py

@@ -11,7 +11,7 @@ LFU cache implementation with size limit.
 Works with ANY data type (modules, packages, etc.).
 """
 
-from typing import Dict, Optional, Any
+from typing import Optional, Any
 from collections import Counter
 from ...common.base import ACachingStrategy
 
@@ -30,7 +30,7 @@ class LFUCache(ACachingStrategy):
         Args:
             max_size: Maximum number of items in cache
         """
-        self._cache: Dict[str, Any] = {}
+        self._cache: dict[str, Any] = {}
         self._freq: Counter[str] = Counter()
         self._max_size = max_size
     

exonware/xwlazy/common/strategies/caching_ttl.py

@@ -12,7 +12,7 @@ Works with ANY data type (modules, packages, etc.).
 """
 
 import time
-from typing import Dict, Optional, Any, Tuple
+from typing import Optional, Any
 from ...common.base import ACachingStrategy
 
 class TTLCache(ACachingStrategy):
@@ -30,7 +30,7 @@ class TTLCache(ACachingStrategy):
         Args:
             ttl_seconds: Time-to-live in seconds (default: 1 hour)
         """
-        self._cache: Dict[str, Tuple[Any, float]] = {}  # (value, expiry_time)
+        self._cache: dict[str, tuple[Any, float]] = {}  # (value, expiry_time)
         self._ttl = ttl_seconds
     
     def get(self, key: str) -> Optional[Any]:

exonware/xwlazy/common/utils.py

@@ -0,0 +1,142 @@
+"""
+Common utility functions for xwlazy.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+
+This module provides shared utility functions used across xwlazy,
+including path operations and project root detection.
+"""
+
+import sys
+from pathlib import Path
+from typing import Optional
+
+
+def find_project_root(start_path: Optional[Path] = None) -> Path:
+    """
+    Find the project root directory by looking for markers.
+    
+    Package-agnostic: Finds root from running script location, not xwlazy's location.
+    This function is designed to work with any project that uses xwlazy.
+    
+    Args:
+        start_path: Optional starting path. If None, attempts to find from:
+            1. __main__ module location
+            2. sys.path[0] (script directory)
+            3. Current working directory
+    
+    Returns:
+        Path to the project root directory
+        
+    Examples:
+        >>> root = find_project_root()
+        >>> # Finds pyproject.toml or setup.py from running script
+        
+        >>> root = find_project_root(Path(__file__).parent)
+        >>> # Finds from specific starting path
+    """
+    start_paths = []
+    
+    # If explicit start path provided, use it first
+    if start_path:
+        try:
+            start_paths.append(start_path.resolve())
+        except (ValueError, OSError):
+            pass
+    
+    # Option 1: Use __main__ module location if available
+    if '__main__' in sys.modules:
+        main_module = sys.modules['__main__']
+        if hasattr(main_module, '__file__') and main_module.__file__:
+            try:
+                main_path = Path(main_module.__file__).resolve().parent
+                start_paths.append(main_path)
+            except (ValueError, OSError):
+                pass
+    
+    # Option 2: Use sys.path[0] (script directory)
+    if sys.path and sys.path[0]:
+        try:
+            script_path = Path(sys.path[0]).resolve()
+            if script_path.exists():
+                start_paths.append(script_path)
+        except (ValueError, OSError):
+            pass
+    
+    # Option 3: Use current working directory
+    try:
+        cwd = Path.cwd().resolve()
+        if cwd.exists():
+            start_paths.append(cwd)
+    except (OSError, ValueError):
+        pass
+    
+    # Option 4: Fallback to xwlazy location (for backwards compatibility)
+    try:
+        xwlazy_path = Path(__file__).parent.parent.parent.parent
+        if xwlazy_path.exists():
+            start_paths.append(xwlazy_path)
+    except (ValueError, OSError):
+        pass
+    
+    # Try each starting path
+    for start_path_item in start_paths:
+        current = start_path_item
+        max_levels = 20  # Prevent infinite loops
+        levels = 0
+        
+        while current != current.parent and levels < max_levels:
+            # Check for project markers
+            markers = ['pyproject.toml', 'setup.py', 'requirements.txt', '.git']
+            if any((current / marker).exists() for marker in markers):
+                return current
+            current = current.parent
+            levels += 1
+    
+    # Final fallback: current working directory
+    try:
+        return Path.cwd().resolve()
+    except (OSError, ValueError):
+        # Ultimate fallback: return the xwlazy package directory
+        return Path(__file__).parent.parent.parent.parent
+
+
+def find_config_file(filename: str, start_path: Optional[Path] = None) -> Optional[Path]:
+    """
+    Find a configuration file by walking up from the start path.
+    
+    Args:
+        filename: Name of the config file to find (e.g., 'pyproject.toml', 'requirements.txt')
+        start_path: Optional starting path. If None, uses find_project_root()
+    
+    Returns:
+        Path to the config file if found, None otherwise
+        
+    Examples:
+        >>> pyproject = find_config_file('pyproject.toml')
+        >>> requirements = find_config_file('requirements.txt')
+    """
+    if start_path is None:
+        root = find_project_root()
+    else:
+        root = start_path
+    
+    # Check in root and walk up
+    current = root
+    max_levels = 10
+    levels = 0
+    
+    while current != current.parent and levels < max_levels:
+        config_path = current / filename
+        if config_path.exists():
+            return config_path
+        current = current.parent
+        levels += 1
+    
+    return None
+
+
+__all__ = ['find_project_root', 'find_config_file']
+

exonware/xwlazy/config.py

@@ -15,7 +15,7 @@ following GUIDE_ARCH.md structure.
 
 from __future__ import annotations
 
-from typing import Optional, Any, Dict
+from typing import Optional, Any
 
 # Import LazyConfig dataclass from defs.py
 from .defs import LazyConfig as _LazyConfigBase