cachu 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

cachu/__init__.py

@@ -1,19 +1,16 @@
 """Flexible caching library with support for memory, file, and Redis backends.
 """
-__version__ = '0.2.3'
+__version__ = '0.2.5'
 
-from .async_decorator import async_cache, clear_async_backends
-from .async_decorator import get_async_backend, get_async_cache_info
-from .async_operations import async_cache_clear, async_cache_delete
-from .async_operations import async_cache_get, async_cache_info
-from .async_operations import async_cache_set
-from .backends import AsyncBackend, Backend
+from .backends import Backend
 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
+from .decorator import aget_backend, cache, clear_async_backends
+from .decorator import get_async_backend, get_async_cache_info, get_backend
+from .operations import async_cache_clear, async_cache_delete, async_cache_get
+from .operations import async_cache_info, async_cache_set, cache_clear
+from .operations import cache_delete, cache_get, cache_info, cache_set
 
 __all__ = [
     'configure',
@@ -29,10 +26,9 @@ __all__ = [
     'cache_clear',
     'cache_info',
     'get_backend',
+    'aget_backend',
     'get_redis_client',
     'Backend',
-    'AsyncBackend',
-    'async_cache',
     'async_cache_get',
     'async_cache_set',
     'async_cache_delete',

cachu/backends/__init__.py

@@ -1,16 +1,21 @@
 """Cache backend implementations.
 """
 from abc import ABC, abstractmethod
-from collections.abc import Iterator
-from typing import Any
+from collections.abc import AsyncIterator, Iterator
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..mutex import AsyncCacheMutex, CacheMutex
 
 NO_VALUE = object()
 
 
 class Backend(ABC):
-    """Abstract base class for cache backends.
+    """Abstract base class for cache backends with both sync and async interfaces.
     """
 
+    # ===== Sync interface =====
+
     @abstractmethod
     def get(self, key: str) -> Any:
         """Get value by key. Returns NO_VALUE if not found.
@@ -46,7 +51,62 @@ class Backend(ABC):
         """Count keys matching pattern.
         """
 
+    @abstractmethod
+    def get_mutex(self, key: str) -> 'CacheMutex':
+        """Get a mutex for dogpile prevention on the given key.
+        """
+
+    # ===== Async interface =====
+
+    @abstractmethod
+    async def aget(self, key: str) -> Any:
+        """Async get value by key. Returns NO_VALUE if not found.
+        """
+
+    @abstractmethod
+    async def aget_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Async get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+
+    @abstractmethod
+    async def aset(self, key: str, value: Any, ttl: int) -> None:
+        """Async set value with TTL in seconds.
+        """
+
+    @abstractmethod
+    async def adelete(self, key: str) -> None:
+        """Async delete value by key.
+        """
+
+    @abstractmethod
+    async def aclear(self, pattern: str | None = None) -> int:
+        """Async clear entries matching pattern. Returns count of cleared entries.
+        """
+
+    @abstractmethod
+    def akeys(self, pattern: str | None = None) -> AsyncIterator[str]:
+        """Async iterate over keys matching pattern.
+        """
+
+    @abstractmethod
+    async def acount(self, pattern: str | None = None) -> int:
+        """Async count keys matching pattern.
+        """
+
+    @abstractmethod
+    def get_async_mutex(self, key: str) -> 'AsyncCacheMutex':
+        """Get an async mutex for dogpile prevention on the given key.
+        """
+
+    # ===== Lifecycle =====
+
+    def close(self) -> None:
+        """Close the backend and release resources.
+        """
+
+    async def aclose(self) -> None:
+        """Async close the backend and release resources.
+        """
 
-from .async_base import AsyncBackend
 
-__all__ = ['Backend', 'AsyncBackend', 'NO_VALUE']
+__all__ = ['Backend', 'NO_VALUE']

cachu/backends/memory.py

@@ -1,102 +1,204 @@
 """Memory cache backend implementation.
 """
+import asyncio
 import fnmatch
 import pickle
 import threading
 import time
-from collections.abc import Iterator
+from collections.abc import AsyncIterator, Iterator
 from typing import Any
 
+from ..mutex import AsyncioMutex, CacheMutex, ThreadingMutex
 from . import NO_VALUE, Backend
 
 
 class MemoryBackend(Backend):
-    """Thread-safe in-memory cache backend.
+    """Thread-safe in-memory cache backend with both sync and async interfaces.
     """
 
     def __init__(self) -> None:
         self._cache: dict[str, tuple[bytes, float, float]] = {}
-        self._lock = threading.RLock()
+        self._sync_lock = threading.RLock()
+        self._async_lock: asyncio.Lock | None = None
 
-    def get(self, key: str) -> Any:
-        """Get value by key. Returns NO_VALUE if not found or expired.
+    def _get_async_lock(self) -> asyncio.Lock:
+        """Lazy-create async lock (must be called from async context).
         """
-        with self._lock:
-            entry = self._cache.get(key)
-            if entry is None:
-                return NO_VALUE
+        if self._async_lock is None:
+            self._async_lock = asyncio.Lock()
+        return self._async_lock
 
-            pickled_value, created_at, expires_at = entry
-            if time.time() > expires_at:
-                del self._cache[key]
-                return NO_VALUE
+    # ===== Core logic (no locking) =====
 
-            return pickle.loads(pickled_value)
+    def _do_get(self, key: str) -> tuple[Any, float | None]:
+        """Get value and metadata without locking.
+        """
+        entry = self._cache.get(key)
+        if entry is None:
+            return NO_VALUE, None
 
-    def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
-        """Get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        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 _do_set(self, key: str, value: Any, ttl: int) -> None:
+        """Set value without locking.
         """
-        with self._lock:
-            entry = self._cache.get(key)
-            if entry is None:
-                return NO_VALUE, None
+        now = time.time()
+        pickled_value = pickle.dumps(value)
+        self._cache[key] = (pickled_value, now, now + ttl)
+
+    def _do_delete(self, key: str) -> None:
+        """Delete value without locking.
+        """
+        self._cache.pop(key, None)
+
+    def _do_clear(self, pattern: str | None = None) -> int:
+        """Clear entries matching pattern without locking.
+        """
+        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 _do_keys(self, pattern: str | None = None) -> list[str]:
+        """Get keys matching pattern without locking (returns snapshot).
+        """
+        now = time.time()
+        result = []
+        keys_to_delete = []
+
+        for key, entry in list(self._cache.items()):
+            _, _, expires_at = entry
+            if now > expires_at:
+                keys_to_delete.append(key)
+                continue
+            if pattern is None or fnmatch.fnmatch(key, pattern):
+                result.append(key)
+
+        for key in keys_to_delete:
+            self._cache.pop(key, None)
+
+        return result
 
-            pickled_value, created_at, expires_at = entry
-            if time.time() > expires_at:
-                del self._cache[key]
-                return NO_VALUE, None
+    # ===== Sync interface =====
 
-            return pickle.loads(pickled_value), created_at
+    def get(self, key: str) -> Any:
+        """Get value by key. Returns NO_VALUE if not found or expired.
+        """
+        with self._sync_lock:
+            value, _ = self._do_get(key)
+            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.
+        """
+        with self._sync_lock:
+            return self._do_get(key)
 
     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)
+        with self._sync_lock:
+            self._do_set(key, value, ttl)
 
     def delete(self, key: str) -> None:
         """Delete value by key.
         """
-        with self._lock:
-            self._cache.pop(key, None)
+        with self._sync_lock:
+            self._do_delete(key)
 
     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)
+        with self._sync_lock:
+            return self._do_clear(pattern)
 
     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())
+        with self._sync_lock:
+            all_keys = self._do_keys(pattern)
+        yield from all_keys
+
+    def count(self, pattern: str | None = None) -> int:
+        """Count keys matching pattern.
+        """
+        with self._sync_lock:
+            return len(self._do_keys(pattern))
+
+    def get_mutex(self, key: str) -> CacheMutex:
+        """Get a mutex for dogpile prevention on the given key.
+        """
+        return ThreadingMutex(f'memory:{key}')
+
+    # ===== Async interface =====
+
+    async def aget(self, key: str) -> Any:
+        """Async get value by key. Returns NO_VALUE if not found or expired.
+        """
+        async with self._get_async_lock():
+            value, _ = self._do_get(key)
+            return value
+
+    async def aget_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Async get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+        async with self._get_async_lock():
+            return self._do_get(key)
+
+    async def aset(self, key: str, value: Any, ttl: int) -> None:
+        """Async set value with TTL in seconds.
+        """
+        async with self._get_async_lock():
+            self._do_set(key, value, ttl)
+
+    async def adelete(self, key: str) -> None:
+        """Async delete value by key.
+        """
+        async with self._get_async_lock():
+            self._do_delete(key)
+
+    async def aclear(self, pattern: str | None = None) -> int:
+        """Async clear entries matching pattern. Returns count of cleared entries.
+        """
+        async with self._get_async_lock():
+            return self._do_clear(pattern)
+
+    async def akeys(self, pattern: str | None = None) -> AsyncIterator[str]:
+        """Async iterate over keys matching pattern.
+        """
+        async with self._get_async_lock():
+            all_keys = self._do_keys(pattern)
 
         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
+            yield key
 
-            if pattern is None or fnmatch.fnmatch(key, pattern):
-                yield key
+    async def acount(self, pattern: str | None = None) -> int:
+        """Async count keys matching pattern.
+        """
+        async with self._get_async_lock():
+            return len(self._do_keys(pattern))
 
-    def count(self, pattern: str | None = None) -> int:
-        """Count keys matching pattern.
+    def get_async_mutex(self, key: str) -> AsyncioMutex:
+        """Get an async mutex for dogpile prevention on the given key.
+        """
+        return AsyncioMutex(f'memory:{key}')
+
+    # ===== Lifecycle =====
+
+    def close(self) -> None:
+        """Close the backend (no-op for memory backend).
+        """
+
+    async def aclose(self) -> None:
+        """Async close the backend (no-op for memory backend).
         """
-        return sum(1 for _ in self.keys(pattern))

cachu/backends/redis.py

@@ -3,13 +3,15 @@
 import pickle
 import struct
 import time
-from collections.abc import Iterator
+from collections.abc import AsyncIterator, Iterator
 from typing import TYPE_CHECKING, Any
 
+from ..mutex import AsyncCacheMutex, AsyncRedisMutex, CacheMutex, RedisMutex
 from . import NO_VALUE, Backend
 
 if TYPE_CHECKING:
     import redis
+    import redis.asyncio as aioredis
 
 
 _METADATA_FORMAT = 'd'
@@ -24,7 +26,20 @@ def _get_redis_module() -> Any:
         return redis
     except ImportError as e:
         raise RuntimeError(
-            "Redis support requires the 'redis' package. Install with: pip install cache[redis]"
+            "Redis support requires the 'redis' package. Install with: pip install cachu[redis]"
+        ) from e
+
+
+def _get_async_redis_module() -> Any:
+    """Import redis.asyncio module, raising helpful error if not installed.
+    """
+    try:
+        import redis.asyncio as aioredis
+        return aioredis
+    except ImportError as e:
+        raise RuntimeError(
+            "Async Redis support requires the 'redis' package (>=4.2.0). "
+            "Install with: pip install cachu[redis]"
         ) from e
 
 
@@ -38,36 +53,49 @@ def get_redis_client(url: str) -> 'redis.Redis':
     return redis_module.from_url(url)
 
 
+def _pack_value(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(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
+
+
 class RedisBackend(Backend):
-    """Redis cache backend.
+    """Unified Redis cache backend with both sync and async interfaces.
     """
 
-    def __init__(self, url: str, distributed_lock: bool = False) -> None:
+    def __init__(self, url: str, lock_timeout: float = 10.0) -> None:
         self._url = url
-        self._distributed_lock = distributed_lock
-        self._client: redis.Redis | None = None
+        self._lock_timeout = lock_timeout
+        self._sync_client: redis.Redis | None = None
+        self._async_client: aioredis.Redis | None = None
 
     @property
     def client(self) -> 'redis.Redis':
-        """Lazy-load Redis client.
+        """Lazy-load sync Redis client.
         """
-        if self._client is None:
-            self._client = get_redis_client(self._url)
-        return self._client
+        if self._sync_client is None:
+            self._sync_client = get_redis_client(self._url)
+        return self._sync_client
 
-    def _pack_value(self, value: Any, created_at: float) -> bytes:
-        """Pack value with creation timestamp.
+    def _get_async_client(self) -> 'aioredis.Redis':
+        """Lazy-load async Redis client (from_url is NOT async).
         """
-        metadata = struct.pack(_METADATA_FORMAT, created_at)
-        pickled = pickle.dumps(value)
-        return metadata + pickled
+        if self._async_client is None:
+            aioredis = _get_async_redis_module()
+            self._async_client = aioredis.from_url(self._url)
+        return self._async_client
 
-    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
+    # ===== Sync interface =====
 
     def get(self, key: str) -> Any:
         """Get value by key. Returns NO_VALUE if not found.
@@ -75,7 +103,7 @@ class RedisBackend(Backend):
         data = self.client.get(key)
         if data is None:
             return NO_VALUE
-        value, _ = self._unpack_value(data)
+        value, _ = _unpack_value(data)
         return value
 
     def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
@@ -84,14 +112,14 @@ class RedisBackend(Backend):
         data = self.client.get(key)
         if data is None:
             return NO_VALUE, None
-        value, created_at = self._unpack_value(data)
+        value, created_at = _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)
+        packed = _pack_value(value, now)
         self.client.setex(key, ttl, packed)
 
     def delete(self, key: str) -> None:
@@ -123,9 +151,113 @@ class RedisBackend(Backend):
         """
         return sum(1 for _ in self.keys(pattern))
 
+    def get_mutex(self, key: str) -> CacheMutex:
+        """Get a mutex for dogpile prevention on the given key.
+        """
+        return RedisMutex(self.client, f'lock:{key}', self._lock_timeout)
+
+    # ===== Async interface =====
+
+    async def aget(self, key: str) -> Any:
+        """Async get value by key. Returns NO_VALUE if not found.
+        """
+        client = self._get_async_client()
+        data = await client.get(key)
+        if data is None:
+            return NO_VALUE
+        value, _ = _unpack_value(data)
+        return value
+
+    async def aget_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Async get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+        client = self._get_async_client()
+        data = await client.get(key)
+        if data is None:
+            return NO_VALUE, None
+        value, created_at = _unpack_value(data)
+        return value, created_at
+
+    async def aset(self, key: str, value: Any, ttl: int) -> None:
+        """Async set value with TTL in seconds.
+        """
+        client = self._get_async_client()
+        now = time.time()
+        packed = _pack_value(value, now)
+        await client.setex(key, ttl, packed)
+
+    async def adelete(self, key: str) -> None:
+        """Async delete value by key.
+        """
+        client = self._get_async_client()
+        await client.delete(key)
+
+    async def aclear(self, pattern: str | None = None) -> int:
+        """Async clear entries matching pattern. Returns count of cleared entries.
+        """
+        client = self._get_async_client()
+        if pattern is None:
+            pattern = '*'
+
+        count = 0
+        async for key in client.scan_iter(match=pattern):
+            await client.delete(key)
+            count += 1
+        return count
+
+    async def akeys(self, pattern: str | None = None) -> AsyncIterator[str]:
+        """Async iterate over keys matching pattern.
+        """
+        client = self._get_async_client()
+        redis_pattern = pattern or '*'
+        async for key in client.scan_iter(match=redis_pattern):
+            yield key.decode() if isinstance(key, bytes) else key
+
+    async def acount(self, pattern: str | None = None) -> int:
+        """Async count keys matching pattern.
+        """
+        count = 0
+        async for _ in self.akeys(pattern):
+            count += 1
+        return count
+
+    def get_async_mutex(self, key: str) -> AsyncCacheMutex:
+        """Get an async mutex for dogpile prevention on the given key.
+        """
+        return AsyncRedisMutex(self._get_async_client(), f'lock:{key}', self._lock_timeout)
+
+    # ===== Lifecycle =====
+
+    def _close_sync_client(self) -> None:
+        """Close sync client if open.
+        """
+        if self._sync_client is not None:
+            client = self._sync_client
+            self._sync_client = None
+            client.close()
+
+    def _close_async_client_sync(self) -> None:
+        """Forcefully close async client from sync context.
+        """
+        if self._async_client is not None:
+            client = self._async_client
+            self._async_client = None
+            try:
+                client.close()
+            except Exception:
+                pass
+
     def close(self) -> None:
-        """Close the Redis connection.
+        """Close all backend resources from sync context.
+        """
+        self._close_sync_client()
+        self._close_async_client_sync()
+
+    async def aclose(self) -> None:
+        """Close all backend resources from async context.
         """
-        if self._client is not None:
-            self._client.close()
-            self._client = None
+        if self._async_client is not None:
+            client = self._async_client
+            self._async_client = None
+            await client.aclose()
+        self._close_sync_client()