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

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

exonware/xwlazy/common/strategies/caching_lru.py

@@ -0,0 +1,64 @@
+"""
+LRU Cache Strategy - Least Recently Used eviction.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+LRU cache implementation with size limit.
+Works with ANY data type (modules, packages, etc.).
+"""
+
+from typing import Optional, Any
+from collections import OrderedDict
+from ...common.base import ACachingStrategy
+
+
+class LRUCache(ACachingStrategy):
+    """
+    LRU (Least Recently Used) cache with size limit.
+    
+    Evicts least recently used items when cache is full.
+    Good for general-purpose caching.
+    """
+    
+    def __init__(self, max_size: int = 1000):
+        """
+        Initialize LRU cache.
+        
+        Args:
+            max_size: Maximum number of items in cache
+        """
+        self._cache: OrderedDict[str, Any] = OrderedDict()
+        self._max_size = max_size
+    
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache (moves to end for LRU)."""
+        if key in self._cache:
+            # Move to end (most recently used)
+            self._cache.move_to_end(key)
+            return self._cache[key]
+        return None
+    
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache (evicts oldest if full)."""
+        if key in self._cache:
+            # Update existing - move to end
+            self._cache.move_to_end(key)
+        else:
+            # New entry - check size limit
+            if len(self._cache) >= self._max_size:
+                # Remove oldest (first item)
+                self._cache.popitem(last=False)
+        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_multitier.py

@@ -0,0 +1,60 @@
+"""
+Multi-Tier Cache Strategy - Wrapper for existing MultiTierCache.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+Wraps existing MultiTierCache to implement ICaching interface.
+Works with ANY data type (modules, packages, etc.).
+"""
+
+from typing import Optional, Any
+from pathlib import Path
+from ...common.cache import MultiTierCache
+from ...common.base import ACachingStrategy
+
+
+class MultiTierCacheStrategy(ACachingStrategy):
+    """
+    Multi-tier cache strategy (L1 memory + L2 disk + L3 predictive).
+    
+    Wraps existing MultiTierCache to implement ICachingStrategy interface.
+    High-performance caching with multiple tiers.
+    """
+    
+    def __init__(self, l1_size: int = 1000, l2_dir: Optional[Path] = None, enable_l3: bool = True):
+        """
+        Initialize multi-tier cache.
+        
+        Args:
+            l1_size: Maximum size of L1 (memory) cache
+            l2_dir: Directory for L2 (disk) cache
+            enable_l3: Enable L3 (predictive) cache
+        """
+        self._cache = MultiTierCache(l1_size=l1_size, l2_dir=l2_dir, enable_l3=enable_l3)
+    
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache (L1 -> L2 -> L3)."""
+        return self._cache.get(key)
+    
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache (L1 + L2 batched)."""
+        self._cache.set(key, value)
+    
+    def invalidate(self, key: str) -> None:
+        """Invalidate cached value."""
+        # MultiTierCache doesn't have invalidate, so we set to None
+        # Or we could extend MultiTierCache to add invalidate
+        self._cache.set(key, None)
+    
+    def clear(self) -> None:
+        """Clear all cached values."""
+        self._cache.clear()
+    
+    def shutdown(self) -> None:
+        """Shutdown cache (flush L2, cleanup threads)."""
+        self._cache.shutdown()
+

exonware/xwlazy/common/strategies/caching_ttl.py

@@ -0,0 +1,60 @@
+"""
+TTL Cache Strategy - Time-To-Live expiration.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+TTL cache implementation with expiration.
+Works with ANY data type (modules, packages, etc.).
+"""
+
+import time
+from typing import Dict, Optional, Any, Tuple
+from ...common.base import ACachingStrategy
+
+
+class TTLCache(ACachingStrategy):
+    """
+    TTL (Time-To-Live) cache with expiration.
+    
+    Automatically expires entries after TTL seconds.
+    Good for time-sensitive data.
+    """
+    
+    def __init__(self, ttl_seconds: float = 3600.0):
+        """
+        Initialize TTL cache.
+        
+        Args:
+            ttl_seconds: Time-to-live in seconds (default: 1 hour)
+        """
+        self._cache: Dict[str, Tuple[Any, float]] = {}  # (value, expiry_time)
+        self._ttl = ttl_seconds
+    
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache (returns None if expired)."""
+        if key in self._cache:
+            value, expiry = self._cache[key]
+            if time.time() < expiry:
+                return value
+            else:
+                # Expired - remove
+                del self._cache[key]
+        return None
+    
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache with TTL."""
+        expiry = time.time() + self._ttl
+        self._cache[key] = (value, expiry)
+    
+    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/config.py

@@ -0,0 +1,195 @@
+"""
+#exonware/xwlazy/src/exonware/xwlazy/config.py
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 10-Oct-2025
+
+Configuration for Lazy Loading System
+
+This module defines configuration classes for the lazy loading system
+following GUIDE_ARCH.md structure.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Any, Dict
+
+# Import LazyConfig dataclass from defs.py
+from .defs import LazyConfig as _LazyConfigBase
+
+
+# Extend LazyConfig with methods (dataclass is in defs.py)
+class LazyConfig(_LazyConfigBase):
+    """Bridge configuration settings with the lazy package implementation."""
+    
+    def __post_init__(self) -> None:
+        """Normalize package names."""
+        super().__post_init__()
+
+    # High-level API -----------------------------------------------------
+    @property
+    def lazy_import(self) -> bool:
+        """Return whether lazy mode is currently active."""
+        # Import from facade
+        from .facade import is_lazy_mode_enabled
+        return is_lazy_mode_enabled()
+
+    @lazy_import.setter
+    def lazy_import(self, value: bool) -> None:
+        self.set_lazy_import(bool(value))
+
+    def set_lazy_import(
+        self,
+        enabled: bool,
+        *,
+        lazy_imports: bool = True,
+        lazy_install: bool = True,
+        install_hook: bool = True,
+        mode: str = "auto",
+    ) -> None:
+        """
+        Toggle lazy mode with optional fine-grained controls.
+        
+        Includes re-hooking support: If lazy is enabled and install_hook is True,
+        ensures the import hook is installed even if it wasn't installed initially.
+        """
+        # Import from facade
+        from .facade import (
+            config_package_lazy_install_enabled,
+            disable_lazy_mode,
+            enable_lazy_mode,
+            is_import_hook_installed,
+            install_import_hook,
+        )
+        
+        if enabled:
+            self._configure_packages(True, mode=mode, install_hook=install_hook)
+            enable_lazy_mode(
+                package_name=self.packages[0],
+                enable_lazy_imports=lazy_imports,
+                enable_lazy_install=lazy_install,
+                install_hook=install_hook,
+                lazy_install_mode=mode,
+            )
+            # Re-hook: Install hook if lazy is enabled and hook not already installed
+            # Root cause: Hook not installed when lazy enabled after package load
+            # Priority impact: Usability (#2) - Users expect lazy to work when enabled
+            if install_hook:
+                self._ensure_hook_installed()
+        else:
+            disable_lazy_mode()
+            self._configure_packages(False, install_hook=False)
+
+    def enable(
+        self,
+        *,
+        lazy_imports: bool = True,
+        lazy_install: bool = True,
+        install_hook: bool = True,
+        mode: str = "auto",
+    ) -> None:
+        """Enable lazy mode using the provided options."""
+        self.set_lazy_import(
+            True,
+            lazy_imports=lazy_imports,
+            lazy_install=lazy_install,
+            install_hook=install_hook,
+            mode=mode,
+        )
+
+    def disable(self) -> None:
+        """Disable lazy mode entirely."""
+        self.set_lazy_import(False)
+
+    # DX: Status check methods -------------------------------------------
+    def get_lazy_status(self) -> dict:
+        """
+        Get detailed lazy installation status (DX enhancement).
+        
+        Returns:
+            Dictionary with lazy mode status information
+        """
+        # Import from facade
+        from .facade import (
+            is_import_hook_installed,
+            is_lazy_install_enabled,
+        )
+        
+        try:
+            primary_package = self.packages[0] if self.packages else "default"
+            return {
+                'enabled': self.lazy_import,
+                'hook_installed': is_import_hook_installed(primary_package),
+                'lazy_install_enabled': is_lazy_install_enabled(primary_package),
+                'active': self.lazy_import and is_import_hook_installed(primary_package)
+            }
+        except Exception:
+            return {
+                'enabled': self.lazy_import,
+                'hook_installed': False,
+                'lazy_install_enabled': False,
+                'active': False,
+                'error': 'Could not check hook status'
+            }
+    
+    def is_lazy_active(self) -> bool:
+        """
+        Check if lazy mode is active (DX enhancement).
+        
+        Returns:
+            True if lazy mode is enabled and hook is installed
+        """
+        # Import from facade
+        from .facade import is_import_hook_installed
+        
+        try:
+            primary_package = self.packages[0] if self.packages else "default"
+            return self.lazy_import and is_import_hook_installed(primary_package)
+        except Exception:
+            return False
+
+    # Internal helpers ---------------------------------------------------
+    def _configure_packages(
+        self,
+        enabled: bool,
+        *,
+        mode: str = "auto",
+        install_hook: bool = True,
+    ) -> None:
+        # Import from facade
+        from .facade import config_package_lazy_install_enabled
+        
+        for package in self.packages:
+            config_package_lazy_install_enabled(
+                package,
+                enabled,
+                mode,
+                install_hook=install_hook,
+            )
+    
+    def _ensure_hook_installed(self) -> None:
+        """
+        Ensure import hook is installed for primary package.
+        
+        Re-hooking support: Install hook if not already installed.
+        """
+        # Import from facade
+        from .facade import (
+            is_import_hook_installed,
+            install_import_hook,
+        )
+        
+        try:
+            primary_package = self.packages[0] if self.packages else "default"
+            if not is_import_hook_installed(primary_package):
+                install_import_hook(primary_package)
+        except Exception:
+            # Fail silently - hook installation failure shouldn't break package
+            pass
+
+
+DEFAULT_LAZY_CONFIG = LazyConfig()
+