cacheado 1.0.1__py3-none-any.whl

eviction_policies/lre_eviction.py

@@ -0,0 +1,130 @@
+import threading
+from collections import OrderedDict, defaultdict
+from typing import DefaultDict, Optional
+
+from cache_types import _CacheKey
+from protocols.eviction_policy import IEvictionPolicy
+
+
+class LRUEvictionPolicy(IEvictionPolicy):
+    """
+    Implements IEvictionPolicy using a thread-safe Least Recently Used (LRU) strategy.
+    Optimized with __slots__ for memory efficiency.
+    """
+
+    __slots__ = ("_lock", "_lru_tracker", "_namespaced_lru_trackers")
+
+    def __init__(self):
+        """Initializes the LRU policy trackers and lock."""
+        self._lock = threading.Lock()
+        self._lru_tracker: OrderedDict[_CacheKey, None] = OrderedDict()
+        self._namespaced_lru_trackers: DefaultDict[str, OrderedDict[_CacheKey, None]] = defaultdict(OrderedDict)
+
+    def notify_set(
+        self, key: _CacheKey, namespace: str, max_items: Optional[int], global_max_size: Optional[int]
+    ) -> Optional[_CacheKey]:
+        """
+        Adds an item to LRU trackers and evicts an old item if limits are hit.
+
+        Logic:
+        1. Adds the new key to both global and namespace-specific LRU trackers
+        2. Checks namespace limit first - if exceeded, evicts oldest item from namespace
+        3. If no namespace eviction, checks global limit - if exceeded, evicts globally oldest item
+        4. Removes evicted key from all relevant trackers to maintain consistency
+
+        Args:
+            key (_CacheKey): The key that was set.
+            namespace (str): The namespace of the key.
+            max_items (Optional[int]): The max_items limit for this namespace.
+            global_max_size (Optional[int]): The global max_size limit.
+
+        Returns:
+            Optional[_CacheKey]: The key to evict, or None.
+        """
+        with self._lock:
+            self._lru_tracker[key] = None
+            if namespace:
+                self._namespaced_lru_trackers[namespace][key] = None
+
+            key_to_evict: Optional[_CacheKey] = None
+
+            if max_items is not None:
+                ns_tracker = self._namespaced_lru_trackers[namespace]
+                if len(ns_tracker) > max_items:
+                    try:
+                        key_to_evict, _ = ns_tracker.popitem(last=False)
+                    except (KeyError, Exception):
+                        pass
+
+            if key_to_evict is None and global_max_size is not None:
+                if len(self._lru_tracker) > global_max_size:
+                    try:
+                        key_to_evict, _ = self._lru_tracker.popitem(last=False)
+                    except KeyError:
+                        pass
+
+            if key_to_evict:
+                self._lru_tracker.pop(key_to_evict, None)
+
+                evicted_ns = key_to_evict[1]
+                if evicted_ns in self._namespaced_lru_trackers:
+                    self._namespaced_lru_trackers[evicted_ns].pop(key_to_evict, None)
+
+            return key_to_evict
+
+    def notify_get(self, key: _CacheKey, namespace: str) -> None:
+        """
+        Moves the accessed item to the end (MRU) of the LRU trackers.
+
+        Args:
+            key (_CacheKey): The key that was accessed.
+            namespace (str): The namespace of the key.
+        """
+        with self._lock:
+            try:
+                self._lru_tracker.move_to_end(key)
+                if namespace in self._namespaced_lru_trackers:
+                    self._namespaced_lru_trackers[namespace].move_to_end(key)
+            except (KeyError, Exception):
+                pass
+
+    def notify_evict(self, key: _CacheKey, namespace: str) -> None:
+        """
+        Removes an item from all LRU trackers.
+
+        Args:
+            key (_CacheKey): The key that was evicted.
+            namespace (str): The namespace of the key.
+        """
+        with self._lock:
+            self._lru_tracker.pop(key, None)
+            if namespace in self._namespaced_lru_trackers:
+                self._namespaced_lru_trackers[namespace].pop(key, None)
+                if not self._namespaced_lru_trackers[namespace]:
+                    del self._namespaced_lru_trackers[namespace]
+
+    def notify_clear(self) -> None:
+        """Clears all LRU trackers."""
+        with self._lock:
+            self._lru_tracker.clear()
+            self._namespaced_lru_trackers.clear()
+
+    def get_namespace_count(self) -> int:
+        """
+        Returns the total number of tracked namespaces.
+
+        Returns:
+            int: The count of namespaces.
+        """
+        with self._lock:
+            return len(self._namespaced_lru_trackers)
+
+    def get_global_size(self) -> int:
+        """
+        Returns the total number of items tracked by the policy.
+
+        Returns:
+            int: The global item count.
+        """
+        with self._lock:
+            return len(self._lru_tracker)

protocols/cache.py

@@ -0,0 +1,183 @@
+from typing import Any, Awaitable, Callable, Dict, Optional, Protocol, Union
+
+from cache_types import _CacheScope, _FuncT
+from protocols.eviction_policy import IEvictionPolicy
+from protocols.storage_provider import IStorageProvider
+
+
+class ICache(Protocol):
+    """
+    Interface (Protocol) defining the public API for the Cache.
+
+    This allows for Dependency Injection and testability, enabling
+    consumers to depend on this interface rather than the concrete
+    Singleton implementation.
+    """
+
+    def get(
+        self, key: Any, scope: _CacheScope = "global", organization_id: Optional[str] = None, user_id: Optional[str] = None
+    ) -> Optional[Any]:
+        """
+        Gets an item programmatically from the cache.
+
+        Args:
+            key (Any): The key to look up (must be hashable).
+            scope (_CacheScope): The scope ('global', 'organization', 'user').
+            organization_id (Optional[str]): Required if scope='organization'.
+            user_id (Optional[str]): Required if scope='user'.
+
+        Returns:
+            Optional[Any]: The cached value or None if not found or expired.
+        """
+        ...
+
+    def set(
+        self,
+        key: Any,
+        value: Any,
+        ttl_seconds: Union[int, float],
+        scope: _CacheScope = "global",
+        organization_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> None:
+        """
+        Sets an item programmatically in the cache.
+
+        Args:
+            key (Any): The key (must be hashable).
+            value (Any): The value to store.
+            ttl_seconds (Union[int, float]): Time-to-live in seconds.
+            scope (_CacheScope): The scope ('global', 'organization', 'user').
+            organization_id (Optional[str]): Required if scope='organization'.
+            user_id (Optional[str]): Required if scope='user'.
+        """
+        ...
+
+    def evict(
+        self, key: Any, scope: _CacheScope = "global", organization_id: Optional[str] = None, user_id: Optional[str] = None
+    ) -> None:
+        """
+        Removes a specific item programmatically from the cache.
+
+        Args:
+            key (Any): The key to remove (must be hashable).
+            scope (_CacheScope): The scope ('global', 'organization', 'user').
+            organization_id (Optional[str]): Required if scope='organization'.
+            user_id (Optional[str]): Required if scope='user'.
+        """
+        ...
+
+    def clear(self) -> None:
+        """Safely clears the entire cache."""
+        ...
+
+    def aget(
+        self, key: Any, scope: _CacheScope = "global", organization_id: Optional[str] = None, user_id: Optional[str] = None
+    ) -> Awaitable[Optional[Any]]:
+        """
+        Asynchronously gets an item programmatically from the cache.
+
+        Args:
+            key (Any): The key to look up (must be hashable).
+            scope (_CacheScope): The scope ('global', 'organization', 'user').
+            organization_id (Optional[str]): Required if scope='organization'.
+            user_id (Optional[str]): Required if scope='user'.
+
+        Returns:
+            Awaitable[Optional[Any]]: The cached value or None.
+        """
+        ...
+
+    def aset(
+        self,
+        key: Any,
+        value: Any,
+        ttl_seconds: Union[int, float],
+        scope: _CacheScope = "global",
+        organization_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> Awaitable[None]:
+        """
+        Asynchronously sets an item programmatically in the cache.
+
+        Args:
+            key (Any): The key (must be hashable).
+            value (Any): The value to store.
+            ttl_seconds (Union[int, float]): Time-to-live in seconds.
+            scope (_CacheScope): The scope ('global', 'organization', 'user').
+            organization_id (Optional[str]): Required if scope='organization'.
+            user_id (Optional[str]): Required if scope='user'.
+        """
+        ...
+
+    def aevict(
+        self, key: Any, scope: _CacheScope = "global", organization_id: Optional[str] = None, user_id: Optional[str] = None
+    ) -> Awaitable[None]:
+        """
+        Asynchronously removes a specific item programmatically.
+
+        Args:
+            key (Any): The key to remove (must be hashable).
+            scope (_CacheScope): The scope ('global', 'organization', 'user').
+            organization_id (Optional[str]): Required if scope='organization'.
+            user_id (Optional[str]): Required if scope='user'.
+        """
+        ...
+
+    def aclear(self) -> Awaitable[None]:
+        """Asynchronously clears the entire cache."""
+        ...
+
+    def stats(self) -> Dict[str, Any]:
+        """
+        Returns a dictionary of cache observability statistics.
+
+        Returns:
+            Dict[str, Any]: A dict containing keys like 'hits', 'misses',
+            'evictions', 'current_size', etc.
+        """
+        ...
+
+    def evict_by_scope(self, scope: _CacheScope, organization_id: Optional[str] = None, user_id: Optional[str] = None) -> int:
+        """
+        Granularly evicts all items belonging to a specific tenant.
+
+        Args:
+            scope (_CacheScope): The scope to target ('organization' or 'user').
+            organization_id (Optional[str]): Required if scope='organization'.
+            user_id (Optional[str]): Required if scope='user'.
+
+        Returns:
+            int: The number of items successfully evicted.
+        """
+        ...
+
+    def cache(
+        self, ttl_seconds: Union[int, float], scope: _CacheScope = "global", max_items: Optional[int] = None
+    ) -> Callable[[_FuncT], _FuncT]:
+        """
+        Decorator factory for caching function results.
+
+        Args:
+            ttl_seconds (Union[int, float]): Time-to-live for items.
+            scope (_CacheScope): The cache scope.
+            max_items (Optional[int]): Max items for this function.
+
+        Returns:
+            Callable[[_FuncT], _FuncT]: A decorator function.
+        """
+        ...
+
+    def configure(
+        self, backend: IStorageProvider, policy: IEvictionPolicy, max_size: int = 1000, cleanup_interval: int = 60
+    ) -> None:
+        """
+        Configures and starts the cache. Must be called once.
+
+        Args:
+            backend (IStorageProvider): The storage backend (e.g., InMemoryStorageProvider).
+            policy (IEvictionPolicy): The eviction policy (e.g., LRUEvictionPolicy).
+            max_size (int): Max number of items to store globally.
+            cleanup_interval (int): Interval (in seconds) for background cleanup.
+        """
+        ...

protocols/cache_policy_manager_protocol.py

@@ -0,0 +1,82 @@
+from typing import Optional, Protocol
+
+from cache_types import _CacheKey
+from protocols.eviction_policy import IEvictionPolicy
+
+
+class ICachePolicyManager(Protocol):
+    """
+    Interface (Protocol) for cache policy management implementations.
+
+    Defines the contract for managing cache policies including
+    background cleanup and eviction coordination.
+    """
+
+    @property
+    def policy(self) -> IEvictionPolicy:
+        """Returns the eviction policy instance."""
+        ...
+
+    @property
+    def global_max_size(self) -> Optional[int]:
+        """Returns the global maximum cache size."""
+        ...
+
+    @property
+    def cleanup_interval(self) -> int:
+        """Returns the cleanup interval in seconds."""
+        ...
+
+    def start_background_cleanup(self) -> None:
+        """Starts the background cleanup thread."""
+        ...
+
+    def stop_background_cleanup(self) -> None:
+        """Stops the background cleanup thread gracefully."""
+        ...
+
+    def notify_set(self, key: _CacheKey, namespace: str, max_items: Optional[int]) -> Optional[_CacheKey]:
+        """
+        Notifies that an item was set and returns key to evict if needed.
+
+        Args:
+            key: The key that was set.
+            namespace: The namespace of the key.
+            max_items: The max_items limit for this namespace.
+
+        Returns:
+            Key to evict or None.
+        """
+        ...
+
+    def notify_get(self, key: _CacheKey, namespace: str) -> None:
+        """
+        Notifies that an item was accessed.
+
+        Args:
+            key: The key that was accessed.
+            namespace: The namespace of the key.
+        """
+        ...
+
+    def notify_evict(self, key: _CacheKey, namespace: str) -> None:
+        """
+        Notifies that an item was evicted.
+
+        Args:
+            key: The key that was evicted.
+            namespace: The namespace of the key.
+        """
+        ...
+
+    def notify_clear(self) -> None:
+        """Notifies that the entire cache was cleared."""
+        ...
+
+    def get_namespace_count(self) -> int:
+        """Returns the total number of tracked namespaces."""
+        ...
+
+    def get_global_size(self) -> int:
+        """Returns the global item count."""
+        ...

protocols/eviction_policy.py

@@ -0,0 +1,70 @@
+from typing import Optional, Protocol
+
+from cache_types import _CacheKey
+
+
+class IEvictionPolicy(Protocol):
+    """
+    Interface (Protocol) for all cache eviction policies (e.g., LRU, LFU).
+    Implementations MUST be thread-safe.
+    """
+
+    def notify_set(
+        self, key: _CacheKey, namespace: str, max_items: Optional[int], global_max_size: Optional[int]
+    ) -> Optional[_CacheKey]:
+        """
+        Notifies the policy that an item was set (added/updated).
+        The policy must enforce limits and return a key to evict if necessary.
+
+        Args:
+            key (_CacheKey): The key that was set.
+            namespace (str): The namespace of the key.
+            max_items (Optional[int]): The max_items limit for this namespace.
+            global_max_size (Optional[int]): The global max_size limit.
+
+        Returns:
+            Optional[_CacheKey]: A key to evict, or None.
+        """
+        ...
+
+    def notify_get(self, key: _CacheKey, namespace: str) -> None:
+        """
+        Notifies the policy that an item was accessed (read).
+
+        Args:
+            key (_CacheKey): The key that was accessed.
+            namespace (str): The namespace of the key.
+        """
+        ...
+
+    def notify_evict(self, key: _CacheKey, namespace: str) -> None:
+        """
+        Notifies the policy that an item was evicted (removed).
+
+        Args:
+            key (_CacheKey): The key that was evicted.
+            namespace (str): The namespace of the key.
+        """
+        ...
+
+    def notify_clear(self) -> None:
+        """Notifies the policy that the entire cache was cleared."""
+        ...
+
+    def get_namespace_count(self) -> int:
+        """
+        Returns the total number of tracked namespaces.
+
+        Returns:
+            int: The count of namespaces.
+        """
+        ...
+
+    def get_global_size(self) -> int:
+        """
+        Returns the total number of items tracked by the policy.
+
+        Returns:
+            int: The global item count.
+        """
+        ...

protocols/scope.py

@@ -0,0 +1,85 @@
+from typing import Any, Dict, List, Optional, Protocol
+
+
+class IScope(Protocol):
+    """
+    Interface (Protocol) for scope configuration implementations.
+
+    Defines the contract for managing hierarchical cache scoping,
+    allowing different implementations while maintaining type safety.
+    """
+
+    @property
+    def level_names(self) -> List[str]:
+        """
+        Returns the names of all scope levels.
+
+        Returns:
+            List of scope level names.
+        """
+        ...
+
+    def get_param_name(self, level_name: str) -> str:
+        """
+        Returns the parameter name for a specific scope level.
+
+        Args:
+            level_name: Name of the scope level.
+
+        Returns:
+            Corresponding parameter name.
+
+        Raises:
+            ValueError: If the level doesn't exist.
+        """
+        ...
+
+    def build_scope_path(self, scope_params: Dict[str, Any]) -> str:
+        """
+        Builds the scope path based on provided parameters.
+
+        Args:
+            scope_params: Dictionary with scope parameters.
+
+        Returns:
+            String representing the hierarchical scope path.
+        """
+        ...
+
+    def validate_scope_params(self, target_level: str, scope_params: Dict[str, Any]) -> None:
+        """
+        Validates that required parameters are present for the target level.
+
+        Args:
+            target_level: Desired scope level.
+            scope_params: Provided parameters.
+
+        Raises:
+            ValueError: If mandatory parameters are missing.
+        """
+        ...
+
+    def get_parent_scope_path(self, scope_path: str) -> Optional[str]:
+        """
+        Returns the parent scope path.
+
+        Args:
+            scope_path: Current scope path.
+
+        Returns:
+            Parent scope path or None if global.
+        """
+        ...
+
+    def is_descendant_of(self, child_path: str, parent_path: str) -> bool:
+        """
+        Checks if one scope is a descendant of another.
+
+        Args:
+            child_path: Child scope path.
+            parent_path: Parent scope path.
+
+        Returns:
+            True if child_path is descendant of parent_path.
+        """
+        ...

protocols/storage_provider.py

@@ -0,0 +1,67 @@
+from typing import List, Optional, Protocol
+
+from cache_types import _CacheKey, _CacheValue
+
+
+class IStorageProvider(Protocol):
+    """
+    Interface (Protocol) for all storage backends (e.g., In-Memory, Redis).
+    Implementations MUST be thread-safe for synchronous operations.
+    """
+
+    def get(self, key: _CacheKey) -> Optional[_CacheValue]:
+        """
+        Atomically gets a value tuple (value, expiry) from storage.
+
+        Args:
+            key (_CacheKey): The internal key to get.
+
+        Returns:
+            Optional[_CacheValue]: The stored tuple, or None.
+        """
+        ...
+
+    def get_value_no_lock(self, key: _CacheKey) -> Optional[_CacheValue]:
+        """
+        Performs a non-locking ("dirty") read for the cleanup loop.
+        Only required for backends that support it.
+
+        Args:
+            key (_CacheKey): The internal key to look up.
+
+        Returns:
+            Optional[_CacheValue]: The stored tuple (value, expiry) or None.
+        """
+        ...
+
+    def set(self, key: _CacheKey, value: _CacheValue) -> None:
+        """
+        Atomically sets a value tuple (value, expiry) in storage.
+
+        Args:
+            key (_CacheKey): The internal key to set.
+            value (_CacheValue): The (value, expiry) tuple to store.
+        """
+        ...
+
+    def evict(self, key: _CacheKey) -> None:
+        """
+        Atomically evicts a key from storage.
+
+        Args:
+            key (_CacheKey): The internal key to evict.
+        """
+        ...
+
+    def get_all_keys(self) -> List[_CacheKey]:
+        """
+        Atomically gets a copy of all keys in storage.
+
+        Returns:
+            List[_CacheKey]: A list of all cache keys.
+        """
+        ...
+
+    def clear(self) -> None:
+        """Atomically clears the entire storage."""
+        ...