py-wlcli 0.8.0__py3-none-any.whl

wl_cli/utils/cache.py

@@ -0,0 +1,491 @@
+"""Generic in-memory/on-disk cache framework -- **debug-only** (#213, ADR-0011).
+
+This module has exactly one production consumer,
+:mod:`wl_cli.commands.debug.debug_cache`, in the subsystem scheduled for
+retirement. The three live caches -- test results, coverage, format results --
+go through :mod:`wl_cli.utils.cache_ledger`; this framework is *not* their seam
+and must not grow into a second one.
+
+It is isolated rather than migrated: a subsystem already judged dead does not
+get ported. ``tests/test_utils_cache_is_debug_only.py`` fails if anything
+outside ``commands/debug/`` imports it, and the module goes away with
+``wl debug``.
+"""
+
+import hashlib
+import pickle
+import threading
+import time
+from collections.abc import Callable
+from typing import Any
+
+
+class CacheKeyGenerator:
+    """Cache key generator for creating unique cache keys."""
+
+    @staticmethod
+    def generate_key(*args, **kwargs) -> str:
+        """
+        Generate a unique cache key based on arguments.
+
+        Args:
+            *args: Positional arguments
+            **kwargs: Keyword arguments
+
+        Returns:
+            A unique cache key as a string
+        """
+        # Create a hashable representation of the arguments
+        key_components = []
+
+        # Process positional arguments
+        for arg in args:
+            if isinstance(arg, str | int | float | bool | type(None)):
+                key_components.append(str(arg))
+            elif isinstance(arg, list | tuple):
+                key_components.append(
+                    str([CacheKeyGenerator._hash_object(item) for item in arg])
+                )
+            elif isinstance(arg, dict):
+                sorted_items = sorted(arg.items())
+                key_components.append(
+                    str(
+                        [
+                            (k, CacheKeyGenerator._hash_object(v))
+                            for k, v in sorted_items
+                        ]
+                    )
+                )
+            else:
+                key_components.append(CacheKeyGenerator._hash_object(arg))
+
+        # Process keyword arguments
+        sorted_kwargs = sorted(kwargs.items())
+        for key, value in sorted_kwargs:
+            key_components.append(f"{key}:{CacheKeyGenerator._hash_object(value)}")
+
+        # Combine and hash
+        combined = "|".join(key_components)
+        return hashlib.md5(combined.encode()).hexdigest()
+
+    @staticmethod
+    def _hash_object(obj: Any) -> str:
+        """
+        Hash an object to a string representation.
+
+        Args:
+            obj: The object to hash
+
+        Returns:
+            A hash string representation of the object
+        """
+        if hasattr(obj, "__dict__"):
+            # For objects with __dict__
+            sorted_attrs = sorted(obj.__dict__.items())
+            return hashlib.md5(str(sorted_attrs).encode()).hexdigest()
+        elif callable(obj):
+            # For callables
+            try:
+                return hashlib.md5(
+                    (obj.__name__ + (obj.__module__ or "")).encode()
+                ).hexdigest()
+            except AttributeError:
+                return hashlib.md5(str(obj).encode()).hexdigest()
+        else:
+            # For other types
+            return hashlib.md5(str(obj).encode()).hexdigest()
+
+
+class CacheItem:
+    """Cache item with metadata."""
+
+    def __init__(self, value: Any, expiry: float | None = None):
+        """
+        Initialize a cache item.
+
+        Args:
+            value: The value to cache
+            expiry: Optional expiry time in seconds since epoch
+        """
+        self.value = value
+        self.created_at = time.time()
+        self.expiry = expiry
+
+    def is_expired(self) -> bool:
+        """
+        Check if the cache item is expired.
+
+        Returns:
+            True if expired, False otherwise
+        """
+        if self.expiry is None:
+            return False
+        return time.time() > self.expiry
+
+
+class BaseCache:
+    """Base cache implementation."""
+
+    def get(self, key: str) -> Any | None:
+        """
+        Get a value from the cache.
+
+        Args:
+            key: The cache key
+
+        Returns:
+            The cached value or None if not found or expired
+        """
+        raise NotImplementedError
+
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """
+        Set a value in the cache.
+
+        Args:
+            key: The cache key
+            value: The value to cache
+            ttl: Optional time-to-live in seconds
+        """
+        raise NotImplementedError
+
+    def delete(self, key: str) -> None:
+        """
+        Delete a value from the cache.
+
+        Args:
+            key: The cache key
+        """
+        raise NotImplementedError
+
+    def clear(self) -> None:
+        """
+        Clear the entire cache.
+        """
+        raise NotImplementedError
+
+    def has(self, key: str) -> bool:
+        """
+        Check if a key exists in the cache and is not expired.
+
+        Args:
+            key: The cache key
+
+        Returns:
+            True if the key exists and is not expired, False otherwise
+        """
+        raise NotImplementedError
+
+
+class MemoryCache(BaseCache):
+    """In-memory cache implementation."""
+
+    def __init__(self):
+        """Initialize the memory cache."""
+        self._cache: dict[str, CacheItem] = {}
+        self._lock = threading.RLock()
+
+    def get(self, key: str) -> Any | None:
+        """
+        Get a value from the cache.
+
+        Args:
+            key: The cache key
+
+        Returns:
+            The cached value or None if not found or expired
+        """
+        with self._lock:
+            if key not in self._cache:
+                return None
+
+            item = self._cache[key]
+            if item.is_expired():
+                del self._cache[key]
+                return None
+
+            return item.value
+
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """
+        Set a value in the cache.
+
+        Args:
+            key: The cache key
+            value: The value to cache
+            ttl: Optional time-to-live in seconds
+        """
+        with self._lock:
+            expiry = time.time() + ttl if ttl is not None else None
+            self._cache[key] = CacheItem(value, expiry)
+
+    def delete(self, key: str) -> None:
+        """
+        Delete a value from the cache.
+
+        Args:
+            key: The cache key
+        """
+        with self._lock:
+            if key in self._cache:
+                del self._cache[key]
+
+    def clear(self) -> None:
+        """
+        Clear the entire cache.
+        """
+        with self._lock:
+            self._cache.clear()
+
+    def has(self, key: str) -> bool:
+        """
+        Check if a key exists in the cache and is not expired.
+
+        Args:
+            key: The cache key
+
+        Returns:
+            True if the key exists and is not expired, False otherwise
+        """
+        with self._lock:
+            if key not in self._cache:
+                return False
+
+            item = self._cache[key]
+            if item.is_expired():
+                del self._cache[key]
+                return False
+
+            return True
+
+    def get_size(self) -> int:
+        """
+        Get the size of the cache.
+
+        Returns:
+            The number of items in the cache
+        """
+        with self._lock:
+            # Clean up expired items first
+            expired_keys = [
+                key for key, item in self._cache.items() if item.is_expired()
+            ]
+            for key in expired_keys:
+                del self._cache[key]
+
+            return len(self._cache)
+
+
+class DiskCache(BaseCache):
+    """Disk-based cache implementation."""
+
+    def __init__(self, cache_dir: str = ".wl_cache"):
+        """
+        Initialize the disk cache.
+
+        Args:
+            cache_dir: The directory to store cache files
+        """
+        import os
+
+        self.cache_dir = cache_dir
+        self._lock = threading.RLock()
+
+        # Create cache directory if it doesn't exist
+        os.makedirs(self.cache_dir, exist_ok=True)
+
+    def get(self, key: str) -> Any | None:
+        """
+        Get a value from the disk cache.
+
+        Args:
+            key: The cache key
+
+        Returns:
+            The cached value or None if not found or expired
+        """
+        import os
+
+        # Sanitize key to handle platform-specific path separators
+        sanitized_key = key.replace(os.sep, "_")
+        cache_file = os.path.join(self.cache_dir, sanitized_key)
+
+        with self._lock:
+            if not os.path.exists(cache_file):
+                return None
+
+            try:
+                with open(cache_file, "rb") as f:
+                    item = pickle.load(f)
+
+                if item.is_expired():
+                    os.remove(cache_file)
+                    return None
+
+                return item.value
+            except (OSError, pickle.UnpicklingError):
+                # If there's an error reading the cache, remove the file
+                if os.path.exists(cache_file):
+                    os.remove(cache_file)
+                return None
+
+    def set(self, key: str, value: Any, ttl: int | None = None) -> None:
+        """
+        Set a value in the disk cache.
+
+        Args:
+            key: The cache key
+            value: The value to cache
+            ttl: Optional time-to-live in seconds
+        """
+        import os
+
+        # Sanitize key to handle platform-specific path separators
+        sanitized_key = key.replace(os.sep, "_")
+        cache_file = os.path.join(self.cache_dir, sanitized_key)
+
+        with self._lock:
+            try:
+                expiry = time.time() + ttl if ttl is not None else None
+                item = CacheItem(value, expiry)
+
+                # Write to a temporary file first
+                import tempfile
+
+                with tempfile.NamedTemporaryFile(
+                    dir=self.cache_dir, delete=False
+                ) as temp_f:
+                    pickle.dump(item, temp_f)
+                    temp_file_name = temp_f.name
+
+                # Atomically rename the temporary file to the final cache file
+                import os
+
+                os.replace(temp_file_name, cache_file)
+            except (OSError, pickle.PickleError, TypeError):
+                # Ignore IO, pickle, and type errors when writing to cache
+                # Clean up any temporary file that might have been created
+                if "temp_file_name" in locals() and os.path.exists(temp_file_name):
+                    try:
+                        os.remove(temp_file_name)
+                    except OSError:
+                        pass
+                pass
+
+    def delete(self, key: str) -> None:
+        """
+        Delete a value from the disk cache.
+
+        Args:
+            key: The cache key
+        """
+        import os
+
+        # Sanitize key to handle platform-specific path separators
+        sanitized_key = key.replace(os.sep, "_")
+        cache_file = os.path.join(self.cache_dir, sanitized_key)
+
+        with self._lock:
+            if os.path.exists(cache_file):
+                try:
+                    os.remove(cache_file)
+                except OSError:
+                    pass
+
+    def clear(self) -> None:
+        """
+        Clear the entire disk cache.
+        """
+        import os
+        import shutil
+
+        with self._lock:
+            if os.path.exists(self.cache_dir):
+                try:
+                    shutil.rmtree(self.cache_dir)
+                    os.makedirs(self.cache_dir, exist_ok=True)
+                except OSError:
+                    pass
+
+    def has(self, key: str) -> bool:
+        """
+        Check if a key exists in the disk cache and is not expired.
+
+        Args:
+            key: The cache key
+
+        Returns:
+            True if the key exists and is not expired, False otherwise
+        """
+        return self.get(key) is not None
+
+
+# Global cache instances
+_memory_cache = MemoryCache()
+
+
+def get_cache() -> MemoryCache:
+    """
+    Get the global memory cache instance.
+
+    Returns:
+        The global memory cache instance
+    """
+    return _memory_cache
+
+
+def cached(ttl: int | None = 3600):
+    """
+    Decorator to cache function results.
+
+    Args:
+        ttl: Time-to-live in seconds
+
+    Returns:
+        A decorator that caches function results
+    """
+
+    def decorator(func: Callable) -> Callable:
+        # Precompute function identifier to avoid repeated attribute access
+        func_id = f"{func.__module__ or ''}:{func.__name__}"
+        cache = get_cache()
+
+        def wrapper(*args, **kwargs):
+            # Generate cache key
+            cache_key = f"{func_id}:{CacheKeyGenerator.generate_key(*args, **kwargs)}"
+
+            # Try to get from cache
+            cached_value = cache.get(cache_key)
+            if cached_value is not None:
+                return cached_value
+
+            # Call the function
+            result = func(*args, **kwargs)
+
+            # Cache the result
+            cache.set(cache_key, result, ttl)
+
+            return result
+
+        # Preserve function metadata
+        wrapper.__name__ = func.__name__
+        wrapper.__doc__ = func.__doc__
+        wrapper.__module__ = func.__module__
+
+        return wrapper
+
+    return decorator
+
+
+# File system cache
+_file_system_cache = MemoryCache()
+
+
+def get_file_system_cache() -> MemoryCache:
+    """
+    Get the global file system cache instance.
+
+    Returns:
+        The global file system cache instance
+    """
+    return _file_system_cache