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

exonware/xwsystem/caching/contracts.py

@@ -1,17 +1,16 @@
 #!/usr/bin/env python3
+#exonware/xwsystem/src/exonware/xwsystem/caching/contracts.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
 
 Caching protocol interfaces for XWSystem.
 """
 
-from abc import ABC, abstractmethod
-from typing import Any, Optional, Union, Iterator, Callable, Protocol
-from typing_extensions import runtime_checkable
+from typing import Any, Optional, Iterator, Callable, Protocol, runtime_checkable
 import time
 
 # Import enums from types module
@@ -27,14 +26,14 @@ from .defs import (
 # CACHEABLE INTERFACES
 # ============================================================================
 
-class ICacheable(ABC):
+@runtime_checkable
+class ICacheable(Protocol):
     """
     Interface for cacheable objects.
     
     Enforces consistent caching behavior across XWSystem.
     """
     
-    @abstractmethod
     def cache(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
         """
         Cache a value with key.
@@ -47,9 +46,8 @@ class ICacheable(ABC):
         Returns:
             True if cached successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_cached(self, key: str, default: Any = None) -> Any:
         """
         Get cached value by key.
@@ -61,16 +59,14 @@ class ICacheable(ABC):
         Returns:
             Cached value or default
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_cache(self) -> None:
         """
         Clear all cached values.
         """
-        pass
+        ...
     
-    @abstractmethod
     def has_cached(self, key: str) -> bool:
         """
         Check if key is cached.
@@ -81,9 +77,8 @@ class ICacheable(ABC):
         Returns:
             True if cached
         """
-        pass
+        ...
     
-    @abstractmethod
     def remove_cached(self, key: str) -> bool:
         """
         Remove cached value by key.
@@ -94,9 +89,8 @@ class ICacheable(ABC):
         Returns:
             True if removed
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_cache_size(self) -> int:
         """
         Get number of cached items.
@@ -104,9 +98,8 @@ class ICacheable(ABC):
         Returns:
             Number of cached items
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_cache_info(self) -> dict[str, Any]:
         """
         Get cache information.
@@ -114,21 +107,21 @@ class ICacheable(ABC):
         Returns:
             Cache information dictionary
         """
-        pass
+        ...
 
 
 # ============================================================================
 # CACHE MANAGER INTERFACES
 # ============================================================================
 
-class ICacheManager(ABC):
+@runtime_checkable
+class ICacheManager(Protocol):
     """
     Interface for cache management.
     
     Enforces consistent cache management across XWSystem.
     """
     
-    @abstractmethod
     def create_cache(self, name: str, max_size: int = 1000, policy: CachePolicy = CachePolicy.LRU) -> ICacheable:
         """
         Create a new cache.
@@ -141,9 +134,8 @@ class ICacheManager(ABC):
         Returns:
             Cache instance
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_cache(self, name: str) -> Optional[ICacheable]:
         """
         Get cache by name.
@@ -154,9 +146,8 @@ class ICacheManager(ABC):
         Returns:
             Cache instance or None
         """
-        pass
+        ...
     
-    @abstractmethod
     def remove_cache(self, name: str) -> bool:
         """
         Remove cache by name.
@@ -167,9 +158,8 @@ class ICacheManager(ABC):
         Returns:
             True if removed
         """
-        pass
+        ...
     
-    @abstractmethod
     def list_caches(self) -> list[str]:
         """
         List all cache names.
@@ -177,16 +167,14 @@ class ICacheManager(ABC):
         Returns:
             List of cache names
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear_all_caches(self) -> None:
         """
         Clear all caches.
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_cache_stats(self) -> dict[str, dict[str, Any]]:
         """
         Get statistics for all caches.
@@ -194,9 +182,8 @@ class ICacheManager(ABC):
         Returns:
             Dictionary of cache statistics
         """
-        pass
+        ...
     
-    @abstractmethod
     def set_global_policy(self, policy: CachePolicy) -> None:
         """
         Set global cache policy.
@@ -204,9 +191,8 @@ class ICacheManager(ABC):
         Args:
             policy: Global eviction policy
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_global_policy(self) -> CachePolicy:
         """
         Get global cache policy.
@@ -214,21 +200,21 @@ class ICacheManager(ABC):
         Returns:
             Global eviction policy
         """
-        pass
+        ...
 
 
 # ============================================================================
 # CACHE STORAGE INTERFACES
 # ============================================================================
 
-class ICacheStorage(ABC):
+@runtime_checkable
+class ICacheStorage(Protocol):
     """
     Interface for cache storage backends.
     
     Enforces consistent cache storage across XWSystem.
     """
     
-    @abstractmethod
     def store(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
         """
         Store value in cache.
@@ -241,9 +227,8 @@ class ICacheStorage(ABC):
         Returns:
             True if stored successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def retrieve(self, key: str) -> Optional[Any]:
         """
         Retrieve value from cache.
@@ -254,9 +239,8 @@ class ICacheStorage(ABC):
         Returns:
             Cached value or None
         """
-        pass
+        ...
     
-    @abstractmethod
     def delete(self, key: str) -> bool:
         """
         Delete value from cache.
@@ -267,9 +251,8 @@ class ICacheStorage(ABC):
         Returns:
             True if deleted
         """
-        pass
+        ...
     
-    @abstractmethod
     def exists(self, key: str) -> bool:
         """
         Check if key exists in cache.
@@ -280,16 +263,14 @@ class ICacheStorage(ABC):
         Returns:
             True if exists
         """
-        pass
+        ...
     
-    @abstractmethod
     def clear(self) -> None:
         """
         Clear all cached values.
         """
-        pass
+        ...
     
-    @abstractmethod
     def size(self) -> int:
         """
         Get number of cached items.
@@ -297,9 +278,8 @@ class ICacheStorage(ABC):
         Returns:
             Number of cached items
         """
-        pass
+        ...
     
-    @abstractmethod
     def keys(self) -> Iterator[str]:
         """
         Get iterator over cache keys.
@@ -307,9 +287,8 @@ class ICacheStorage(ABC):
         Yields:
             Cache keys
         """
-        pass
+        ...
     
-    @abstractmethod
     def values(self) -> Iterator[Any]:
         """
         Get iterator over cache values.
@@ -317,9 +296,8 @@ class ICacheStorage(ABC):
         Yields:
             Cache values
         """
-        pass
+        ...
     
-    @abstractmethod
     def items(self) -> Iterator[tuple[str, Any]]:
         """
         Get iterator over cache items.
@@ -327,21 +305,21 @@ class ICacheStorage(ABC):
         Yields:
             Tuples of (key, value)
         """
-        pass
+        ...
 
 
 # ============================================================================
 # CACHE EVICTION INTERFACES
 # ============================================================================
 
-class ICacheEviction(ABC):
+@runtime_checkable
+class ICacheEviction(Protocol):
     """
     Interface for cache eviction strategies.
     
     Enforces consistent cache eviction across XWSystem.
     """
     
-    @abstractmethod
     def should_evict(self, cache_size: int, max_size: int) -> bool:
         """
         Check if eviction is needed.
@@ -353,9 +331,8 @@ class ICacheEviction(ABC):
         Returns:
             True if eviction needed
         """
-        pass
+        ...
     
-    @abstractmethod
     def select_eviction_candidate(self, items: list[tuple[str, Any, float]]) -> str:
         """
         Select item to evict.
@@ -366,9 +343,8 @@ class ICacheEviction(ABC):
         Returns:
             Key of item to evict
         """
-        pass
+        ...
     
-    @abstractmethod
     def update_access(self, key: str, timestamp: float) -> None:
         """
         Update access information for key.
@@ -377,9 +353,8 @@ class ICacheEviction(ABC):
             key: Cache key
             timestamp: Access timestamp
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_eviction_policy(self) -> CachePolicy:
         """
         Get eviction policy.
@@ -387,9 +362,8 @@ class ICacheEviction(ABC):
         Returns:
             Eviction policy
         """
-        pass
+        ...
     
-    @abstractmethod
     def set_eviction_policy(self, policy: CachePolicy) -> None:
         """
         Set eviction policy.
@@ -397,9 +371,8 @@ class ICacheEviction(ABC):
         Args:
             policy: Eviction policy to set
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_eviction_stats(self) -> dict[str, Any]:
         """
         Get eviction statistics.
@@ -407,21 +380,21 @@ class ICacheEviction(ABC):
         Returns:
             Eviction statistics dictionary
         """
-        pass
+        ...
 
 
 # ============================================================================
 # CACHE MONITORING INTERFACES
 # ============================================================================
 
-class ICacheMonitor(ABC):
+@runtime_checkable
+class ICacheMonitor(Protocol):
     """
     Interface for cache monitoring.
     
     Enforces consistent cache monitoring across XWSystem.
     """
     
-    @abstractmethod
     def record_hit(self, key: str) -> None:
         """
         Record cache hit.
@@ -429,9 +402,8 @@ class ICacheMonitor(ABC):
         Args:
             key: Cache key that was hit
         """
-        pass
+        ...
     
-    @abstractmethod
     def record_miss(self, key: str) -> None:
         """
         Record cache miss.
@@ -439,9 +411,8 @@ class ICacheMonitor(ABC):
         Args:
             key: Cache key that was missed
         """
-        pass
+        ...
     
-    @abstractmethod
     def record_set(self, key: str, size: int) -> None:
         """
         Record cache set operation.
@@ -450,9 +421,8 @@ class ICacheMonitor(ABC):
             key: Cache key that was set
             size: Size of cached value
         """
-        pass
+        ...
     
-    @abstractmethod
     def record_delete(self, key: str) -> None:
         """
         Record cache delete operation.
@@ -460,9 +430,8 @@ class ICacheMonitor(ABC):
         Args:
             key: Cache key that was deleted
         """
-        pass
+        ...
     
-    @abstractmethod
     def record_eviction(self, key: str, reason: str) -> None:
         """
         Record cache eviction.
@@ -471,9 +440,8 @@ class ICacheMonitor(ABC):
             key: Cache key that was evicted
             reason: Eviction reason
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_hit_rate(self) -> float:
         """
         Get cache hit rate.
@@ -481,9 +449,8 @@ class ICacheMonitor(ABC):
         Returns:
             Hit rate as percentage (0.0 to 1.0)
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_miss_rate(self) -> float:
         """
         Get cache miss rate.
@@ -491,9 +458,8 @@ class ICacheMonitor(ABC):
         Returns:
             Miss rate as percentage (0.0 to 1.0)
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_stats(self) -> dict[str, Any]:
         """
         Get cache statistics.
@@ -501,28 +467,27 @@ class ICacheMonitor(ABC):
         Returns:
             Statistics dictionary
         """
-        pass
+        ...
     
-    @abstractmethod
     def reset_stats(self) -> None:
         """
         Reset cache statistics.
         """
-        pass
+        ...
 
 
 # ============================================================================
 # DISTRIBUTED CACHE INTERFACES
 # ============================================================================
 
-class IDistributedCache(ABC):
+@runtime_checkable
+class IDistributedCache(Protocol):
     """
     Interface for distributed cache operations.
     
     Enforces consistent distributed caching across XWSystem.
     """
     
-    @abstractmethod
     def get_node_id(self) -> str:
         """
         Get current node ID.
@@ -530,9 +495,8 @@ class IDistributedCache(ABC):
         Returns:
             Node identifier
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_cluster_nodes(self) -> list[str]:
         """
         Get list of cluster nodes.
@@ -540,9 +504,8 @@ class IDistributedCache(ABC):
         Returns:
             List of node IDs
         """
-        pass
+        ...
     
-    @abstractmethod
     def replicate(self, key: str, value: Any, nodes: list[str]) -> bool:
         """
         Replicate cache entry to nodes.
@@ -555,9 +518,8 @@ class IDistributedCache(ABC):
         Returns:
             True if replicated successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def invalidate(self, key: str, nodes: list[str]) -> bool:
         """
         Invalidate cache entry on nodes.
@@ -569,9 +531,8 @@ class IDistributedCache(ABC):
         Returns:
             True if invalidated successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def sync_with_node(self, node_id: str) -> bool:
         """
         Sync cache with specific node.
@@ -582,9 +543,8 @@ class IDistributedCache(ABC):
         Returns:
             True if synced successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_consistency_level(self) -> str:
         """
         Get cache consistency level.
@@ -592,9 +552,8 @@ class IDistributedCache(ABC):
         Returns:
             Consistency level (e.g., 'strong', 'eventual')
         """
-        pass
+        ...
     
-    @abstractmethod
     def set_consistency_level(self, level: str) -> None:
         """
         Set cache consistency level.
@@ -602,21 +561,21 @@ class IDistributedCache(ABC):
         Args:
             level: Consistency level
         """
-        pass
+        ...
 
 
 # ============================================================================
 # CACHE DECORATOR INTERFACES
 # ============================================================================
 
-class ICacheDecorator(ABC):
+@runtime_checkable
+class ICacheDecorator(Protocol):
     """
     Interface for cache decorators.
     
     Enforces consistent cache decoration across XWSystem.
     """
     
-    @abstractmethod
     def cache_result(self, func: Callable, ttl: Optional[int] = None, key_func: Optional[Callable] = None) -> Callable:
         """
         Decorate function to cache results.
@@ -629,9 +588,8 @@ class ICacheDecorator(ABC):
         Returns:
             Decorated function
         """
-        pass
+        ...
     
-    @abstractmethod
     def cache_invalidate(self, func: Callable, key_func: Optional[Callable] = None) -> Callable:
         """
         Decorate function to invalidate cache.
@@ -643,9 +601,8 @@ class ICacheDecorator(ABC):
         Returns:
             Decorated function
         """
-        pass
+        ...
     
-    @abstractmethod
     def cache_clear(self, func: Callable) -> Callable:
         """
         Decorate function to clear cache.
@@ -656,9 +613,8 @@ class ICacheDecorator(ABC):
         Returns:
             Decorated function
         """
-        pass
+        ...
     
-    @abstractmethod
     def cache_conditional(self, func: Callable, condition: Callable[[Any], bool]) -> Callable:
         """
         Decorate function with conditional caching.
@@ -670,21 +626,21 @@ class ICacheDecorator(ABC):
         Returns:
             Decorated function
         """
-        pass
+        ...
 
 
 # ============================================================================
 # CACHE PERSISTENCE INTERFACES
 # ============================================================================
 
-class ICachePersistence(ABC):
+@runtime_checkable
+class ICachePersistence(Protocol):
     """
     Interface for cache persistence.
     
     Enforces consistent cache persistence across XWSystem.
     """
     
-    @abstractmethod
     def save_cache(self, cache_name: str, file_path: str) -> bool:
         """
         Save cache to file.
@@ -696,9 +652,8 @@ class ICachePersistence(ABC):
         Returns:
             True if saved successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def load_cache(self, cache_name: str, file_path: str) -> bool:
         """
         Load cache from file.
@@ -710,9 +665,8 @@ class ICachePersistence(ABC):
         Returns:
             True if loaded successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def backup_cache(self, cache_name: str, backup_path: str) -> bool:
         """
         Backup cache to file.
@@ -724,9 +678,8 @@ class ICachePersistence(ABC):
         Returns:
             True if backed up successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def restore_cache(self, cache_name: str, backup_path: str) -> bool:
         """
         Restore cache from backup.
@@ -738,9 +691,8 @@ class ICachePersistence(ABC):
         Returns:
             True if restored successfully
         """
-        pass
+        ...
     
-    @abstractmethod
     def get_persistence_format(self) -> str:
         """
         Get persistence format.
@@ -748,9 +700,8 @@ class ICachePersistence(ABC):
         Returns:
             Format name (e.g., 'pickle', 'json')
         """
-        pass
+        ...
     
-    @abstractmethod
     def set_persistence_format(self, format_name: str) -> None:
         """
         Set persistence format.
@@ -758,14 +709,15 @@ class ICachePersistence(ABC):
         Args:
             format_name: Format name
         """
-        pass
+        ...
 
 
 # ============================================================================
 # BASIC CACHE INTERFACE
 # ============================================================================
 
-class ICache(ABC):
+@runtime_checkable
+class ICache(Protocol):
     """
     Basic cache interface for disk-based and specialized caches.
     
@@ -776,35 +728,29 @@ class ICache(ABC):
     use string keys (like disk caches and two-tier caches).
     """
     
-    @abstractmethod
     def get(self, key: str) -> Optional[Any]:
         """Get value from cache."""
-        pass
+        ...
     
-    @abstractmethod
     def set(self, key: str, value: Any, ttl: Optional[int] = None) -> bool:
         """Set value in cache."""
-        pass
+        ...
     
-    @abstractmethod
     def delete(self, key: str) -> bool:
         """Delete value from cache."""
-        pass
+        ...
     
-    @abstractmethod
     def clear(self) -> bool:
         """Clear all cached values."""
-        pass
+        ...
     
-    @abstractmethod
     def exists(self, key: str) -> bool:
         """Check if key exists in cache."""
-        pass
+        ...
     
-    @abstractmethod
     def size(self) -> int:
         """Get number of cached items."""
-        pass
+        ...
 
 
 # ============================================================================
@@ -812,8 +758,8 @@ class ICache(ABC):
 # ============================================================================
 
 @runtime_checkable
-class Cacheable(Protocol):
-    """Protocol for objects that support caching."""
+class ICacheableSimple(Protocol):
+    """Protocol for objects that support caching (simpler interface than ICacheable)."""
     
     def get(self, key: str, default: Any = None) -> Any:
         """Get value from cache."""