cacheado 1.0.1__py3-none-any.whl

cache_policies/cache_policy_manager.py

@@ -0,0 +1,187 @@
+import logging
+import threading
+import time
+from typing import TYPE_CHECKING, Optional
+
+from cache_types import _CacheKey
+
+if TYPE_CHECKING:
+    from cache import Cache
+
+from protocols.cache_policy_manager_protocol import ICachePolicyManager
+from protocols.eviction_policy import IEvictionPolicy
+
+
+class CachePolicyManager(ICachePolicyManager):
+    """
+    Manages cache maintenance policies (e.g., eviction, cleanup).
+
+    This class handles background cleanup and delegates eviction logic
+    to an injected IEvictionPolicy. Optimized with __slots__ for memory efficiency.
+    """
+
+    __slots__ = ("_cache", "_cleanup_interval", "_policy", "_global_max_size", "_stop_event", "_cleanup_thread")
+
+    def __init__(
+        self, cache_instance: "Cache", cleanup_interval: int, policy: IEvictionPolicy, max_size: Optional[int] = None
+    ):
+        """
+        Initializes the policy manager.
+
+        Args:
+            cache_instance (Cache): The main Cache instance.
+            cleanup_interval (int): The interval (in seconds) for the cleanup loop.
+            policy (IEvictionPolicy): The injected eviction policy (e.g., LRUPolicy).
+            max_size (Optional[int]): The maximum number of items allowed globally.
+        """
+        self._cache = cache_instance
+        self._cleanup_interval = cleanup_interval
+        self._policy = policy
+        self._global_max_size = max_size
+        self._stop_event = threading.Event()
+        self._cleanup_thread: Optional[threading.Thread] = None
+        logging.info(
+            f"CachePolicyManager initialized with policy={policy.__class__.__name__}, "
+            f"max_size={max_size}, cleanup_interval={cleanup_interval}s"
+        )
+
+    def start_background_cleanup(self) -> None:
+        """
+        Starts the background daemon thread for cache cleanup.
+        """
+        try:
+            if self._cleanup_thread is None or not self._cleanup_thread.is_alive():
+                self._stop_event.clear()
+                self._cleanup_thread = threading.Thread(target=self._cleanup_loop, daemon=True, name="CacheCleanupThread")
+                self._cleanup_thread.start()
+                logging.info("Cache cleanup thread started.")
+        except Exception as e:
+            logging.error(f"Failed to start cache cleanup thread: {e}")
+            raise
+
+    def stop_background_cleanup(self) -> None:
+        """Stops the background cleanup thread gracefully."""
+        try:
+            if self._cleanup_thread and self._cleanup_thread.is_alive():
+                self._stop_event.set()
+                self._cleanup_thread.join()
+                logging.info("Cache cleanup thread stopped.")
+        except Exception as e:
+            logging.error(f"Error stopping cache cleanup thread: {e}")
+
+    def _cleanup_loop(self) -> None:
+        """
+        The main loop for the garbage collector thread.
+
+        Periodically scans keys and triggers passive eviction for expired items.
+        """
+        while not self._stop_event.wait(self._cleanup_interval):
+            try:
+                if self._cache is None:
+                    continue
+
+                all_keys = self._cache._get_all_keys_from_storage()
+                if not all_keys:
+                    continue
+
+                logging.info(f"Background cleanup: checking {len(all_keys)} keys.")
+
+                current_time = time.monotonic()
+                expired_count = 0
+
+                for key in all_keys:
+                    value_tuple = self._cache._get_value_no_lock_from_storage(key)
+                    if value_tuple and current_time > value_tuple[1]:
+                        namespace = key[1]
+                        self._cache._internal_get(key, namespace)
+                        expired_count += 1
+
+                if expired_count > 0:
+                    logging.info(f"Background cleanup: {expired_count} expired keys removed.")
+
+            except Exception as e:
+                logging.error(f"Error in cache cleanup thread: {e}", exc_info=True)
+
+    def notify_set(self, key: _CacheKey, namespace: str, max_items: Optional[int]) -> Optional[_CacheKey]:
+        """
+        Delegates 'set' notification to the eviction policy.
+
+        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.
+
+        Returns:
+            Optional[_CacheKey]: A key to evict, or None.
+        """
+        try:
+            return self._policy.notify_set(key, namespace, max_items, self._global_max_size)
+        except Exception as e:
+            logging.error(f"Error in policy notify_set: {e}")
+            return None
+
+    def notify_get(self, key: _CacheKey, namespace: str) -> None:
+        """
+        Delegates 'get' notification to the eviction policy.
+
+        Args:
+            key (_CacheKey): The key that was accessed.
+            namespace (str): The namespace of the key.
+        """
+        try:
+            self._policy.notify_get(key, namespace)
+        except Exception as e:
+            logging.error(f"Error in policy notify_get: {e}")
+
+    def notify_evict(self, key: _CacheKey, namespace: str) -> None:
+        """
+        Delegates 'evict' notification to the eviction policy.
+
+        Args:
+            key (_CacheKey): The key that was evicted.
+            namespace (str): The namespace of the key.
+        """
+        try:
+            self._policy.notify_evict(key, namespace)
+        except Exception as e:
+            logging.error(f"Error in policy notify_evict: {e}")
+
+    def notify_clear(self) -> None:
+        """Delegates 'clear' notification to the eviction policy."""
+        try:
+            self._policy.notify_clear()
+        except Exception as e:
+            logging.error(f"Error in policy notify_clear: {e}")
+
+    def get_namespace_count(self) -> int:
+        """
+        Gets the total number of tracked namespaces from the policy.
+
+        Returns:
+            int: The count of namespaces.
+        """
+        return self._policy.get_namespace_count()
+
+    def get_global_size(self) -> int:
+        """
+        Gets the global item count from the policy.
+
+        Returns:
+            int: The global item count.
+        """
+        return self._policy.get_global_size()
+
+    @property
+    def policy(self) -> IEvictionPolicy:
+        """Returns the eviction policy instance."""
+        return self._policy
+
+    @property
+    def global_max_size(self) -> Optional[int]:
+        """Returns the global maximum cache size."""
+        return self._global_max_size
+
+    @property
+    def cleanup_interval(self) -> int:
+        """Returns the cleanup interval in seconds."""
+        return self._cleanup_interval

cache_scopes/scope_config.py

@@ -0,0 +1,228 @@
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from protocols.scope import IScope
+
+
+@dataclass
+class ScopeLevel:
+    """Represents a level in the scope hierarchy."""
+
+    name: str
+    param_name: str
+    children: Optional[List["ScopeLevel"]] = None
+
+    def __post_init__(self):
+        if not self.name:
+            raise ValueError("name cannot be empty")
+        if self.children is None:
+            self.children = []
+
+
+class ScopeConfig(IScope):
+    """
+    Hierarchical scope configuration for cache with multiple tree support.
+
+    Example:
+        ``` python
+            # Multiple independent trees
+            org_tree = ScopeLevel("organization", "org_id", [
+                ScopeLevel("user", "user_id")
+            ])
+            car_tree = ScopeLevel("car", "car_id", [
+                ScopeLevel("door", "door_id", [
+                    ScopeLevel("tire", "tire_id")
+                ])
+            ])
+            config = ScopeConfig([org_tree, car_tree])
+        ```
+    """
+
+    __slots__ = ("_root_levels", "_all_levels", "_level_names", "_param_mapping")
+
+    def __init__(self, root_levels: Optional[List[ScopeLevel]] = None):
+        """
+        Initializes scope configuration with global as implicit root.
+
+        Args:
+            root_levels: List of global child levels (optional).
+        """
+        global_level = ScopeLevel("global", "", root_levels or [])
+
+        self._root_levels = [global_level]
+        self._all_levels = self._flatten_levels(self._root_levels)
+        self._level_names = [level.name for level in self._all_levels]
+        self._param_mapping = {level.name: level.param_name for level in self._all_levels}
+
+        if len(set(self._level_names)) != len(self._level_names):
+            raise ValueError("Scope level names must be unique")
+
+    def _flatten_levels(self, levels: List[ScopeLevel]) -> List[ScopeLevel]:
+        """Flattens the level tree into a list."""
+        result = []
+        for level in levels:
+            result.append(level)
+            if level.children:
+                result.extend(self._flatten_levels(level.children))
+        return result
+
+    @property
+    def root_levels(self) -> List[ScopeLevel]:
+        """Returns the configured root scope levels."""
+        return self._root_levels.copy()
+
+    @property
+    def all_levels(self) -> List[ScopeLevel]:
+        """Returns all scope levels (flattened)."""
+        return self._all_levels.copy()
+
+    @property
+    def level_names(self) -> List[str]:
+        """Returns the scope level names."""
+        return self._level_names.copy()
+
+    def get_param_name(self, level_name: str) -> str:
+        """
+        Returns the parameter name for a specific level.
+
+        Args:
+            level_name: Name of the scope level.
+
+        Returns:
+            Corresponding parameter name.
+
+        Raises:
+            ValueError: If the level doesn't exist.
+        """
+        if level_name not in self._param_mapping:
+            raise ValueError(f"Unknown scope level: {level_name}")
+        return self._param_mapping[level_name]
+
+    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 build_path_recursive(levels: List[ScopeLevel], path_parts: List[str]) -> List[str]:
+            for level in levels:
+                if level.name == "global":
+                    if level.children:
+                        return build_path_recursive(level.children, path_parts)
+                    return path_parts
+
+                param_value = scope_params.get(level.param_name)
+                if param_value is not None:
+                    new_path = path_parts + [f"{level.name}:{param_value}"]
+                    if level.children:
+                        child_path = build_path_recursive(level.children, new_path)
+                        if len(child_path) > len(new_path):
+                            return child_path
+                    return new_path
+            return path_parts
+
+        path_parts = build_path_recursive(self._root_levels, [])
+        return "/".join(path_parts) if path_parts else "global"
+
+    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.
+        """
+        if target_level == "global":
+            return
+
+        if target_level not in self._level_names:
+            raise ValueError(f"Unknown scope level: {target_level}")
+
+        path_to_target = self._find_path_to_level(target_level)
+        if not path_to_target:
+            raise ValueError(f"Cannot find path to scope level: {target_level}")
+
+        for level in path_to_target:
+            if level.param_name and (level.param_name not in scope_params or scope_params[level.param_name] is None):
+                raise ValueError(f"Missing required parameter '{level.param_name}' for scope level '{level.name}'")
+
+    def _find_path_to_level(self, target_level: str) -> Optional[List[ScopeLevel]]:
+        """Finds the hierarchical path to a specific level."""
+
+        def search_recursive(levels: List[ScopeLevel], path: List[ScopeLevel]) -> Optional[List[ScopeLevel]]:
+            for level in levels:
+                current_path = path + [level]
+                if level.name == target_level:
+                    return current_path
+                if level.children:
+                    result = search_recursive(level.children, current_path)
+                    if result:
+                        return result
+            return None
+
+        return search_recursive(self._root_levels, [])
+
+    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.
+        """
+        if scope_path == "global":
+            return None
+
+        parts = scope_path.split("/")
+        if len(parts) <= 1:
+            return "global"
+
+        return "/".join(parts[:-1])
+
+    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.
+        """
+        if parent_path == "global":
+            return True
+
+        if child_path == "global":
+            return False
+
+        return child_path.startswith(parent_path + "/") or child_path == parent_path
+
+    def get_scope_tree_for_level(self, level_name: str) -> Optional[ScopeLevel]:
+        """Returns the root tree that contains the specified level."""
+
+        def find_root(levels: List[ScopeLevel], target: str) -> Optional[ScopeLevel]:
+            for root in levels:
+                if self._level_exists_in_tree(root, target):
+                    return root
+            return None
+
+        return find_root(self._root_levels, level_name)
+
+    def _level_exists_in_tree(self, root: ScopeLevel, target: str) -> bool:
+        """Checks if a level exists in the tree."""
+        if root.name == target:
+            return True
+        if root.children:
+            return any(self._level_exists_in_tree(child, target) for child in root.children)
+        return False

cache_types.py

@@ -0,0 +1,6 @@
+from typing import Any, Callable, Tuple, TypeVar, Union
+
+_CacheKey = Tuple[str, str, Tuple[Any, ...]]
+_CacheValue = Tuple[Any, float]
+_FuncT = TypeVar("_FuncT", bound=Callable[..., Any])
+_CacheScope = Union[str, Tuple[str, ...]]