exonware-xwsystem 0.1.0.1__py3-none-any.whl → 0.1.0.3__py3-none-any.whl

exonware/xwsystem/monitoring/defs.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/defs.py
 #exonware/xwsystem/monitoring/types.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: 07-Sep-2025
 
 Monitoring types and enums for XWSystem.

exonware/xwsystem/monitoring/error_recovery.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/error_recovery.py
 """
 Error Recovery and Resilience Mechanisms for XWSystem Library.
 
@@ -10,7 +11,7 @@ import functools
 import threading
 import time
 from dataclasses import dataclass, field
-from typing import Any, Callable, Optional, Union
+from typing import Any, Callable, Optional
 
 from .defs import CircuitState
 
@@ -241,6 +242,18 @@ class ErrorRecoveryManager:
 
         return None
 
+    def register_degradation_strategy(self, error_type: str, strategy: Callable) -> None:
+        """
+        Register a degradation strategy for a specific error type.
+        
+        Args:
+            error_type: Error type identifier (e.g., "security_errors", "memory")
+            strategy: Callable that handles the error (error, context) -> Any
+        """
+        with self._lock:
+            self.degradation_strategies[error_type] = strategy
+            logger.info(f"📋 Registered degradation strategy for: {error_type}")
+    
     def add_circuit_breaker(self, name: str, config: CircuitBreakerConfig) -> None:
         """Add a circuit breaker."""
         with self._lock:
@@ -307,7 +320,7 @@ class ErrorRecoveryManager:
                 # Calculate next delay
                 delay = min(delay * backoff_factor, max_delay)
 
-        # This should never be reached
+        # Unreachable code path
         raise last_exception
 
     async def async_retry_with_backoff(
@@ -344,7 +357,7 @@ class ErrorRecoveryManager:
                 await asyncio.sleep(delay)
                 delay = min(delay * backoff_factor, max_delay)
 
-        # This should never be reached
+        # Unreachable code path
         raise last_exception
 
     def graceful_degradation(

exonware/xwsystem/monitoring/errors.py

@@ -1,9 +1,10 @@
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/errors.py
 #exonware/xwsystem/monitoring/errors.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 Monitoring module errors - exception classes for monitoring functionality.

exonware/xwsystem/monitoring/facade.py

@@ -0,0 +1,183 @@
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/facade.py
+"""
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.3
+Generation Date: January 2026
+
+XWMonitor - Unified Monitoring Facade
+
+Simplified API for monitoring operations:
+- Performance monitoring
+- Memory monitoring
+- Circuit breakers
+- System monitoring
+"""
+
+from typing import Any, Optional, Callable
+from contextlib import contextmanager
+from functools import wraps
+
+from .performance_monitor import (
+    PerformanceMonitor,
+    performance_context,
+    create_performance_monitor,
+)
+from .memory_monitor import (
+    MemoryMonitor,
+    start_memory_monitoring,
+    stop_memory_monitoring,
+    get_memory_stats,
+    get_memory_monitor,
+)
+from .error_recovery import (
+    CircuitBreaker,
+    CircuitBreakerConfig,
+    circuit_breaker,
+    retry_with_backoff,
+)
+from .system_monitor import (
+    SystemMonitor,
+    get_cpu_usage,
+    get_memory_usage,
+    get_system_info,
+)
+from ..config.logging_setup import get_logger
+
+logger = get_logger(__name__)
+
+
+class XWMonitor:
+    """
+    Unified monitoring facade - simple API for monitoring operations.
+    
+    Examples:
+        >>> # Performance monitoring
+        >>> with XWMonitor.performance("operation"):
+        ...     result = expensive_operation()
+        
+        >>> # Memory monitoring
+        >>> monitor = XWMonitor.memory(auto_cleanup=True)
+        >>> monitor.start()
+        
+        >>> # Circuit breaker
+        >>> @XWMonitor.circuit_breaker(failures=5, timeout=60)
+        >>> def external_api_call():
+        ...     return requests.get("https://api.example.com")
+        
+        >>> # System monitoring
+        >>> cpu = XWMonitor.cpu_usage()
+        >>> memory = XWMonitor.memory_usage()
+        >>> disk = XWMonitor.disk_usage()
+    """
+    
+    @staticmethod
+    @contextmanager
+    def performance(operation_name: str):
+        """
+        Context manager for performance monitoring.
+        
+        Args:
+            operation_name: Name of the operation being monitored
+        """
+        monitor = create_performance_monitor()
+        with performance_context(monitor, operation_name):
+            yield
+    
+    @staticmethod
+    def memory(auto_cleanup: bool = False) -> MemoryMonitor:
+        """
+        Create memory monitor instance.
+        
+        Args:
+            auto_cleanup: Enable automatic memory cleanup
+            
+        Returns:
+            MemoryMonitor instance
+        """
+        monitor = get_memory_monitor()
+        if auto_cleanup:
+            monitor.enable_auto_cleanup()
+        return monitor
+    
+    @staticmethod
+    def start_memory_monitoring(auto_cleanup: bool = False) -> None:
+        """Start memory monitoring."""
+        start_memory_monitoring(auto_cleanup=auto_cleanup)
+    
+    @staticmethod
+    def stop_memory_monitoring() -> None:
+        """Stop memory monitoring."""
+        stop_memory_monitoring()
+    
+    @staticmethod
+    def get_memory_stats() -> dict:
+        """Get current memory statistics."""
+        return get_memory_stats()
+    
+    @staticmethod
+    def circuit_breaker(
+        failures: int = 5,
+        timeout: int = 60,
+        **kwargs
+    ):
+        """
+        Decorator for circuit breaker pattern.
+        
+        Args:
+            failures: Number of failures before opening circuit
+            timeout: Timeout in seconds before attempting recovery
+            **kwargs: Additional circuit breaker options
+            
+        Returns:
+            Decorator function
+        """
+        config = CircuitBreakerConfig(
+            failure_threshold=failures,
+            recovery_timeout=timeout,
+            **kwargs
+        )
+        return circuit_breaker(config=config)
+    
+    @staticmethod
+    def retry(max_attempts: int = 3, backoff: float = 1.0, **kwargs):
+        """
+        Decorator for retry logic.
+        
+        Args:
+            max_attempts: Maximum retry attempts
+            backoff: Backoff multiplier
+            **kwargs: Additional retry options
+            
+        Returns:
+            Decorator function
+        """
+        return retry_with_backoff(max_attempts=max_attempts, backoff=backoff, **kwargs)
+    
+    @staticmethod
+    def cpu_usage() -> float:
+        """Get current CPU usage percentage."""
+        return get_cpu_usage()
+    
+    @staticmethod
+    def memory_usage() -> dict:
+        """Get current memory usage statistics."""
+        return get_memory_usage()
+    
+    @staticmethod
+    def disk_usage(path: str = "/") -> dict:
+        """Get disk usage statistics."""
+        import shutil
+        usage = shutil.disk_usage(path)
+        return {
+            "total": usage.total,
+            "used": usage.used,
+            "free": usage.free,
+            "percent": (usage.used / usage.total) * 100
+        }
+    
+    @staticmethod
+    def system_info() -> dict:
+        """Get system information."""
+        return get_system_info()

exonware/xwsystem/monitoring/memory_monitor.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/memory_monitor.py
 """
 Memory Monitoring and Leak Detection for XSystem Library.
 

exonware/xwsystem/monitoring/metrics.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/metrics.py
 """
 Generic performance metrics and monitoring system.
 

exonware/xwsystem/monitoring/performance_manager_generic.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/performance_manager_generic.py
 #exonware/xwsystem/monitoring/performance_manager_generic.py
 """
 Generic Performance Management for XSystem (Moved from performance/ module)
@@ -10,7 +11,7 @@ health monitoring, and recommendations without being tied to specific implementa
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: November 04, 2025
 """
 
@@ -18,7 +19,7 @@ import threading
 import time
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Any, Optional, Union
+from typing import Any, Optional
 
 from ..config.performance_modes import PerformanceMode
 from ..config.logging_setup import get_logger
@@ -106,19 +107,19 @@ class GenericPerformanceManager:
         """Get the current performance mode (local or global)."""
         if hasattr(self, "_local_mode") and self._local_mode is not None:
             return self._local_mode
-        # This should be overridden by subclasses to get global mode
+        # Override in subclasses to get global mode
         return PerformanceMode.FAST  # Default fallback
 
     def get_effective_config(self) -> Optional[Any]:
         """Get effective config (local or global)."""
         if hasattr(self, "_local_config") and self._local_config is not None:
             return self._local_config
-        # This should be overridden by subclasses to get global config
+        # Override in subclasses to get global config
         return None
 
     def _create_local_config(self, mode: PerformanceMode) -> Any:
         """Create local configuration for the given mode."""
-        # This should be overridden by subclasses
+        # Override in subclasses
         return {"performance_mode": mode}
 
     def get_mode_history(self) -> list[dict[str, Any]]:
@@ -262,7 +263,7 @@ class GenericPerformanceManager:
             ]:
                 self.set_performance_mode(PerformanceMode.ADAPTIVE)
         elif memory_percent < 30 and cache_hit_rate > 0.8:
-            # Good conditions - can use fast mode
+            # Conditions allow fast mode
             if current_mode != PerformanceMode.FAST:
                 self.set_performance_mode(PerformanceMode.FAST)
 
@@ -466,4 +467,3 @@ class GenericPerformanceManager:
     def _apply_manual_overrides(self, config_overrides: dict[str, Any]) -> None:
         """Apply manual configuration overrides. Override in subclasses."""
         pass
-

exonware/xwsystem/monitoring/performance_monitor.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/performance_monitor.py
 """
 Performance Monitoring Utilities for XSystem
 

exonware/xwsystem/monitoring/performance_validator.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/performance_validator.py
 """
 Performance Validation and Monitoring for XSystem Library.
 

exonware/xwsystem/monitoring/system_monitor.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/system_monitor.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 System-wide monitoring and hardware introspection utilities.
@@ -12,7 +13,7 @@ import os
 import platform
 import time
 from dataclasses import dataclass
-from typing import Optional, Any, Union
+from typing import Optional, Any
 from pathlib import Path
 
 # Import psutil - lazy installation system will handle it if missing
@@ -142,7 +143,7 @@ class SystemMonitor:
     
     def is_available(self) -> bool:
         """Check if full system monitoring is available."""
-        # Lazy installation system ensures psutil is always available
+        # Lazy installation system provides psutil when available
         return True
     
     # =============================================================================
@@ -357,7 +358,7 @@ class SystemMonitor:
         
         return SystemInfo(**system_info)
     
-    def get_cpu_usage(self, interval: float = 1.0, per_cpu: bool = False) -> Union[float, list[float]]:
+    def get_cpu_usage(self, interval: float = 1.0, per_cpu: bool = False) -> float | list[float]:
         """
         Get CPU usage percentage.
         
@@ -696,5 +697,5 @@ def get_hardware_info() -> dict[str, Any]:
 
 def is_monitoring_available() -> bool:
     """Check if full system monitoring is available."""
-    # Lazy installation system ensures psutil is always available
+    # Lazy installation system provides psutil when available
     return True

exonware/xwsystem/monitoring/tracing.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/tracing.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: September 05, 2025
 
 Distributed Tracing Integration for Enterprise Observability
@@ -19,7 +20,7 @@ import time
 import uuid
 from contextlib import asynccontextmanager, contextmanager
 from dataclasses import dataclass, field
-from typing import Any, AsyncContextManager, ContextManager, Optional, Union
+from typing import Any, AsyncContextManager, ContextManager, Optional
 from .base import ATracingProvider
 from .errors import TracingError
 from .defs import SpanKind
@@ -92,25 +93,27 @@ class OpenTelemetryTracer(ATracingProvider):
     
     def _setup_otlp_exporter(self, endpoint: str) -> None:
         """Set up OTLP exporter (modern standard, Python 3.8+ only, no legacy deps)."""
+        # Optional dependency: opentelemetry-exporter-otlp-proto-http
         try:
-            # Lazy import to avoid pulling in dependencies unless actually used
-            from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
-            
-            otlp_exporter = OTLPSpanExporter(endpoint=endpoint)
-            span_processor = BatchSpanProcessor(otlp_exporter)
-            trace.get_tracer_provider().add_span_processor(span_processor)
-            logger.info(f"OTLP exporter configured for endpoint: {endpoint}")
-            
-        except ImportError:
-            logger.warning(
-                "OTLP exporter not available. Install with: pip install opentelemetry-exporter-otlp-proto-http"
-            )
+            import importlib.util
+            _otlp_exporter_spec = importlib.util.find_spec('opentelemetry.exporter.otlp.proto.http.trace_exporter')
+            if _otlp_exporter_spec is not None:
+                from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+                
+                otlp_exporter = OTLPSpanExporter(endpoint=endpoint)
+                span_processor = BatchSpanProcessor(otlp_exporter)
+                trace.get_tracer_provider().add_span_processor(span_processor)
+                logger.info(f"OTLP exporter configured for endpoint: {endpoint}")
+            else:
+                logger.warning(
+                    "OTLP exporter not available. Install with: pip install opentelemetry-exporter-otlp-proto-http"
+                )
         except Exception as e:
             logger.warning(f"Failed to setup OTLP exporter: {e}")
     
     def _setup_zipkin_exporter(self, endpoint: str) -> None:
         """Set up Zipkin exporter."""
-        # Import is explicit - if missing, user should install: pip install exonware-xwsystem[observability]
+        # Import is explicit - if missing, install: pip install exonware-xwsystem[observability]
         from opentelemetry.exporter.zipkin.json import ZipkinExporter
         
         try:
@@ -424,4 +427,3 @@ class DistributedTracing:
     def is_tracing_enabled(self) -> bool:
         """Check if tracing is enabled."""
         return self.manager.is_tracing_enabled()
-

exonware/xwsystem/monitoring/tracker.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/monitoring/tracker.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: October 26, 2025
 
 Operation tracker for monitoring operations with context management.

exonware/xwsystem/operations/__init__.py

@@ -1,70 +1,25 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/operations/__init__.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: October 26, 2025
 
 Universal operations library for data manipulation.
 """
 
-from typing import Any, Optional, Union
-from enum import Enum
-from dataclasses import dataclass
 from ..config.logging_setup import get_logger
 
 logger = get_logger("xwsystem.operations")
 
-
-class MergeStrategy(Enum):
-    """Merge strategies for data operations."""
-    DEEP = "deep"           # Recursive merge (default)
-    SHALLOW = "shallow"     # Top-level only
-    OVERWRITE = "overwrite" # Replace entirely
-    APPEND = "append"       # Append lists instead of replacing
-    UNIQUE = "unique"       # Merge lists with uniqueness
-
-
-class DiffMode(Enum):
-    """Diff operation modes."""
-    STRUCTURAL = "structural"  # Compare structure only
-    CONTENT = "content"        # Compare content only
-    FULL = "full"              # Compare both structure and content
-
-
-class PatchOperation(Enum):
-    """JSON Patch operation types."""
-    ADD = "add"
-    REMOVE = "remove"
-    REPLACE = "replace"
-    MOVE = "move"
-    COPY = "copy"
-    TEST = "test"
-
-
-@dataclass
-class DiffResult:
-    """Result of a diff operation."""
-    operations: list[dict[str, Any]]
-    mode: DiffMode
-    paths_changed: list[str]
-    total_changes: int
-
-
-@dataclass
-class PatchResult:
-    """Result of a patch operation."""
-    success: bool
-    operations_applied: int
-    errors: list[str]
-    result: Any
-
-
 # Import from submodules
 from .defs import MergeStrategy, DiffMode, PatchOperation, DiffResult, PatchResult
 from .base import (
-    OperationError, MergeError, DiffError, PatchError,
+    OperationError, MergeError, DiffError, PatchError
+)
+from .contracts import (
     IOperation, IMergeOperation, IDiffOperation, IPatchOperation
 )
 from .merge import MergeOperation, deep_merge

exonware/xwsystem/operations/base.py

@@ -1,17 +1,16 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/operations/base.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.1.0.1
+Version: 0.1.0.3
 Generation Date: October 26, 2025
 
 Base classes and contracts for operations.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Union
-from .defs import MergeStrategy, DiffMode, PatchOperation, DiffResult, PatchResult
+from typing import Optional
 
 
 class OperationError(Exception):
@@ -37,49 +36,9 @@ class PatchError(OperationError):
     pass
 
 
-class IOperation(ABC):
-    """Interface for operations."""
-    
-    @abstractmethod
-    def execute(self, *args, **kwargs) -> Any:
-        """Execute the operation."""
-        pass
-
-
-class IMergeOperation(IOperation):
-    """Interface for merge operations."""
-    
-    @abstractmethod
-    def merge(self, target: Any, source: Any, strategy: MergeStrategy = MergeStrategy.DEEP) -> Any:
-        """Merge source into target."""
-        pass
-
-
-class IDiffOperation(IOperation):
-    """Interface for diff operations."""
-    
-    @abstractmethod
-    def diff(self, original: Any, modified: Any, mode: DiffMode = DiffMode.FULL) -> DiffResult:
-        """Generate diff between original and modified."""
-        pass
-
-
-class IPatchOperation(IOperation):
-    """Interface for patch operations."""
-    
-    @abstractmethod
-    def apply_patch(self, data: Any, operations: list[dict[str, Any]]) -> PatchResult:
-        """Apply patch operations to data."""
-        pass
-
-
 __all__ = [
     "OperationError",
     "MergeError", 
     "DiffError",
     "PatchError",
-    "IOperation",
-    "IMergeOperation",
-    "IDiffOperation", 
-    "IPatchOperation",
 ]