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

exonware/xwlazy/runtime/base.py

@@ -1,274 +0,0 @@
-"""
-#exonware/xwlazy/src/exonware/xwlazy/runtime/base.py
-
-Company: eXonware.com
-Author: Eng. Muhammad AlShehri
-Email: connect@exonware.com
-
-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 Optional, Any
-
-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',
-]
-

exonware/xwlazy/runtime/facade.py

@@ -1,94 +0,0 @@
-"""
-Runtime Services Facade
-
-Main facade: XWRuntimeHelper extends ARuntimeHelper
-Provides concrete implementation for all runtime services.
-"""
-
-from typing import Optional, Any
-from .base import ARuntimeHelper
-from ..defs import LazyLoadMode, LazyInstallMode
-
-class XWRuntimeHelper(ARuntimeHelper):
-    """
-    Concrete implementation of ARuntimeHelper.
-    
-    Provides runtime services for state management, learning, monitoring, and caching.
-    """
-    
-    def __init__(self):
-        """Initialize XW runtime services."""
-        super().__init__()
-    
-    # Abstract methods from ARuntime that need implementation
-    def record_import(self, module_name: str, import_time: float) -> None:
-        """Record an import event."""
-        # TODO: Implement import recording
-        pass
-    
-    def predict_next_imports(self, current_module: str, count: int = 3) -> list[str]:
-        """Predict next likely imports based on patterns."""
-        # TODO: Implement prediction logic
-        return []
-    
-    def get_module_score(self, module_name: str) -> float:
-        """Get priority score for a module."""
-        # TODO: Implement scoring logic
-        return 0.0
-    
-    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
-    ):
-        """Detect current load level."""
-        # TODO: Implement load level detection
-        from .intelligent_selector import LoadLevel
-        return LoadLevel.LIGHT
-    
-    def get_optimal_mode(self, load_level) -> tuple[LazyLoadMode, LazyInstallMode]:
-        """Get optimal mode for a load level."""
-        # TODO: Implement mode selection
-        return LazyLoadMode.AUTO, LazyInstallMode.SMART
-    
-    def update_mode_map(self, mode_map: dict[Any, tuple[LazyLoadMode, LazyInstallMode]]) -> None:
-        """Update mode mapping with benchmark results."""
-        # TODO: Implement mode map update
-        pass
-    
-    def get_metric_stats(self, name: str) -> dict[str, Any]:
-        """Get statistics for a metric."""
-        with self._lock:
-            values = self._metrics.get(name, [])
-            if not values:
-                return {'count': 0, 'total': 0.0, 'average': 0.0, 'min': 0.0, 'max': 0.0}
-            return {
-                'count': len(values),
-                'total': sum(values),
-                'average': sum(values) / len(values),
-                'min': min(values),
-                'max': max(values)
-            }
-    
-    def get_all_stats(self) -> dict[str, dict[str, Any]]:
-        """Get statistics for all metrics."""
-        with self._lock:
-            return {name: self.get_metric_stats(name) for name in self._metrics.keys()}
-    
-    def get_performance_stats(self) -> dict[str, Any]:
-        """Get performance statistics."""
-        with self._lock:
-            return {
-                'load_times': {k: {'count': len(v), 'total': sum(v), 'average': sum(v) / len(v) if v else 0.0} 
-                              for k, v in self._load_times.items()},
-                'access_counts': self._access_counts.copy(),
-                'memory_usage': 0.0  # TODO: Implement memory usage tracking
-            }
-    
-    def shutdown_multi_tier_cache(self) -> None:
-        """Shutdown cache (flush L2, cleanup threads)."""
-        # TODO: Implement cache shutdown
-        pass
-

exonware/xwlazy/runtime/intelligent_selector.py

@@ -1,170 +0,0 @@
-"""
-#exonware/xwlazy/src/exonware/xwlazy/loading/intelligent_utils.py
-
-Intelligent mode utilities for automatic mode switching.
-
-Company: eXonware.com
-Author: Eng. Muhammad AlShehri
-Email: connect@exonware.com
-
-Generation Date: 19-Nov-2025
-
-This module provides intelligent mode switching based on load level.
-"""
-
-from typing import Optional
-
-from ..defs import LazyLoadMode, LazyInstallMode, LoadLevel
-
-# Lazy import to avoid circular dependency
-logger = None
-
-def _get_logger():
-    """Get logger (lazy import to avoid circular dependency)."""
-    global logger
-    if logger is None:
-        from ..common.logger import get_logger
-        logger = get_logger("xwlazy.loading.intelligent")
-    return logger
-
-# Optimal mode mappings based on benchmark results (updated from consistency test)
-# Format: {LoadLevel: (LazyLoadMode, LazyInstallMode)}
-# Updated: 2025-11-19 - Based on 20-iteration consistency test averages
-# Light: ultra+full (0.568ms avg), Medium: hyperparallel+full (5.134ms avg)
-# Heavy: preload+size_aware (18.475ms avg), Enterprise: preload+full (44.742ms avg)
-INTELLIGENT_MODE_MAP: dict[LoadLevel, tuple[LazyLoadMode, LazyInstallMode]] = {
-    LoadLevel.LIGHT: (LazyLoadMode.ULTRA, LazyInstallMode.FULL),  # Winner: 0.568ms avg (±26.1% CV)
-    LoadLevel.MEDIUM: (LazyLoadMode.HYPERPARALLEL, LazyInstallMode.FULL),  # Winner: 5.134ms avg (±4.7% CV)
-    LoadLevel.HEAVY: (LazyLoadMode.PRELOAD, LazyInstallMode.SIZE_AWARE),  # Winner: 18.475ms avg (±10.2% CV)
-    LoadLevel.ENTERPRISE: (LazyLoadMode.PRELOAD, LazyInstallMode.FULL),  # Winner: 44.742ms avg (±1.5% CV)
-}
-
-class IntelligentModeSelector:
-    """Selects optimal mode based on current load characteristics."""
-    
-    def __init__(self, mode_map: Optional[dict[LoadLevel, tuple[LazyLoadMode, LazyInstallMode]]] = None):
-        """
-        Initialize intelligent mode selector.
-        
-        Args:
-            mode_map: Custom mode mapping (defaults to INTELLIGENT_MODE_MAP)
-        """
-        self._mode_map = mode_map or INTELLIGENT_MODE_MAP.copy()
-        self._current_load_level: Optional[LoadLevel] = None
-        self._module_count = 0
-        self._total_import_time = 0.0
-        self._import_count = 0
-    
-    def update_mode_map(self, mode_map: dict[LoadLevel, tuple[LazyLoadMode, LazyInstallMode]]) -> None:
-        """Update the mode mapping with benchmark results."""
-        self._mode_map = mode_map.copy()
-        _get_logger().info(f"Updated INTELLIGENT mode mapping: {mode_map}")
-    
-    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
-    ) -> LoadLevel:
-        """
-        Detect current load level based on system characteristics.
-        
-        Args:
-            module_count: Number of modules loaded
-            total_import_time: Total time spent on imports (seconds)
-            import_count: Number of imports performed
-            memory_usage_mb: Current memory usage in MB
-            
-        Returns:
-            Detected LoadLevel
-        """
-        # Update internal state
-        self._module_count = module_count
-        self._total_import_time = total_import_time
-        self._import_count = import_count
-        
-        # Simple heuristics based on module count and import patterns
-        # These thresholds can be tuned based on actual usage patterns
-        
-        if import_count == 0:
-            # Initial state - default to light
-            self._current_load_level = LoadLevel.LIGHT
-        elif module_count < 5 and import_count < 10:
-            # Light load: few modules, few imports
-            self._current_load_level = LoadLevel.LIGHT
-        elif module_count < 20 and import_count < 50:
-            # Medium load: moderate number of modules/imports
-            self._current_load_level = LoadLevel.MEDIUM
-        elif module_count < 100 and import_count < 200:
-            # Heavy load: many modules, many imports
-            self._current_load_level = LoadLevel.HEAVY
-        else:
-            # Enterprise load: very large scale
-            self._current_load_level = LoadLevel.ENTERPRISE
-        
-        # Override based on memory usage if significant
-        if memory_usage_mb > 300:
-            self._current_load_level = LoadLevel.ENTERPRISE
-        elif memory_usage_mb > 150:
-            self._current_load_level = LoadLevel.HEAVY
-        
-        return self._current_load_level
-    
-    def get_optimal_mode(self, load_level: Optional[LoadLevel] = None) -> tuple[LazyLoadMode, LazyInstallMode]:
-        """
-        Get optimal mode combination for given load level.
-        
-        Args:
-            load_level: Load level (if None, uses detected level)
-            
-        Returns:
-            Tuple of (LazyLoadMode, LazyInstallMode)
-        """
-        if load_level is None:
-            load_level = self._current_load_level or LoadLevel.LIGHT
-        
-        optimal = self._mode_map.get(load_level)
-        if optimal is None:
-            # Fallback to default
-            _get_logger().warning(f"No optimal mode found for {load_level}, using default")
-            optimal = (LazyLoadMode.AUTO, LazyInstallMode.SMART)
-        
-        return optimal
-    
-    def should_switch_mode(
-        self,
-        current_mode: tuple[LazyLoadMode, LazyInstallMode],
-        detected_level: LoadLevel
-    ) -> bool:
-        """
-        Determine if mode should be switched based on detected load level.
-        
-        Args:
-            current_mode: Current (load_mode, install_mode) tuple
-            detected_level: Detected load level
-            
-        Returns:
-            True if mode should be switched
-        """
-        optimal_mode = self.get_optimal_mode(detected_level)
-        return current_mode != optimal_mode
-    
-    def get_stats(self) -> Dict:
-        """Get intelligent mode statistics."""
-        return {
-            'current_load_level': self._current_load_level.value if self._current_load_level else None,
-            'module_count': self._module_count,
-            'import_count': self._import_count,
-            'total_import_time': self._total_import_time,
-            'mode_map': {
-                level.value: {
-                    'load_mode': mode[0].value,
-                    'install_mode': mode[1].value
-                }
-                for level, mode in self._mode_map.items()
-            }
-        }
-
-__all__ = ['LoadLevel', 'INTELLIGENT_MODE_MAP', 'IntelligentModeSelector']
-

exonware/xwlazy/runtime/metrics.py

@@ -1,60 +0,0 @@
-"""
-Performance metrics tracking for lazy loading system.
-
-This module provides utilities for tracking and aggregating performance metrics.
-"""
-
-from typing import Any, Optional
-from datetime import datetime
-from collections import defaultdict
-
-class MetricsCollector:
-    """Collects and aggregates performance metrics."""
-    
-    def __init__(self):
-        """Initialize metrics collector."""
-        self._metrics: dict[str, list[float]] = defaultdict(list)
-        self._counts: dict[str, int] = defaultdict(int)
-        self._timestamps: dict[str, list[datetime]] = defaultdict(list)
-    
-    def record_metric(self, name: str, value: float, timestamp: Optional[datetime] = None) -> None:
-        """Record a metric value."""
-        self._metrics[name].append(value)
-        self._counts[name] += 1
-        if timestamp is None:
-            timestamp = datetime.now()
-        self._timestamps[name].append(timestamp)
-    
-    def get_metric_stats(self, name: str) -> dict[str, Any]:
-        """Get statistics for a specific metric."""
-        values = self._metrics.get(name, [])
-        if not values:
-            return {}
-        
-        return {
-            'count': len(values),
-            'total': sum(values),
-            'average': sum(values) / len(values),
-            'min': min(values),
-            'max': max(values),
-        }
-    
-    def get_all_stats(self) -> dict[str, dict[str, Any]]:
-        """Get statistics for all metrics."""
-        return {name: self.get_metric_stats(name) for name in self._metrics.keys()}
-    
-    def clear(self) -> None:
-        """Clear all collected metrics."""
-        self._metrics.clear()
-        self._counts.clear()
-        self._timestamps.clear()
-
-# Global metrics collector instance
-_global_metrics = MetricsCollector()
-
-def get_metrics_collector() -> MetricsCollector:
-    """Get the global metrics collector instance."""
-    return _global_metrics
-
-__all__ = ['MetricsCollector', 'get_metrics_collector']
-

exonware/xwlazy/runtime/performance.py

@@ -1,37 +0,0 @@
-"""
-Performance monitoring for lazy loading system.
-
-This module contains LazyPerformanceMonitor extracted from lazy_core.py Section 4.
-"""
-
-from typing import Any
-
-class LazyPerformanceMonitor:
-    """Performance monitor for lazy loading operations."""
-    
-    __slots__ = ('_load_times', '_access_counts', '_memory_usage')
-    
-    def __init__(self):
-        """Initialize performance monitor."""
-        self._load_times: dict[str, float] = {}
-        self._access_counts: dict[str, int] = {}
-        self._memory_usage: dict[str, Any] = {}
-    
-    def record_load_time(self, module: str, load_time: float) -> None:
-        """Record module load time."""
-        self._load_times[module] = load_time
-    
-    def record_access(self, module: str) -> None:
-        """Record module access."""
-        self._access_counts[module] = self._access_counts.get(module, 0) + 1
-    
-    def get_stats(self) -> dict[str, Any]:
-        """Get performance statistics."""
-        return {
-            'load_times': self._load_times.copy(),
-            'access_counts': self._access_counts.copy(),
-            'memory_usage': self._memory_usage.copy()
-        }
-
-__all__ = ['LazyPerformanceMonitor']
-