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

exonware/xwlazy/package/strategies/package_timing_full.py

@@ -0,0 +1,67 @@
+"""
+Full Timing Strategy
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+Full timing - install all dependencies upfront.
+"""
+
+from typing import List, Any
+from ...package.base import AInstallTimingStrategy
+
+
+class FullTiming(AInstallTimingStrategy):
+    """
+    Full timing strategy - installs all packages upfront (LazyInstallMode.FULL).
+    
+    Batch installs all dependencies in parallel on initialization.
+    """
+    
+    def should_install_now(self, package_name: str, context: Any) -> bool:
+        """
+        Determine if package should be installed now.
+        
+        Full mode: Install all upfront.
+        
+        Args:
+            package_name: Package name to check
+            context: Context information (ignored in full mode)
+            
+        Returns:
+            True (always install upfront)
+        """
+        return True
+    
+    def should_uninstall_after(self, package_name: str, context: Any) -> bool:
+        """
+        Determine if package should be uninstalled after use.
+        
+        Full mode: Keep installed after use.
+        
+        Args:
+            package_name: Package name to check
+            context: Context information
+            
+        Returns:
+            False (keep installed)
+        """
+        return False
+    
+    def get_install_priority(self, packages: List[str]) -> List[str]:
+        """
+        Get priority order for installing packages.
+        
+        Full mode: Install all in parallel (no specific order).
+        
+        Args:
+            packages: List of package names
+            
+        Returns:
+            Priority-ordered list (original order)
+        """
+        return packages
+

exonware/xwlazy/package/strategies/package_timing_smart.py

@@ -0,0 +1,69 @@
+"""
+Smart Timing Strategy
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+Smart timing - install on first usage (on-demand).
+"""
+
+from typing import List, Any
+from ...package.base import AInstallTimingStrategy
+from ...defs import LazyInstallMode
+
+
+class SmartTiming(AInstallTimingStrategy):
+    """
+    Smart timing strategy - installs packages on-demand (LazyInstallMode.SMART).
+    
+    Installs package when first needed, then caches the result.
+    """
+    
+    def should_install_now(self, package_name: str, context: Any) -> bool:
+        """
+        Determine if package should be installed now.
+        
+        Smart mode: Install when first needed.
+        
+        Args:
+            package_name: Package name to check
+            context: Context information (e.g., import error)
+            
+        Returns:
+            True if should install now
+        """
+        # In smart mode, install when first needed (context indicates need)
+        return context is not None
+    
+    def should_uninstall_after(self, package_name: str, context: Any) -> bool:
+        """
+        Determine if package should be uninstalled after use.
+        
+        Smart mode: Keep installed after use.
+        
+        Args:
+            package_name: Package name to check
+            context: Context information
+            
+        Returns:
+            False (keep installed)
+        """
+        return False
+    
+    def get_install_priority(self, packages: List[str]) -> List[str]:
+        """
+        Get priority order for installing packages.
+        
+        Smart mode: Install in order requested.
+        
+        Args:
+            packages: List of package names
+            
+        Returns:
+            Priority-ordered list
+        """
+        return packages
+

exonware/xwlazy/package/strategies/package_timing_temporary.py

@@ -0,0 +1,67 @@
+"""
+Temporary Timing Strategy
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 15-Nov-2025
+
+Temporary timing - always uninstall after use (more aggressive than CLEAN).
+"""
+
+from typing import List, Any
+from ...package.base import AInstallTimingStrategy
+
+
+class TemporaryTiming(AInstallTimingStrategy):
+    """
+    Temporary timing strategy - always uninstalls after use (LazyInstallMode.TEMPORARY).
+    
+    More aggressive than CLEAN - always uninstalls packages after use.
+    """
+    
+    def should_install_now(self, package_name: str, context: Any) -> bool:
+        """
+        Determine if package should be installed now.
+        
+        Temporary mode: Install when first needed.
+        
+        Args:
+            package_name: Package name to check
+            context: Context information (e.g., import error)
+            
+        Returns:
+            True if should install now
+        """
+        return context is not None
+    
+    def should_uninstall_after(self, package_name: str, context: Any) -> bool:
+        """
+        Determine if package should be uninstalled after use.
+        
+        Temporary mode: Always uninstall after use.
+        
+        Args:
+            package_name: Package name to check
+            context: Context information (ignored)
+            
+        Returns:
+            True (always uninstall)
+        """
+        return True
+    
+    def get_install_priority(self, packages: List[str]) -> List[str]:
+        """
+        Get priority order for installing packages.
+        
+        Temporary mode: Install in order requested.
+        
+        Args:
+            packages: List of package names
+            
+        Returns:
+            Priority-ordered list
+        """
+        return packages
+

exonware/xwlazy/runtime/__init__.py

@@ -0,0 +1,18 @@
+"""
+Runtime Services Module
+
+This module provides concrete implementations for runtime services.
+Main facade: XWRuntimeHelper extends ARuntimeHelper
+"""
+
+# Lazy imports to avoid circular dependencies
+def __getattr__(name: str):
+    if name == 'XWRuntimeHelper':
+        from .facade import XWRuntimeHelper
+        return XWRuntimeHelper
+    if name == 'XWRuntime':  # Backward compatibility alias
+        from .facade import XWRuntimeHelper
+        return XWRuntimeHelper
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+__all__ = ['XWRuntimeHelper', 'XWRuntime']  # XWRuntime is backward compatibility alias

exonware/xwlazy/runtime/adaptive_learner.py

@@ -0,0 +1,131 @@
+"""
+#exonware/xwlazy/src/exonware/xwlazy/loading/adaptive_utils.py
+
+Adaptive learning utilities for pattern-based optimization.
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 19-Nov-2025
+
+This module provides adaptive learning for ADAPTIVE mode.
+"""
+
+import time
+import threading
+from typing import Dict, List, Tuple, Optional
+from collections import defaultdict, deque
+
+# Logger not used in this module, removed to avoid circular dependency
+
+
+class AdaptiveLearner:
+    """Learns import patterns and optimizes loading strategy."""
+    
+    def __init__(self, learning_window: int = 100, prediction_depth: int = 3):
+        """
+        Initialize adaptive learner.
+        
+        Args:
+            learning_window: Number of imports to track for learning
+            prediction_depth: Depth of sequence predictions
+        """
+        self._learning_window = learning_window
+        self._prediction_depth = prediction_depth
+        self._import_sequences: deque = deque(maxlen=learning_window)
+        self._access_times: Dict[str, List[float]] = defaultdict(list)
+        self._import_chains: Dict[str, Dict[str, int]] = defaultdict(lambda: defaultdict(int))
+        self._module_scores: Dict[str, float] = {}
+        self._lock = threading.RLock()
+    
+    def record_import(self, module_name: str, import_time: float) -> None:
+        """Record an import event."""
+        current_time = time.time()
+        
+        # Lock-free append to deque (thread-safe for appends)
+        self._import_sequences.append((module_name, current_time, import_time))
+        
+        with self._lock:
+            self._access_times[module_name].append(current_time)
+            
+            # Update import chains (what imports after what)
+            if len(self._import_sequences) > 1:
+                prev_name, _, _ = self._import_sequences[-2]
+                self._import_chains[prev_name][module_name] += 1
+            
+            # Update module score (frequency * recency) - defer heavy computation
+            if len(self._access_times[module_name]) % 5 == 0:  # Update every 5th access
+                self._update_module_score(module_name)
+    
+    def _update_module_score(self, module_name: str) -> None:
+        """Update module priority score."""
+        with self._lock:
+            accesses = self._access_times[module_name]
+            if not accesses:
+                return
+            
+            # Frequency component
+            recent_accesses = [t for t in accesses if time.time() - t < 3600]  # Last hour
+            frequency = len(recent_accesses)
+            
+            # Recency component (more recent = higher score)
+            if accesses:
+                last_access = accesses[-1]
+                recency = 1.0 / (time.time() - last_access + 1.0)
+            else:
+                recency = 0.0
+            
+            # Chain component (if often imported after another module)
+            chain_weight = sum(self._import_chains.get(prev, {}).get(module_name, 0) 
+                             for prev in self._access_times.keys()) / max(len(self._import_sequences), 1)
+            
+            # Combined score
+            self._module_scores[module_name] = frequency * 0.4 + recency * 1000 * 0.4 + chain_weight * 0.2
+    
+    def predict_next_imports(self, current_module: Optional[str] = None, limit: int = 5) -> List[str]:
+        """Predict likely next imports based on patterns."""
+        # Lock-free check first
+        if not self._import_sequences:
+            return []
+        
+        with self._lock:
+            candidates: Dict[str, float] = {}
+            
+            # Predict based on current module chain (lock-free read of dict)
+            if current_module:
+                chain_candidates = self._import_chains.get(current_module, {})
+                for module, count in chain_candidates.items():
+                    candidates[module] = candidates.get(module, 0.0) + count * 2.0
+            
+            # Add high-scoring modules (lock-free read of dict)
+            for module, score in self._module_scores.items():
+                candidates[module] = candidates.get(module, 0.0) + score * 0.5
+            
+            # Sort by score
+            sorted_candidates = sorted(candidates.items(), key=lambda x: x[1], reverse=True)
+            return [module for module, _ in sorted_candidates[:limit]]
+    
+    def get_priority_modules(self, limit: int = 10) -> List[str]:
+        """Get modules that should be preloaded based on scores."""
+        with self._lock:
+            sorted_modules = sorted(
+                self._module_scores.items(),
+                key=lambda x: x[1],
+                reverse=True
+            )
+            return [module for module, _ in sorted_modules[:limit]]
+    
+    def get_stats(self) -> Dict:
+        """Get learning statistics."""
+        with self._lock:
+            return {
+                'sequences_tracked': len(self._import_sequences),
+                'unique_modules': len(self._access_times),
+                'chains_tracked': sum(len(chains) for chains in self._import_chains.values()),
+                'top_modules': self.get_priority_modules(5),
+            }
+
+
+__all__ = ['AdaptiveLearner']
+

exonware/xwlazy/runtime/base.py

@@ -0,0 +1,276 @@
+"""
+#exonware/xwlazy/src/exonware/xwlazy/runtime/base.py
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 10-Oct-2025
+
+Abstract Base Class for Runtime Services
+
+This module defines the abstract base class for runtime services.
+"""
+
+import threading
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional, Any, Tuple
+
+from ..contracts import (
+    IRuntime,
+)
+
+
+# =============================================================================
+# ABSTRACT RUNTIME (Unified - Merges all runtime services)
+# =============================================================================
+
+class ARuntimeHelper(IRuntime, ABC):
+    """
+    Unified abstract base for runtime services.
+    
+    Merges functionality from all runtime service interfaces.
+    Provides runtime services for state management, learning, monitoring, and caching.
+    
+    This abstract class combines:
+    - State management (persistent state for lazy installation)
+    - Adaptive learning (learning import patterns and optimizing loading)
+    - Intelligent selection (selecting optimal modes based on load characteristics)
+    - Metrics collection (collecting and aggregating performance metrics)
+    - Performance monitoring (monitoring lazy loading performance)
+    - Multi-tier caching (L1/L2/L3 caching)
+    - Registry (managing instances by key)
+    """
+    
+    __slots__ = (
+        # From IStateManager
+        '_manual_state', '_auto_state',
+        # From IMetricsCollector
+        '_metrics',
+        # From IPerformanceMonitor
+        '_load_times', '_access_counts',
+        # From IMultiTierCache
+        '_l1_cache', '_l2_cache', '_l3_cache',
+        # From IRegistry
+        '_registry',
+        # Common
+        '_lock'
+    )
+    
+    def __init__(self):
+        """Initialize unified runtime services."""
+        # From IStateManager
+        self._manual_state: Optional[bool] = None
+        self._auto_state: Optional[bool] = None
+        
+        # From IMetricsCollector
+        self._metrics: Dict[str, List[float]] = {}
+        
+        # From IPerformanceMonitor
+        self._load_times: Dict[str, List[float]] = {}
+        self._access_counts: Dict[str, int] = {}
+        
+        # From IMultiTierCache
+        self._l1_cache: Dict[str, Any] = {}
+        self._l2_cache: Dict[str, Any] = {}
+        self._l3_cache: Dict[str, Any] = {}
+        
+        # From IRegistry
+        self._registry: Dict[str, Any] = {}
+        
+        # Common
+        self._lock = threading.RLock()
+    
+    # ========================================================================
+    # State Management Methods (from IStateManager)
+    # ========================================================================
+    
+    def get_manual_state(self) -> Optional[bool]:
+        """Get manual state override (from IStateManager)."""
+        return self._manual_state
+    
+    def set_manual_state(self, value: Optional[bool]) -> None:
+        """Set manual state override (from IStateManager)."""
+        with self._lock:
+            self._manual_state = value
+    
+    def get_cached_auto_state(self) -> Optional[bool]:
+        """Get cached auto-detected state (from IStateManager)."""
+        return self._auto_state
+    
+    def set_auto_state(self, value: Optional[bool]) -> None:
+        """Set cached auto-detected state (from IStateManager)."""
+        with self._lock:
+            self._auto_state = value
+    
+    # ========================================================================
+    # Adaptive Learning Methods (from IAdaptiveLearner)
+    # ========================================================================
+    
+    @abstractmethod
+    def record_import(self, module_name: str, import_time: float) -> None:
+        """Record an import event (from IAdaptiveLearner)."""
+        pass
+    
+    @abstractmethod
+    def predict_next_imports(self, current_module: str, count: int = 3) -> List[str]:
+        """Predict next likely imports based on patterns (from IAdaptiveLearner)."""
+        pass
+    
+    @abstractmethod
+    def get_module_score(self, module_name: str) -> float:
+        """Get priority score for a module (from IAdaptiveLearner)."""
+        pass
+    
+    # ========================================================================
+    # Intelligent Selection Methods (from IIntelligentSelector)
+    # ========================================================================
+    
+    @abstractmethod
+    def detect_load_level(
+        self,
+        module_count: int = 0,
+        total_import_time: float = 0.0,
+        import_count: int = 0,
+        memory_usage_mb: float = 0.0
+    ) -> Any:
+        """Detect current load level (from IIntelligentSelector)."""
+        pass
+    
+    @abstractmethod
+    def get_optimal_mode(self, load_level: Any) -> Tuple[Any, Any]:
+        """Get optimal mode for a load level (from IIntelligentSelector)."""
+        pass
+    
+    @abstractmethod
+    def update_mode_map(self, mode_map: Dict[Any, Tuple[Any, Any]]) -> None:
+        """Update mode mapping with benchmark results (from IIntelligentSelector)."""
+        pass
+    
+    # ========================================================================
+    # Metrics Collection Methods (from IMetricsCollector)
+    # ========================================================================
+    
+    def record_metric(self, name: str, value: float, timestamp: Optional[Any] = None) -> None:
+        """Record a metric value (from IMetricsCollector)."""
+        with self._lock:
+            if name not in self._metrics:
+                self._metrics[name] = []
+            self._metrics[name].append(value)
+    
+    @abstractmethod
+    def get_metric_stats(self, name: str) -> Dict[str, Any]:
+        """Get statistics for a metric (from IMetricsCollector)."""
+        pass
+    
+    @abstractmethod
+    def get_all_stats(self) -> Dict[str, Dict[str, Any]]:
+        """Get statistics for all metrics (from IMetricsCollector)."""
+        pass
+    
+    def clear_metrics(self) -> None:
+        """Clear all collected metrics (from IMetricsCollector)."""
+        with self._lock:
+            self._metrics.clear()
+    
+    # ========================================================================
+    # Performance Monitoring Methods (from IPerformanceMonitor)
+    # ========================================================================
+    
+    def record_load_time(self, module: str, load_time: float) -> None:
+        """Record module load time (from IPerformanceMonitor)."""
+        with self._lock:
+            if module not in self._load_times:
+                self._load_times[module] = []
+            self._load_times[module].append(load_time)
+    
+    def record_access(self, module: str) -> None:
+        """Record module access (from IPerformanceMonitor)."""
+        with self._lock:
+            self._access_counts[module] = self._access_counts.get(module, 0) + 1
+    
+    @abstractmethod
+    def get_performance_stats(self) -> Dict[str, Any]:
+        """Get performance statistics (from IPerformanceMonitor)."""
+        pass
+    
+    # ========================================================================
+    # Multi-Tier Cache Methods (from IMultiTierCache)
+    # ========================================================================
+    
+    def get_multi_tier_cached(self, key: str) -> Optional[Any]:
+        """Get value from cache (L1 -> L2 -> L3) (from IMultiTierCache)."""
+        with self._lock:
+            # Check L1 first
+            if key in self._l1_cache:
+                return self._l1_cache[key]
+            # Check L2
+            if key in self._l2_cache:
+                value = self._l2_cache[key]
+                # Promote to L1
+                self._l1_cache[key] = value
+                return value
+            # Check L3
+            if key in self._l3_cache:
+                value = self._l3_cache[key]
+                # Promote to L2
+                self._l2_cache[key] = value
+                return value
+            return None
+    
+    def set_multi_tier_cached(self, key: str, value: Any) -> None:
+        """Set value in cache (L1 and L2) (from IMultiTierCache)."""
+        with self._lock:
+            self._l1_cache[key] = value
+            self._l2_cache[key] = value
+    
+    def clear_multi_tier_cache(self) -> None:
+        """Clear all cache tiers (from IMultiTierCache)."""
+        with self._lock:
+            self._l1_cache.clear()
+            self._l2_cache.clear()
+            self._l3_cache.clear()
+    
+    @abstractmethod
+    def shutdown_multi_tier_cache(self) -> None:
+        """Shutdown cache (flush L2, cleanup threads) (from IMultiTierCache)."""
+        pass
+    
+    # Alias method for backward compatibility
+    def shutdown_cache(self) -> None:
+        """Alias for shutdown_multi_tier_cache (backward compatibility)."""
+        self.shutdown_multi_tier_cache()
+    
+    # ========================================================================
+    # Registry Methods (from IRegistry)
+    # ========================================================================
+    
+    def get_instance(self, key: str) -> Any:
+        """Get instance by key (from IRegistry)."""
+        with self._lock:
+            return self._registry.get(key)
+    
+    def register(self, key: str, instance: Any) -> None:
+        """Register an instance (from IRegistry)."""
+        with self._lock:
+            self._registry[key] = instance
+    
+    def unregister(self, key: str) -> None:
+        """Unregister an instance (from IRegistry)."""
+        with self._lock:
+            self._registry.pop(key, None)
+    
+    def has_key(self, key: str) -> bool:
+        """Check if key is registered (from IRegistry)."""
+        with self._lock:
+            return key in self._registry
+
+
+# =============================================================================
+# EXPORT ALL
+# =============================================================================
+
+__all__ = [
+    'ARuntimeHelper',
+]
+