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

exonware/xwlazy/common/services/keyword_detection.py

@@ -0,0 +1,292 @@
+"""
+Keyword-based detection for lazy installation.
+
+This module provides functionality to detect packages that opt-in to lazy loading
+by including specific keywords in their metadata.
+"""
+
+import os
+import sys
+import threading
+from typing import Optional
+
+from ..logger import get_logger
+
+logger = get_logger("xwlazy.discovery.keyword")
+
+# Global configuration
+_KEYWORD_DETECTION_ENABLED: bool = True
+_KEYWORD_TO_CHECK: str = "xwlazy-enabled"
+_keyword_config_lock = threading.RLock()
+
+# Detection cache
+_lazy_detection_cache: dict[str, bool] = {}
+_lazy_detection_lock = threading.RLock()
+
+
+def _check_package_keywords(package_name: Optional[str] = None, keyword: Optional[str] = None) -> bool:
+    """
+    Check if any installed package has the specified keyword in its metadata.
+    
+    This allows packages to opt-in to lazy loading by adding:
+    [project]
+    keywords = ["xwlazy-enabled"]
+    
+    in their pyproject.toml file. The keyword is stored in the package's
+    metadata when installed.
+    
+    Args:
+        package_name: The package name to check (or None to check all packages)
+        keyword: The keyword to look for (default: uses _KEYWORD_TO_CHECK)
+    
+    Returns:
+        True if the keyword is found in any relevant package's metadata
+    """
+    if not _KEYWORD_DETECTION_ENABLED:
+        return False
+    
+    if sys.version_info < (3, 8):
+        return False
+    
+    try:
+        from importlib import metadata
+    except Exception as exc:
+        logger.debug(f"importlib.metadata unavailable for keyword detection: {exc}")
+        return False
+    
+    with _keyword_config_lock:
+        search_keyword = (keyword or _KEYWORD_TO_CHECK).lower()
+    
+    try:
+        if package_name:
+            # Check specific package
+            try:
+                dist = metadata.distribution(package_name)
+                keywords = dist.metadata.get_all('Keywords', [])
+                if keywords:
+                    # Keywords can be a single string or list
+                    all_keywords = []
+                    for kw in keywords:
+                        if isinstance(kw, str):
+                            # Split comma-separated keywords
+                            all_keywords.extend(k.strip().lower() for k in kw.split(','))
+                        else:
+                            all_keywords.append(str(kw).lower())
+                    
+                    if search_keyword in all_keywords:
+                        logger.info(f"✅ Detected '{search_keyword}' keyword in package: {package_name}")
+                        return True
+            except metadata.PackageNotFoundError:
+                return False
+        else:
+            # Check all installed packages
+            for dist in metadata.distributions():
+                try:
+                    keywords = dist.metadata.get_all('Keywords', [])
+                    if keywords:
+                        all_keywords = []
+                        for kw in keywords:
+                            if isinstance(kw, str):
+                                all_keywords.extend(k.strip().lower() for k in kw.split(','))
+                            else:
+                                all_keywords.append(str(kw).lower())
+                        
+                        if search_keyword in all_keywords:
+                            package_found = dist.metadata.get('Name', 'unknown')
+                            logger.info(f"✅ Detected '{search_keyword}' keyword in package: {package_found}")
+                            return True
+                except Exception:
+                    continue
+    except Exception as exc:
+        logger.debug(f"Failed to check package keywords: {exc}")
+    
+    return False
+
+
+def _lazy_marker_installed() -> bool:
+    """Check if the exonware-xwlazy marker package is installed."""
+    if sys.version_info < (3, 8):
+        return False
+
+    try:
+        from importlib import metadata
+    except Exception as exc:
+        logger.debug(f"importlib.metadata unavailable for lazy detection: {exc}")
+        return False
+
+    try:
+        metadata.distribution("exonware-xwlazy")
+        logger.info("✅ Detected exonware-xwlazy marker package")
+        return True
+    except metadata.PackageNotFoundError:
+        logger.debug("❌ exonware-xwlazy marker package not installed")
+        return False
+
+
+def _lazy_env_override(package_name: str) -> Optional[bool]:
+    """Check environment variable override for lazy installation."""
+    env_var = f"{package_name.upper()}_LAZY_INSTALL"
+    raw_value = os.environ.get(env_var)
+    if raw_value is None:
+        return None
+
+    normalized = raw_value.strip().lower()
+    if normalized in ("true", "1", "yes", "on"):
+        return True
+    if normalized in ("false", "0", "no", "off"):
+        return False
+    return None
+
+
+def _detect_meta_info_mode(package_name: str) -> Optional[str]:
+    """
+    Detect lazy mode from package metadata keywords.
+    
+    Checks for keywords like:
+    - xwlazy-load-install-uninstall (clean mode)
+    - xwlazy-lite (lite mode)
+    - xwlazy-smart (smart mode)
+    - xwlazy-full (full mode)
+    - xwlazy-auto (auto mode)
+    
+    Returns:
+        Mode string or None if not found
+    """
+    try:
+        import importlib.metadata
+        try:
+            dist = importlib.metadata.distribution(package_name)
+            keywords = dist.metadata.get_all("Keywords", [])
+            if not keywords:
+                return None
+            
+            keyword_str = " ".join(keywords).lower()
+            
+            if "xwlazy-load-install-uninstall" in keyword_str:
+                return "clean"
+            if "xwlazy-lite" in keyword_str:
+                return "lite"
+            if "xwlazy-smart" in keyword_str:
+                return "smart"
+            if "xwlazy-full" in keyword_str:
+                return "full"
+            if "xwlazy-auto" in keyword_str:
+                return "auto"
+        except importlib.metadata.PackageNotFoundError:
+            return None
+    except Exception:
+        pass
+    return None
+
+
+def enable_keyword_detection(enabled: bool = True, keyword: Optional[str] = None) -> None:
+    """
+    Enable/disable keyword-based auto-detection of lazy loading.
+    
+    When enabled, xwlazy will check installed packages for a keyword
+    (default: "xwlazy-enabled") in their metadata. Packages can opt-in
+    by adding the keyword to their pyproject.toml:
+    
+    [project]
+    keywords = ["xwlazy-enabled"]
+    
+    Args:
+        enabled: Whether to enable keyword detection (default: True)
+        keyword: Custom keyword to check (default: "xwlazy-enabled")
+    """
+    global _KEYWORD_DETECTION_ENABLED, _KEYWORD_TO_CHECK
+    with _keyword_config_lock:
+        _KEYWORD_DETECTION_ENABLED = enabled
+        if keyword is not None:
+            _KEYWORD_TO_CHECK = keyword
+        # Clear cache to force re-detection
+        with _lazy_detection_lock:
+            _lazy_detection_cache.clear()
+
+
+def is_keyword_detection_enabled() -> bool:
+    """Return whether keyword-based detection is enabled."""
+    with _keyword_config_lock:
+        return _KEYWORD_DETECTION_ENABLED
+
+
+def get_keyword_detection_keyword() -> str:
+    """Get the keyword currently being checked for auto-detection."""
+    with _keyword_config_lock:
+        return _KEYWORD_TO_CHECK
+
+
+def check_package_keywords(package_name: Optional[str] = None, keyword: Optional[str] = None) -> bool:
+    """
+    Check if a package (or any package) has the specified keyword in its metadata.
+    
+    This is the public API for the keyword detection functionality.
+    
+    Args:
+        package_name: The package name to check (or None to check all packages)
+        keyword: The keyword to look for (default: uses configured keyword)
+    
+    Returns:
+        True if the keyword is found in the package's metadata
+    """
+    return _check_package_keywords(package_name, keyword)
+
+
+def _detect_lazy_installation(package_name: str) -> bool:
+    """
+    Detect if lazy installation should be enabled for a package.
+    
+    This function checks multiple sources in order:
+    1. Environment variable override
+    2. Manual state (from state manager)
+    3. Cached auto state
+    4. Marker package detection
+    5. Keyword detection
+    
+    Args:
+        package_name: The package name to check
+    
+    Returns:
+        True if lazy installation should be enabled
+    """
+    with _lazy_detection_lock:
+        cached = _lazy_detection_cache.get(package_name)
+        if cached is not None:
+            return cached
+
+    env_override = _lazy_env_override(package_name)
+    if env_override is not None:
+        with _lazy_detection_lock:
+            _lazy_detection_cache[package_name] = env_override
+        return env_override
+
+    from .state_manager import LazyStateManager
+    state_manager = LazyStateManager(package_name)
+    manual_state = state_manager.get_manual_state()
+    if manual_state is not None:
+        with _lazy_detection_lock:
+            _lazy_detection_cache[package_name] = manual_state
+        return manual_state
+
+    cached_state = state_manager.get_cached_auto_state()
+    if cached_state is not None:
+        with _lazy_detection_lock:
+            _lazy_detection_cache[package_name] = cached_state
+        return cached_state
+
+    # Check marker package first (existing behavior)
+    marker_detected = _lazy_marker_installed()
+    
+    # Also check for keyword in package metadata (new feature)
+    keyword_detected = _check_package_keywords(package_name)
+    
+    # Enable if either marker package OR keyword is found
+    detected = marker_detected or keyword_detected
+    
+    state_manager.set_auto_state(detected)
+
+    with _lazy_detection_lock:
+        _lazy_detection_cache[package_name] = detected
+
+    return detected
+

exonware/xwlazy/common/services/spec_cache.py

@@ -0,0 +1,173 @@
+"""
+#exonware/xwlazy/src/exonware/xwlazy/discovery/spec_cache.py
+
+Spec cache utilities for module specification caching.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 10-Oct-2025
+
+This module provides multi-level caching (L1: memory, L2: disk) for module specs
+to optimize import performance.
+"""
+
+import os
+import sys
+import time
+import threading
+import importlib
+import importlib.machinery
+import importlib.util
+from pathlib import Path
+from typing import Optional, Tuple
+from collections import OrderedDict
+from functools import lru_cache
+
+# Environment variables
+_SPEC_CACHE_MAX = int(os.environ.get("XWLAZY_SPEC_CACHE_MAX", "512") or 512)
+_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()
+
+# Multi-level cache: L1 (in-memory) + L2 (disk)
+_CACHE_L2_DIR = Path(
+    os.environ.get(
+        "XWLAZY_CACHE_DIR",
+        os.path.join(os.path.expanduser("~"), ".xwlazy", "cache"),
+    )
+)
+_CACHE_L2_DIR.mkdir(parents=True, exist_ok=True)
+
+# Stdlib module set
+try:
+    _STDLIB_MODULE_SET: set[str] = set(sys.stdlib_module_names)  # type: ignore[attr-defined]
+except AttributeError:
+    _STDLIB_MODULE_SET = set()
+_STDLIB_MODULE_SET.update(sys.builtin_module_names)
+
+
+@lru_cache(maxsize=1024)
+def _cached_stdlib_check(module_name: str) -> bool:
+    """Check if module is part of stdlib or built-in modules."""
+    try:
+        spec = importlib.util.find_spec(module_name)
+        if spec is None:
+            return False
+        if spec.origin in ("built-in", None):
+            return True
+        origin = spec.origin or ""
+        return (
+            "python" in origin.lower()
+            and "site-packages" not in origin.lower()
+            and "dist-packages" not in origin.lower()
+        )
+    except Exception:
+        return False
+
+
+def _spec_cache_prune_locked(now: Optional[float] = None) -> None:
+    """Prune expired entries from spec cache (must be called with lock held)."""
+    if not _spec_cache:
+        return
+    current = now or time.monotonic()
+    while _spec_cache:
+        fullname, (_, ts) = next(iter(_spec_cache.items()))
+        if current - ts <= _SPEC_CACHE_TTL and len(_spec_cache) <= _SPEC_CACHE_MAX:
+            break
+        _spec_cache.popitem(last=False)
+
+
+def _spec_cache_get(fullname: str) -> Optional[importlib.machinery.ModuleSpec]:
+    """Get spec from multi-level cache (L1: memory, L2: disk)."""
+    with _spec_cache_lock:
+        _spec_cache_prune_locked()
+        entry = _spec_cache.get(fullname)
+        if entry is not None:
+            spec, _ = entry
+            _spec_cache.move_to_end(fullname)
+            return spec
+        
+        # L2 cache: Check disk cache
+        try:
+            cache_file = _CACHE_L2_DIR / f"{fullname.replace('.', '_')}.spec"
+            if cache_file.exists():
+                mtime = cache_file.stat().st_mtime
+                age = time.time() - mtime
+                if age < _SPEC_CACHE_TTL:
+                    try:
+                        import pickle
+                        with open(cache_file, 'rb') as f:
+                            spec = pickle.load(f)
+                        # Promote to L1 cache
+                        _spec_cache[fullname] = (spec, time.monotonic())
+                        _spec_cache.move_to_end(fullname)
+                        return spec
+                    except Exception:
+                        pass
+        except Exception:
+            pass
+        
+        return None
+
+
+def _spec_cache_put(fullname: str, spec: Optional[importlib.machinery.ModuleSpec]) -> None:
+    """Put spec in multi-level cache (L1: memory, L2: disk)."""
+    if spec is None:
+        return
+    with _spec_cache_lock:
+        # L1 cache: In-memory
+        _spec_cache[fullname] = (spec, time.monotonic())
+        _spec_cache.move_to_end(fullname)
+        _spec_cache_prune_locked()
+        
+        # L2 cache: Disk (async, non-blocking)
+        try:
+            cache_file = _CACHE_L2_DIR / f"{fullname.replace('.', '_')}.spec"
+            import pickle
+            # Use protocol 5 for better performance
+            with open(cache_file, 'wb') as f:
+                pickle.dump(spec, f, protocol=5)
+        except Exception:
+            pass  # Fail silently for disk cache
+
+
+def _spec_cache_clear(fullname: Optional[str] = None) -> None:
+    """Clear spec cache entries."""
+    with _spec_cache_lock:
+        if fullname is None:
+            _spec_cache.clear()
+        else:
+            _spec_cache.pop(fullname, None)
+
+
+def _cache_spec_if_missing(fullname: str) -> None:
+    """Ensure a ModuleSpec is cached for a known-good module."""
+    if _spec_cache_get(fullname):
+        return
+    try:
+        spec = importlib.util.find_spec(fullname)
+    except Exception:
+        spec = None
+    if spec is not None:
+        _spec_cache_put(fullname, spec)
+
+
+def get_stdlib_module_set() -> set[str]:
+    """Get the set of stdlib module names."""
+    return _STDLIB_MODULE_SET.copy()
+
+
+__all__ = [
+    '_cached_stdlib_check',
+    '_spec_cache_get',
+    '_spec_cache_put',
+    '_spec_cache_clear',
+    '_spec_cache_prune_locked',
+    '_cache_spec_if_missing',
+    'get_stdlib_module_set',
+]
+

exonware/xwlazy/common/strategies/__init__.py

@@ -0,0 +1,28 @@
+"""
+Common Caching Strategies - Shared by modules and packages.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+Generic caching strategies that work with ANY data type.
+"""
+
+from .caching_dict import DictCache
+from .caching_lru import LRUCache
+from .caching_lfu import LFUCache
+from .caching_ttl import TTLCache
+from .caching_multitier import MultiTierCacheStrategy
+from .caching_installation import InstallationCacheWrapper
+
+__all__ = [
+    'DictCache',
+    'LRUCache',
+    'LFUCache',
+    'TTLCache',
+    'MultiTierCacheStrategy',
+    'InstallationCacheWrapper',
+]
+

exonware/xwlazy/common/strategies/caching_dict.py

@@ -0,0 +1,45 @@
+"""
+Dict Cache Strategy - Simple dictionary-based caching.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+Simple dict-based cache implementation.
+Works with ANY data type (modules, packages, etc.).
+"""
+
+from typing import Dict, Optional, Any
+from ...common.base import ACachingStrategy
+
+
+class DictCache(ACachingStrategy):
+    """
+    Simple dictionary-based cache.
+    
+    No eviction policy - grows unbounded.
+    Use for small applications or when memory is not a concern.
+    """
+    
+    def __init__(self):
+        """Initialize dict cache."""
+        self._cache: Dict[str, Any] = {}
+    
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache."""
+        return self._cache.get(key)
+    
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache."""
+        self._cache[key] = value
+    
+    def invalidate(self, key: str) -> None:
+        """Invalidate cached value."""
+        self._cache.pop(key, None)
+    
+    def clear(self) -> None:
+        """Clear all cached values."""
+        self._cache.clear()
+

exonware/xwlazy/common/strategies/caching_installation.py

@@ -0,0 +1,89 @@
+"""
+Installation Cache Strategy - Wrapper for existing InstallationCache.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+Wraps existing InstallationCache to implement ICachingStrategy interface.
+"""
+
+from typing import Optional, Any
+from pathlib import Path
+from ..cache import InstallationCache
+from ..base import ACachingStrategy
+from ...package.data import PackageData
+
+
+class InstallationCacheWrapper(ACachingStrategy):
+    """
+    Installation cache strategy wrapper.
+    
+    Wraps existing InstallationCache to implement ICachingStrategy interface.
+    Used for package installation status caching.
+    """
+    
+    def __init__(self, cache_file: Optional[Path] = None):
+        """
+        Initialize installation cache wrapper.
+        
+        Args:
+            cache_file: Optional path to cache file
+        """
+        self._cache = InstallationCache(cache_file)
+    
+    def get(self, key: str) -> Optional[Any]:
+        """
+        Get package from cache.
+        
+        Args:
+            key: Package name
+            
+        Returns:
+            PackageData if found, None otherwise
+        """
+        if self._cache.is_installed(key):
+            version = self._cache.get_version(key)
+            return PackageData(
+                name=key,
+                installed=True,
+                version=version
+            )
+        return None
+    
+    def set(self, key: str, value: Any) -> None:
+        """
+        Cache a package.
+        
+        Args:
+            key: Package name
+            value: PackageData or dict with installed/version info
+        """
+        if isinstance(value, PackageData):
+            if value.installed:
+                self._cache.mark_installed(key, value.version)
+            else:
+                self._cache.mark_uninstalled(key)
+        elif isinstance(value, dict):
+            if value.get('installed', False):
+                self._cache.mark_installed(key, value.get('version'))
+            else:
+                self._cache.mark_uninstalled(key)
+    
+    def invalidate(self, key: str) -> None:
+        """
+        Invalidate cached package.
+        
+        Args:
+            key: Package name
+        """
+        self._cache.mark_uninstalled(key)
+    
+    def clear(self) -> None:
+        """Clear all cached packages."""
+        # InstallationCache doesn't have clear, so we'd need to extend it
+        # For now, just mark all as uninstalled (would need cache iteration)
+        pass
+

exonware/xwlazy/common/strategies/caching_lfu.py

@@ -0,0 +1,67 @@
+"""
+LFU Cache Strategy - Least Frequently Used eviction.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+LFU cache implementation with size limit.
+Works with ANY data type (modules, packages, etc.).
+"""
+
+from typing import Dict, Optional, Any
+from collections import Counter
+from ...common.base import ACachingStrategy
+
+
+class LFUCache(ACachingStrategy):
+    """
+    LFU (Least Frequently Used) cache with size limit.
+    
+    Evicts least frequently accessed items when cache is full.
+    Good for access pattern-based caching.
+    """
+    
+    def __init__(self, max_size: int = 1000):
+        """
+        Initialize LFU cache.
+        
+        Args:
+            max_size: Maximum number of items in cache
+        """
+        self._cache: Dict[str, Any] = {}
+        self._freq: Counter[str] = Counter()
+        self._max_size = max_size
+    
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache (increments frequency)."""
+        if key in self._cache:
+            self._freq[key] += 1
+            return self._cache[key]
+        return None
+    
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache (evicts least frequent if full)."""
+        if key not in self._cache and len(self._cache) >= self._max_size:
+            # Evict least frequent
+            if self._freq:
+                least_frequent = min(self._freq.items(), key=lambda x: x[1])[0]
+                self._cache.pop(least_frequent, None)
+                self._freq.pop(least_frequent, None)
+        
+        self._cache[key] = value
+        if key not in self._freq:
+            self._freq[key] = 0
+    
+    def invalidate(self, key: str) -> None:
+        """Invalidate cached value."""
+        self._cache.pop(key, None)
+        self._freq.pop(key, None)
+    
+    def clear(self) -> None:
+        """Clear all cached values."""
+        self._cache.clear()
+        self._freq.clear()
+