exonware-xwlazy 0.1.0.10__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/services/state_manager.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Dict, Optional
+
+
+def _get_base_config_dir() -> Path:
+    """Determine a cross-platform directory for storing lazy configuration."""
+    if os.name == "nt":
+        appdata = os.getenv("APPDATA")
+        if appdata:
+            return Path(appdata) / "exonware" / "lazy"
+        return Path.home() / "AppData" / "Roaming" / "exonware" / "lazy"
+
+    # POSIX-style
+    xdg_config = os.getenv("XDG_CONFIG_HOME")
+    if xdg_config:
+        return Path(xdg_config) / "exonware" / "lazy"
+    return Path.home() / ".config" / "exonware" / "lazy"
+
+
+class LazyStateManager:
+    """Persist and retrieve lazy installation state."""
+
+    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()
+
+    # --------------------------------------------------------------------- #
+    # Persistence helpers
+    # --------------------------------------------------------------------- #
+    def _load_state(self) -> Dict[str, Dict[str, bool]]:
+        if not self._state_path.exists():
+            return {}
+        try:
+            with self._state_path.open("r", encoding="utf-8") as fh:
+                data = json.load(fh)
+                if isinstance(data, dict):
+                    return data
+        except Exception:
+            pass
+        return {}
+
+    def _save_state(self) -> None:
+        self._state_path.parent.mkdir(parents=True, exist_ok=True)
+        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]:
+        return self._state.setdefault(self._package, {})
+
+    # --------------------------------------------------------------------- #
+    # Manual state management
+    # --------------------------------------------------------------------- #
+    def get_manual_state(self) -> Optional[bool]:
+        entry = self._state.get(self._package, {})
+        value = entry.get("manual")
+        return bool(value) if isinstance(value, bool) else None
+
+    def set_manual_state(self, value: Optional[bool]) -> None:
+        entry = self._ensure_entry()
+        if value is None:
+            entry.pop("manual", None)
+        else:
+            entry["manual"] = bool(value)
+        self._save_state()
+
+    # --------------------------------------------------------------------- #
+    # Auto detection cache
+    # --------------------------------------------------------------------- #
+    def get_cached_auto_state(self) -> Optional[bool]:
+        entry = self._state.get(self._package, {})
+        value = entry.get("auto")
+        return bool(value) if isinstance(value, bool) else None
+
+    def set_auto_state(self, value: Optional[bool]) -> None:
+        entry = self._ensure_entry()
+        if value is None:
+            entry.pop("auto", None)
+        else:
+            entry["auto"] = bool(value)
+        self._save_state()
+

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()
+