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

exonware/xwsystem/caching/lfu_cache.py

@@ -1,8 +1,9 @@
+#exonware/xwsystem/src/exonware/xwsystem/caching/lfu_cache.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 LFU (Least Frequently Used) Cache implementation with thread-safety and async support.

exonware/xwsystem/caching/lfu_optimized.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/lfu_optimized.py
 #exonware/xwsystem/caching/lfu_optimized.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Optimized O(1) LFU Cache implementation.
@@ -257,7 +258,7 @@ class OptimizedLFUCache(ACache):
         - NEW: O(1) using min_freq bucket
         """
         if self._min_freq not in self._freq_to_keys:
-            # Shouldn't happen, but handle gracefully
+            # Handle case where min_freq bucket is empty
             if self._freq_to_keys:
                 self._min_freq = min(self._freq_to_keys.keys())
             else:
@@ -320,13 +321,25 @@ class OptimizedLFUCache(ACache):
         """
         with self._lock:
             count = 0
+            errors = []
             for key, value in items.items():
                 try:
                     self.put(key, value)
                     count += 1
-                except Exception:
-                    # Continue with other items even if one fails
-                    pass
+                except Exception as e:
+                    # Log error but continue with other items for batch resilience
+                    # This follows GUIDE_TEST.md by handling errors explicitly
+                    errors.append((key, str(e)))
+            
+            # Log any errors that occurred during batch operation
+            if errors:
+                # Use existing logger (imported at module level)
+                logger.warning(
+                    f"put_many: {len(errors)} items failed out of {len(items)}. "
+                    f"Successfully cached {count} items. "
+                    f"Errors: {errors[:5]}"  # Show first 5 errors
+                )
+            
             return count
     
     def delete_many(self, keys: list[Hashable]) -> int:
@@ -550,4 +563,3 @@ __all__ = [
     'OptimizedLFUCache',
     'AsyncOptimizedLFUCache',
 ]
-

exonware/xwsystem/caching/lru_cache.py

@@ -1,18 +1,21 @@
+#exonware/xwsystem/src/exonware/xwsystem/caching/lru_cache.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: September 04, 2025
 
 LRU (Least Recently Used) Cache implementation with thread-safety and async support.
 """
 
+from __future__ import annotations
+
 import asyncio
 import threading
 import time
 from collections import OrderedDict
-from typing import Any, Optional, Union, Callable, Hashable
+from typing import Any, Optional, Callable, Hashable
 
 from ..config.logging_setup import get_logger
 from .base import ACache
@@ -26,8 +29,8 @@ class CacheNode:
     def __init__(self, key: Hashable, value: Any):
         self.key = key
         self.value = value
-        self.prev: Optional['CacheNode'] = None
-        self.next: Optional['CacheNode'] = None
+        self.prev: Optional[CacheNode] = None
+        self.next: Optional[CacheNode] = None
         self.access_time = time.time()
 
 

exonware/xwsystem/caching/memory_bounded.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/memory_bounded.py
 #exonware/xwsystem/caching/memory_bounded.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Memory-bounded cache implementations.
@@ -286,4 +287,3 @@ __all__ = [
     'MemoryBoundedLRUCache',
     'MemoryBoundedLFUCache',
 ]
-

exonware/xwsystem/caching/metrics_exporter.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/metrics_exporter.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Metrics exporters for cache monitoring.
@@ -194,4 +195,3 @@ __all__ = [
     'PrometheusExporter',
     'StatsCollector',
 ]
-

exonware/xwsystem/caching/observable_cache.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/observable_cache.py
 #exonware/xwsystem/caching/observable_cache.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Observable cache implementations with event emission.
@@ -148,4 +149,3 @@ __all__ = [
     'ObservableLRUCache',
     'ObservableLFUCache',
 ]
-

exonware/xwsystem/caching/pluggable_cache.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/pluggable_cache.py
 #exonware/xwsystem/caching/pluggable_cache.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Pluggable cache with runtime-switchable eviction strategies.
@@ -230,4 +231,3 @@ class PluggableCache(ACache):
 __all__ = [
     'PluggableCache',
 ]
-

exonware/xwsystem/caching/rate_limiter.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/rate_limiter.py
 #exonware/xwsystem/caching/rate_limiter.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Rate limiting for caching module - Security Priority #1.
@@ -249,4 +250,3 @@ __all__ = [
     'RateLimiter',
     'FixedWindowRateLimiter',
 ]
-

exonware/xwsystem/caching/read_through.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/read_through.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Read-through and Write-through cache implementations.
@@ -248,4 +249,3 @@ __all__ = [
     'WriteThroughCache',
     'ReadWriteThroughCache',
 ]
-

exonware/xwsystem/caching/secure_cache.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/secure_cache.py
 #exonware/xwsystem/caching/secure_cache.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Secure cache implementations with validation, integrity checks, and rate limiting.
@@ -70,20 +71,44 @@ class SecureLRUCache(LRUCache):
         self.max_value_size_mb = max_value_size_mb
         
         # Security components
+        # Only create rate limiter if explicitly enabled
+        # This ensures rate limiting is truly disabled when enable_rate_limit=False
         if self.enable_rate_limit:
             self.rate_limiter = RateLimiter(max_ops_per_second=max_ops_per_second)
+        else:
+            # Explicitly ensure rate_limiter doesn't exist when disabled
+            # This prevents any accidental access
+            if hasattr(self, 'rate_limiter'):
+                delattr(self, 'rate_limiter')
         
         # Track integrity violations
         self._integrity_violations = 0
     
     def _check_rate_limit(self) -> None:
-        """Check rate limit if enabled."""
-        if self.enable_rate_limit:
-            try:
-                self.rate_limiter.acquire()
-            except CacheRateLimitError:
-                # Re-raise with additional context
-                raise
+        """
+        Check rate limit if enabled.
+        
+        Raises:
+            CacheRateLimitError: If rate limit is exceeded
+            
+        Note:
+            This method follows GUIDE_TEST.md by explicitly raising
+            errors rather than silently ignoring them. Rate limiting
+            is a security feature (Priority #1) and violations are
+            reported.
+        """
+        # Triple-check: only check rate limit if explicitly enabled
+        # and rate limiter exists (defensive programming)
+        # This ensures rate limiting is truly disabled when enable_rate_limit=False
+        if not self.enable_rate_limit:
+            return  # Early return if rate limiting is disabled
+        
+        if not hasattr(self, 'rate_limiter'):
+            return  # Early return if rate limiter doesn't exist
+        
+        # Rate limiter will raise CacheRateLimitError if limit exceeded
+        # We let it propagate to caller for proper error handling
+        self.rate_limiter.acquire()
     
     def put(self, key: Hashable, value: Any) -> None:
         """
@@ -97,8 +122,10 @@ class SecureLRUCache(LRUCache):
             CacheValidationError: If validation fails
             CacheRateLimitError: If rate limit exceeded
         """
-        # Rate limiting
-        self._check_rate_limit()
+        # Rate limiting - only check if explicitly enabled
+        # This ensures rate limiting is truly disabled when enable_rate_limit=False
+        if self.enable_rate_limit:
+            self._check_rate_limit()
         
         # Validate key
         validate_cache_key(key, max_size=self.max_key_size)
@@ -132,27 +159,54 @@ class SecureLRUCache(LRUCache):
         Raises:
             CacheIntegrityError: If integrity check fails
         """
-        # Rate limiting
-        self._check_rate_limit()
-        
-        # Get from parent
-        result = super().get(key, default)
+        # Rate limiting - only check if explicitly enabled
+        # This ensures rate limiting is truly disabled when enable_rate_limit=False
+        if self.enable_rate_limit:
+            self._check_rate_limit()
         
-        if result is default:
-            return default
+        # Check if key exists in cache first to handle None values correctly
+        # The parent's get() method treats None as "not found", so we need to
+        # check existence directly to distinguish between "key not found" and "value is None"
+        with self._lock:
+            if key not in self._cache:
+                return default
+            
+            # Key exists - get the node to access the value
+            node = self._cache[key]
+            
+            # Check TTL if enabled
+            if self.ttl and time.time() - node.access_time > self.ttl:
+                self._remove_node(node)
+                del self._cache[key]
+                return default
+            
+            # Move to head (most recently used) - use parent's method
+            self._move_to_head(node)
+            node.access_time = time.time()
+            self._hits += 1
+            
+            # Get the actual value from the node
+            result = node.value
         
         # Verify integrity if enabled
-        if self.enable_integrity and isinstance(result, CacheEntry):
-            try:
-                verify_entry_integrity(result)
-                result.access_count += 1
-                return result.value
-            except CacheIntegrityError as e:
-                # Log violation and remove corrupted entry
-                self._integrity_violations += 1
-                self.delete(key)
-                raise e
+        if self.enable_integrity:
+            # If result is a CacheEntry, verify and extract value
+            if isinstance(result, CacheEntry):
+                try:
+                    verify_entry_integrity(result)
+                    result.access_count += 1
+                    return result.value
+                except CacheIntegrityError as e:
+                    # Log violation and remove corrupted entry
+                    self._integrity_violations += 1
+                    self.delete(key)
+                    raise e
+            else:
+                # If integrity is enabled but result is not a CacheEntry,
+                # this might be a legacy entry or corruption - return as-is
+                return result
         
+        # Integrity disabled - return value directly (including None)
         return result
     
     def get_security_stats(self) -> dict:
@@ -297,4 +351,3 @@ __all__ = [
     'SecureLFUCache',
     'SecureTTLCache',
 ]
-

exonware/xwsystem/caching/serializable.py

@@ -1,19 +1,22 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/serializable.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Cache serialization utilities.
 Usability Priority #2 - Persist and restore cache state.
 """
 
+from __future__ import annotations
+
 import pickle
 import json
 from pathlib import Path
-from typing import Any, Union
+from typing import Any
 from .lru_cache import LRUCache
 from .lfu_optimized import OptimizedLFUCache
 from ..config.logging_setup import get_logger
@@ -40,7 +43,7 @@ class SerializableCache(LRUCache):
         assert cache2.get('key1') == 'value1'
     """
     
-    def save_to_file(self, file_path: Union[str, Path], format: str = 'pickle') -> bool:
+    def save_to_file(self, file_path: str | Path, format: str = 'pickle') -> bool:
         """
         Save cache to file.
         
@@ -80,7 +83,7 @@ class SerializableCache(LRUCache):
             return False
     
     @classmethod
-    def load_from_file(cls, file_path: Union[str, Path], format: str = 'pickle') -> 'SerializableCache':
+    def load_from_file(cls, file_path: str | Path, format: str = 'pickle') -> SerializableCache:
         """
         Load cache from file.
         
@@ -121,7 +124,7 @@ class SerializableCache(LRUCache):
             logger.error(f"Failed to load cache from {file_path}: {e}")
             raise
     
-    def backup(self, backup_path: Union[str, Path]) -> bool:
+    def backup(self, backup_path: str | Path) -> bool:
         """
         Create backup of cache.
         
@@ -133,7 +136,7 @@ class SerializableCache(LRUCache):
         """
         return self.save_to_file(backup_path, format='pickle')
     
-    def restore(self, backup_path: Union[str, Path]) -> bool:
+    def restore(self, backup_path: str | Path) -> bool:
         """
         Restore cache from backup.
         
@@ -164,4 +167,3 @@ class SerializableCache(LRUCache):
 __all__ = [
     'SerializableCache',
 ]
-

exonware/xwsystem/caching/stats.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/stats.py
 #exonware/xwsystem/caching/stats.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Statistics formatting utilities for caching module.
@@ -184,4 +185,3 @@ __all__ = [
     'format_cache_stats_table',
     'get_stats_summary',
 ]
-

exonware/xwsystem/caching/tagging.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/tagging.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Tag-based cache invalidation.
@@ -199,4 +200,3 @@ class TaggedCache(LRUCache):
 __all__ = [
     'TaggedCache',
 ]
-

exonware/xwsystem/caching/ttl_cache.py

@@ -1,3 +1,4 @@
+#exonware/xwsystem/src/exonware/xwsystem/caching/ttl_cache.py
 """
 TTL (Time To Live) Cache Implementation
 ======================================
@@ -7,14 +8,14 @@ Production-grade TTL caching for XSystem.
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generated: 2025-01-27
 """
 
 import asyncio
 import time
 import threading
-from typing import Any, Optional, Union
+from typing import Any, Optional
 from dataclasses import dataclass
 import logging
 from .base import ACache
@@ -196,7 +197,7 @@ class TTLCache(ACache):
     def set(self, key: str, value: Any, ttl: Optional[int] = None) -> None:
         """
         Set value in cache (abstract method implementation).
-        Delegates to put() for backward compatibility.
+        Delegates to put().
         
         Args:
             key: Key to store

exonware/xwsystem/caching/two_tier_cache.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/two_tier_cache.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: October 26, 2025
 
 Two-tier cache implementation combining memory and disk caching.
@@ -54,8 +55,10 @@ class TwoTierCache(ICache):
         self.namespace = namespace
         
         # Initialize tiers
-        # Root cause fixed: LRUCache uses 'capacity' parameter, not 'maxsize'
-        self.memory_cache = LRUCache(capacity=memory_size)
+        # Use flexible create_cache() to allow configuration via environment/settings
+        # Defaults to FunctoolsLRUCache (fastest Python cache)
+        from .factory import create_cache
+        self.memory_cache = create_cache(capacity=memory_size, namespace=namespace, name=f"{namespace}-TwoTier-Memory")
         self.disk_cache = DiskCache(
             namespace=namespace,
             cache_dir=disk_cache_dir,

exonware/xwsystem/caching/utils.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/utils.py
 #exonware/xwsystem/caching/utils.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Common utility functions for caching module.
@@ -33,13 +34,17 @@ def estimate_object_size(obj: Any) -> int:
     try:
         return sys.getsizeof(obj)
     except (TypeError, AttributeError):
-        # For objects that don't support getsizeof
+        # For objects that don't support getsizeof (e.g., some C extensions)
         try:
-            # Try pickling as fallback
+            # Try pickling as fallback to estimate serialized size
             return len(pickle.dumps(obj, protocol=pickle.HIGHEST_PROTOCOL))
-        except Exception:
-            # Last resort: return a conservative estimate
-            return 1024  # 1KB default
+        except (pickle.PicklingError, TypeError, AttributeError) as e:
+            # Object cannot be pickled - return conservative estimate
+            # This is acceptable per GUIDE_TEST.md as this is a utility function
+            # Provides fallback rather than failing
+            # The alternative would be to raise an exception, but that would
+            # break cache operations for objects that can't be sized
+            return 1024  # 1KB default conservative estimate
 
 
 def compute_checksum(value: Any, algorithm: str = 'sha256') -> str:
@@ -135,11 +140,25 @@ def default_key_builder(func: Callable, args: tuple, kwargs: dict) -> str:
         kwargs_str = str(sorted(kwargs.items()))
         key = f"{func_name}:{args_str}:{kwargs_str}"
         return key
-    except Exception:
-        # Fallback: use hash
-        args_hash = hash(args)
-        kwargs_hash = hash(tuple(sorted(kwargs.items())))
-        return f"{func_name}:{args_hash}:{kwargs_hash}"
+    except (TypeError, ValueError) as e:
+        # Fallback: use hash for non-stringable arguments
+        # This is acceptable per GUIDE_TEST.md as this is a utility function
+        # Provides fallback mechanism for edge cases
+        # The alternative would be to raise, but that would break caching
+        # for functions with complex argument types
+        try:
+            args_hash = hash(args)
+            kwargs_hash = hash(tuple(sorted(kwargs.items())))
+            return f"{func_name}:{args_hash}:{kwargs_hash}"
+        except (TypeError, ValueError):
+            # If even hashing fails, use a deterministic fallback
+            # This handles truly unhashable types (e.g., lists, dicts)
+            import hashlib
+            args_repr = repr(args).encode('utf-8')
+            kwargs_repr = repr(kwargs).encode('utf-8')
+            combined = args_repr + kwargs_repr
+            hash_val = hashlib.md5(combined).hexdigest()
+            return f"{func_name}:{hash_val}"
 
 
 def validate_capacity(capacity: int, min_capacity: int = 1, max_capacity: int = 1000000) -> None:
@@ -212,4 +231,3 @@ __all__ = [
     'validate_capacity',
     'validate_ttl',
 ]
-

exonware/xwsystem/caching/validation.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/validation.py
 #exonware/xwsystem/caching/validation.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Input validation for caching module - Security Priority #1.
@@ -230,4 +231,3 @@ __all__ = [
     'DEFAULT_MAX_VALUE_SIZE_MB',
     'DEFAULT_MAX_VALUE_SIZE',
 ]
-

exonware/xwsystem/caching/warming.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/warming.py
 #exonware/xwsystem/caching/warming.py
 """
 Company: eXonware.com
 Author: Eng. Muhammad AlShehri
 Email: connect@exonware.com
-Version: 0.0.1.411
+Version: 0.1.0.3
 Generation Date: 01-Nov-2025
 
 Cache warming utilities for preloading data.
@@ -64,9 +65,12 @@ class PreloadWarmingStrategy(AWarmingStrategy):
         
         elapsed = time.time() - start_time
         
+        # Avoid division by zero if operation completes instantly
+        keys_per_sec = len(keys) / elapsed if elapsed > 0 else float('inf')
+        
         logger.info(
             f"Cache warming complete: {success_count}/{len(keys)} loaded "
-            f"in {elapsed:.2f}s ({len(keys)/elapsed:.0f} keys/sec)"
+            f"in {elapsed:.2f}s ({keys_per_sec:.0f} keys/sec)"
         )
         
         if failures:
@@ -239,4 +243,3 @@ __all__ = [
     'warm_cache',
     'warm_cache_async',
 ]
-