cachu 0.1.1__py3-none-any.whl

cachu/__init__.py

@@ -0,0 +1,27 @@
+"""Flexible caching library with support for memory, file, and Redis backends.
+"""
+__version__ = '0.1.1'
+
+from .backends.redis import get_redis_client
+from .config import configure, disable, enable, get_all_configs, get_config
+from .config import is_disabled
+from .decorator import cache, get_backend
+from .operations import cache_clear, cache_delete, cache_get, cache_info
+from .operations import cache_set
+
+__all__ = [
+    'configure',
+    'get_config',
+    'get_all_configs',
+    'disable',
+    'enable',
+    'is_disabled',
+    'cache',
+    'cache_get',
+    'cache_set',
+    'cache_delete',
+    'cache_clear',
+    'cache_info',
+    'get_backend',
+    'get_redis_client',
+]

cachu/backends/__init__.py

@@ -0,0 +1,47 @@
+"""Cache backend implementations.
+"""
+from abc import ABC, abstractmethod
+from typing import Any
+from collections.abc import Iterator
+
+NO_VALUE = object()
+
+
+class Backend(ABC):
+    """Abstract base class for cache backends.
+    """
+
+    @abstractmethod
+    def get(self, key: str) -> Any:
+        """Get value by key. Returns NO_VALUE if not found.
+        """
+
+    @abstractmethod
+    def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+
+    @abstractmethod
+    def set(self, key: str, value: Any, ttl: int) -> None:
+        """Set value with TTL in seconds.
+        """
+
+    @abstractmethod
+    def delete(self, key: str) -> None:
+        """Delete value by key.
+        """
+
+    @abstractmethod
+    def clear(self, pattern: str | None = None) -> int:
+        """Clear entries matching pattern. Returns count of cleared entries.
+        """
+
+    @abstractmethod
+    def keys(self, pattern: str | None = None) -> Iterator[str]:
+        """Iterate over keys matching pattern.
+        """
+
+    @abstractmethod
+    def count(self, pattern: str | None = None) -> int:
+        """Count keys matching pattern.
+        """

cachu/backends/file.py

@@ -0,0 +1,158 @@
+"""File-based cache backend using DBM.
+"""
+import dbm
+import fnmatch
+import pathlib
+import pickle
+import struct
+import threading
+import time
+from collections.abc import Iterator
+from typing import Any
+
+from . import NO_VALUE, Backend
+
+_METADATA_FORMAT = 'dd'
+_METADATA_SIZE = struct.calcsize(_METADATA_FORMAT)
+
+
+class FileBackend(Backend):
+    """DBM file-based cache backend.
+    """
+
+    def __init__(self, filepath: str) -> None:
+        self._filepath = filepath
+        self._lock = threading.RLock()
+        self._ensure_dir()
+
+    def _ensure_dir(self) -> None:
+        """Ensure the directory for the cache file exists.
+        """
+        directory = pathlib.Path(self._filepath).parent
+        if directory and not pathlib.Path(directory).exists():
+            pathlib.Path(directory).mkdir(exist_ok=True, parents=True)
+
+    def _pack_value(self, value: Any, created_at: float, expires_at: float) -> bytes:
+        """Pack value with metadata.
+        """
+        metadata = struct.pack(_METADATA_FORMAT, created_at, expires_at)
+        pickled = pickle.dumps(value)
+        return metadata + pickled
+
+    def _unpack_value(self, data: bytes) -> tuple[Any, float, float]:
+        """Unpack value and metadata.
+        """
+        created_at, expires_at = struct.unpack(_METADATA_FORMAT, data[:_METADATA_SIZE])
+        value = pickle.loads(data[_METADATA_SIZE:])
+        return value, created_at, expires_at
+
+    def get(self, key: str) -> Any:
+        """Get value by key. Returns NO_VALUE if not found or expired.
+        """
+        with self._lock:
+            try:
+                with dbm.open(self._filepath, 'c') as db:
+                    data = db.get(key.encode())
+                    if data is None:
+                        return NO_VALUE
+
+                    value, created_at, expires_at = self._unpack_value(data)
+                    if time.time() > expires_at:
+                        del db[key.encode()]
+                        return NO_VALUE
+
+                    return value
+            except Exception:
+                return NO_VALUE
+
+    def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+        with self._lock:
+            try:
+                with dbm.open(self._filepath, 'c') as db:
+                    data = db.get(key.encode())
+                    if data is None:
+                        return NO_VALUE, None
+
+                    value, created_at, expires_at = self._unpack_value(data)
+                    if time.time() > expires_at:
+                        del db[key.encode()]
+                        return NO_VALUE, None
+
+                    return value, created_at
+            except Exception:
+                return NO_VALUE, None
+
+    def set(self, key: str, value: Any, ttl: int) -> None:
+        """Set value with TTL in seconds.
+        """
+        now = time.time()
+        packed = self._pack_value(value, now, now + ttl)
+        with self._lock, dbm.open(self._filepath, 'c') as db:
+            db[key.encode()] = packed
+
+    def delete(self, key: str) -> None:
+        """Delete value by key.
+        """
+        with self._lock:
+            try:
+                with dbm.open(self._filepath, 'c') as db:
+                    if key.encode() in db:
+                        del db[key.encode()]
+            except Exception:
+                pass
+
+    def clear(self, pattern: str | None = None) -> int:
+        """Clear entries matching pattern. Returns count of cleared entries.
+        """
+        with self._lock:
+            try:
+                if pattern is None:
+                    with dbm.open(self._filepath, 'n'):
+                        pass
+                    return -1
+
+                with dbm.open(self._filepath, 'c') as db:
+                    keys_to_delete = [
+                        k for k in db
+                        if fnmatch.fnmatch(k.decode(), pattern)
+                    ]
+                    for key in keys_to_delete:
+                        del db[key]
+                    return len(keys_to_delete)
+            except Exception:
+                return 0
+
+    def keys(self, pattern: str | None = None) -> Iterator[str]:
+        """Iterate over keys matching pattern.
+        """
+        now = time.time()
+        with self._lock:
+            try:
+                with dbm.open(self._filepath, 'c') as db:
+                    all_keys = [k.decode() for k in db]
+            except Exception:
+                return
+
+        for key in all_keys:
+            with self._lock:
+                try:
+                    with dbm.open(self._filepath, 'c') as db:
+                        data = db.get(key.encode())
+                        if data is None:
+                            continue
+                        _, _, expires_at = self._unpack_value(data)
+                        if now > expires_at:
+                            del db[key.encode()]
+                            continue
+                except Exception:
+                    continue
+
+            if pattern is None or fnmatch.fnmatch(key, pattern):
+                yield key
+
+    def count(self, pattern: str | None = None) -> int:
+        """Count keys matching pattern.
+        """
+        return sum(1 for _ in self.keys(pattern))

cachu/backends/memory.py

@@ -0,0 +1,102 @@
+"""Memory cache backend implementation.
+"""
+import fnmatch
+import pickle
+import threading
+import time
+from collections.abc import Iterator
+from typing import Any
+
+from . import NO_VALUE, Backend
+
+
+class MemoryBackend(Backend):
+    """Thread-safe in-memory cache backend.
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[str, tuple[bytes, float, float]] = {}
+        self._lock = threading.RLock()
+
+    def get(self, key: str) -> Any:
+        """Get value by key. Returns NO_VALUE if not found or expired.
+        """
+        with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return NO_VALUE
+
+            pickled_value, created_at, expires_at = entry
+            if time.time() > expires_at:
+                del self._cache[key]
+                return NO_VALUE
+
+            return pickle.loads(pickled_value)
+
+    def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+        with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return NO_VALUE, None
+
+            pickled_value, created_at, expires_at = entry
+            if time.time() > expires_at:
+                del self._cache[key]
+                return NO_VALUE, None
+
+            return pickle.loads(pickled_value), created_at
+
+    def set(self, key: str, value: Any, ttl: int) -> None:
+        """Set value with TTL in seconds.
+        """
+        now = time.time()
+        pickled_value = pickle.dumps(value)
+        with self._lock:
+            self._cache[key] = (pickled_value, now, now + ttl)
+
+    def delete(self, key: str) -> None:
+        """Delete value by key.
+        """
+        with self._lock:
+            self._cache.pop(key, None)
+
+    def clear(self, pattern: str | None = None) -> int:
+        """Clear entries matching pattern. Returns count of cleared entries.
+        """
+        with self._lock:
+            if pattern is None:
+                count = len(self._cache)
+                self._cache.clear()
+                return count
+
+            keys_to_delete = [k for k in self._cache if fnmatch.fnmatch(k, pattern)]
+            for key in keys_to_delete:
+                del self._cache[key]
+            return len(keys_to_delete)
+
+    def keys(self, pattern: str | None = None) -> Iterator[str]:
+        """Iterate over keys matching pattern.
+        """
+        now = time.time()
+        with self._lock:
+            all_keys = list(self._cache.keys())
+
+        for key in all_keys:
+            with self._lock:
+                entry = self._cache.get(key)
+                if entry is None:
+                    continue
+                _, _, expires_at = entry
+                if now > expires_at:
+                    del self._cache[key]
+                    continue
+
+            if pattern is None or fnmatch.fnmatch(key, pattern):
+                yield key
+
+    def count(self, pattern: str | None = None) -> int:
+        """Count keys matching pattern.
+        """
+        return sum(1 for _ in self.keys(pattern))

cachu/backends/redis.py

@@ -0,0 +1,131 @@
+"""Redis cache backend implementation.
+"""
+import pickle
+import struct
+import time
+from collections.abc import Iterator
+from typing import TYPE_CHECKING, Any
+
+from . import NO_VALUE, Backend
+
+if TYPE_CHECKING:
+    import redis
+
+
+_METADATA_FORMAT = 'd'
+_METADATA_SIZE = struct.calcsize(_METADATA_FORMAT)
+
+
+def _get_redis_module() -> Any:
+    """Import redis module, raising helpful error if not installed.
+    """
+    try:
+        import redis
+        return redis
+    except ImportError as e:
+        raise RuntimeError(
+            "Redis support requires the 'redis' package. Install with: pip install cache[redis]"
+        ) from e
+
+
+def get_redis_client(url: str) -> 'redis.Redis':
+    """Create a Redis client from URL.
+
+    Args:
+        url: Redis URL (e.g., 'redis://localhost:6379/0')
+    """
+    redis_module = _get_redis_module()
+    return redis_module.from_url(url)
+
+
+class RedisBackend(Backend):
+    """Redis cache backend.
+    """
+
+    def __init__(self, url: str, distributed_lock: bool = False) -> None:
+        self._url = url
+        self._distributed_lock = distributed_lock
+        self._client: redis.Redis | None = None
+
+    @property
+    def client(self) -> 'redis.Redis':
+        """Lazy-load Redis client.
+        """
+        if self._client is None:
+            self._client = get_redis_client(self._url)
+        return self._client
+
+    def _pack_value(self, value: Any, created_at: float) -> bytes:
+        """Pack value with creation timestamp.
+        """
+        metadata = struct.pack(_METADATA_FORMAT, created_at)
+        pickled = pickle.dumps(value)
+        return metadata + pickled
+
+    def _unpack_value(self, data: bytes) -> tuple[Any, float]:
+        """Unpack value and creation timestamp.
+        """
+        created_at = struct.unpack(_METADATA_FORMAT, data[:_METADATA_SIZE])[0]
+        value = pickle.loads(data[_METADATA_SIZE:])
+        return value, created_at
+
+    def get(self, key: str) -> Any:
+        """Get value by key. Returns NO_VALUE if not found.
+        """
+        data = self.client.get(key)
+        if data is None:
+            return NO_VALUE
+        value, _ = self._unpack_value(data)
+        return value
+
+    def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+        data = self.client.get(key)
+        if data is None:
+            return NO_VALUE, None
+        value, created_at = self._unpack_value(data)
+        return value, created_at
+
+    def set(self, key: str, value: Any, ttl: int) -> None:
+        """Set value with TTL in seconds.
+        """
+        now = time.time()
+        packed = self._pack_value(value, now)
+        self.client.setex(key, ttl, packed)
+
+    def delete(self, key: str) -> None:
+        """Delete value by key.
+        """
+        self.client.delete(key)
+
+    def clear(self, pattern: str | None = None) -> int:
+        """Clear entries matching pattern. Returns count of cleared entries.
+        """
+        if pattern is None:
+            pattern = '*'
+
+        count = 0
+        for key in self.client.scan_iter(match=pattern):
+            self.client.delete(key)
+            count += 1
+        return count
+
+    def keys(self, pattern: str | None = None) -> Iterator[str]:
+        """Iterate over keys matching pattern.
+        """
+        redis_pattern = pattern or '*'
+        for key in self.client.scan_iter(match=redis_pattern):
+            yield key.decode() if isinstance(key, bytes) else key
+
+    def count(self, pattern: str | None = None) -> int:
+        """Count keys matching pattern.
+        """
+        return sum(1 for _ in self.keys(pattern))
+
+    def close(self) -> None:
+        """Close the Redis connection.
+        """
+        if self._client is not None:
+            self._client.close()
+            self._client = None