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

cachu/mutex.py

@@ -0,0 +1,247 @@
+"""Mutex implementations for cache dogpile prevention.
+"""
+import asyncio
+import threading
+import time
+import uuid
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, ClassVar, Self
+
+if TYPE_CHECKING:
+    import redis
+    import redis.asyncio as aioredis
+
+
+class CacheMutex(ABC):
+    """Abstract base class for synchronous cache mutexes.
+    """
+
+    @abstractmethod
+    def acquire(self, timeout: float | None = None) -> bool:
+        """Acquire the lock. Returns True if acquired, False on timeout.
+        """
+
+    @abstractmethod
+    def release(self) -> None:
+        """Release the lock.
+        """
+
+    def __enter__(self) -> Self:
+        self.acquire()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.release()
+
+
+class AsyncCacheMutex(ABC):
+    """Abstract base class for asynchronous cache mutexes.
+    """
+
+    @abstractmethod
+    async def acquire(self, timeout: float | None = None) -> bool:
+        """Acquire the lock. Returns True if acquired, False on timeout.
+        """
+
+    @abstractmethod
+    async def release(self) -> None:
+        """Release the lock.
+        """
+
+    async def __aenter__(self) -> Self:
+        await self.acquire()
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.release()
+
+
+class NullMutex(CacheMutex):
+    """No-op mutex for testing or when locking is not needed.
+    """
+
+    def acquire(self, timeout: float | None = None) -> bool:
+        return True
+
+    def release(self) -> None:
+        pass
+
+
+class NullAsyncMutex(AsyncCacheMutex):
+    """No-op async mutex for testing or when locking is not needed.
+    """
+
+    async def acquire(self, timeout: float | None = None) -> bool:
+        return True
+
+    async def release(self) -> None:
+        pass
+
+
+class ThreadingMutex(CacheMutex):
+    """Per-key threading.Lock for local dogpile prevention.
+    """
+    _locks: ClassVar[dict[str, threading.Lock]] = {}
+    _registry_lock: ClassVar[threading.Lock] = threading.Lock()
+
+    def __init__(self, key: str) -> None:
+        self._key = key
+        self._acquired = False
+        with self._registry_lock:
+            if key not in self._locks:
+                self._locks[key] = threading.Lock()
+            self._lock = self._locks[key]
+
+    def acquire(self, timeout: float | None = None) -> bool:
+        if timeout is None:
+            self._acquired = self._lock.acquire()
+        else:
+            self._acquired = self._lock.acquire(timeout=timeout)
+        return self._acquired
+
+    def release(self) -> None:
+        if self._acquired:
+            self._lock.release()
+            self._acquired = False
+
+    @classmethod
+    def clear_locks(cls) -> None:
+        """Clear all locks. For testing only.
+        """
+        with cls._registry_lock:
+            cls._locks.clear()
+
+
+class AsyncioMutex(AsyncCacheMutex):
+    """Per-key asyncio.Lock for local async dogpile prevention.
+    """
+    _locks: ClassVar[dict[str, asyncio.Lock]] = {}
+
+    def __init__(self, key: str) -> None:
+        self._key = key
+        self._acquired = False
+        if key not in self._locks:
+            self._locks[key] = asyncio.Lock()
+        self._lock = self._locks[key]
+
+    async def acquire(self, timeout: float | None = None) -> bool:
+        if timeout is None:
+            await self._lock.acquire()
+            self._acquired = True
+            return True
+
+        try:
+            await asyncio.wait_for(self._lock.acquire(), timeout=timeout)
+            self._acquired = True
+            return True
+        except asyncio.TimeoutError:
+            return False
+
+    async def release(self) -> None:
+        if self._acquired:
+            self._lock.release()
+            self._acquired = False
+
+    @classmethod
+    def clear_locks(cls) -> None:
+        """Clear all locks. For testing only.
+        """
+        cls._locks.clear()
+
+
+class RedisMutex(CacheMutex):
+    """Distributed lock using Redis SET NX EX.
+    """
+    _RELEASE_SCRIPT = """
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+    end
+    return 0
+    """
+
+    def __init__(
+        self,
+        client: 'redis.Redis',
+        key: str,
+        lock_timeout: float = 10.0,
+    ) -> None:
+        self._client = client
+        self._key = key
+        self._lock_timeout = lock_timeout
+        self._token = str(uuid.uuid4())
+        self._acquired = False
+
+    def acquire(self, timeout: float | None = None) -> bool:
+        timeout = timeout or self._lock_timeout
+        end = time.time() + timeout
+        while time.time() < end:
+            if self._client.set(
+                self._key,
+                self._token,
+                nx=True,
+                ex=int(self._lock_timeout),
+            ):
+                self._acquired = True
+                return True
+            time.sleep(0.05)
+        return False
+
+    def release(self) -> None:
+        if self._acquired:
+            self._client.eval(self._RELEASE_SCRIPT, 1, self._key, self._token)
+            self._acquired = False
+
+
+class AsyncRedisMutex(AsyncCacheMutex):
+    """Async distributed lock using redis.asyncio.
+    """
+    _RELEASE_SCRIPT = """
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+        return redis.call("del", KEYS[1])
+    end
+    return 0
+    """
+
+    def __init__(
+        self,
+        client: 'aioredis.Redis',
+        key: str,
+        lock_timeout: float = 10.0,
+    ) -> None:
+        self._client = client
+        self._key = key
+        self._lock_timeout = lock_timeout
+        self._token = str(uuid.uuid4())
+        self._acquired = False
+
+    async def acquire(self, timeout: float | None = None) -> bool:
+        timeout = timeout or self._lock_timeout
+        end = time.time() + timeout
+        while time.time() < end:
+            if await self._client.set(
+                self._key,
+                self._token,
+                nx=True,
+                ex=int(self._lock_timeout),
+            ):
+                self._acquired = True
+                return True
+            await asyncio.sleep(0.05)
+        return False
+
+    async def release(self) -> None:
+        if self._acquired:
+            await self._client.eval(self._RELEASE_SCRIPT, 1, self._key, self._token)
+            self._acquired = False
+
+
+__all__ = [
+    'CacheMutex',
+    'AsyncCacheMutex',
+    'NullMutex',
+    'NullAsyncMutex',
+    'ThreadingMutex',
+    'AsyncioMutex',
+    'RedisMutex',
+    'AsyncRedisMutex',
+]

cachu/operations.py

@@ -1,4 +1,4 @@
-"""Cache CRUD operations.
+"""Cache CRUD operations for sync and async APIs.
 """
 import logging
 from collections.abc import Callable
@@ -6,8 +6,8 @@ from typing import Any
 
 from .backends import NO_VALUE
 from .config import _get_caller_package, get_config
-from .decorator import _get_backend, get_cache_info
-from .keys import mangle_key
+from .decorator import get_async_cache_info, get_cache_info, manager
+from .keys import _tag_to_pattern, mangle_key
 from .types import CacheInfo, CacheMeta
 
 logger = logging.getLogger(__name__)
@@ -15,12 +15,12 @@ logger = logging.getLogger(__name__)
 _MISSING = object()
 
 
-def _get_meta(fn: Callable[..., Any]) -> CacheMeta:
+def _get_meta(fn: Callable[..., Any], decorator_name: str = '@cache') -> CacheMeta:
     """Get CacheMeta from a decorated function.
     """
     meta = getattr(fn, '_cache_meta', None)
     if meta is None:
-        raise ValueError(f'{fn.__name__} is not decorated with @cache')
+        raise ValueError(f'{fn.__name__} is not decorated with {decorator_name}')
     return meta
 
 
@@ -46,7 +46,7 @@ def cache_get(fn: Callable[..., Any], default: Any = _MISSING, **kwargs: Any) ->
     base_key = key_generator(**kwargs)
     cache_key = mangle_key(base_key, cfg.key_prefix, meta.ttl)
 
-    backend = _get_backend(meta.package, meta.backend, meta.ttl)
+    backend = manager.get_backend(meta.package, meta.backend, meta.ttl)
     value = backend.get(cache_key)
 
     if value is NO_VALUE:
@@ -75,7 +75,7 @@ def cache_set(fn: Callable[..., Any], value: Any, **kwargs: Any) -> None:
     base_key = key_generator(**kwargs)
     cache_key = mangle_key(base_key, cfg.key_prefix, meta.ttl)
 
-    backend = _get_backend(meta.package, meta.backend, meta.ttl)
+    backend = manager.get_backend(meta.package, meta.backend, meta.ttl)
     backend.set(cache_key, value, meta.ttl)
 
     logger.debug(f'Set cache for {fn.__name__} with key {cache_key}')
@@ -98,7 +98,7 @@ def cache_delete(fn: Callable[..., Any], **kwargs: Any) -> None:
     base_key = key_generator(**kwargs)
     cache_key = mangle_key(base_key, cfg.key_prefix, meta.ttl)
 
-    backend = _get_backend(meta.package, meta.backend, meta.ttl)
+    backend = manager.get_backend(meta.package, meta.backend, meta.ttl)
     backend.delete(cache_key)
 
     logger.debug(f'Deleted cache for {fn.__name__} with key {cache_key}')
@@ -129,28 +129,18 @@ def cache_clear(
     else:
         backends_to_clear = ['memory', 'file', 'redis']
 
-    if tag:
-        from .keys import _normalize_tag
-        pattern = f'*|{_normalize_tag(tag)}|*'
-    else:
-        pattern = None
-
+    pattern = _tag_to_pattern(tag)
     total_cleared = 0
 
-    from .decorator import _backends, _backends_lock
-
-    # When both backend and ttl are specified, directly get/create and clear that backend.
-    # This is essential for distributed caches (Redis) where cache_clear may be called
-    # from a different process than the one that populated the cache.
     if backend is not None and ttl is not None:
-        backend_instance = _get_backend(package, backend, ttl)
+        backend_instance = manager.get_backend(package, backend, ttl)
         cleared = backend_instance.clear(pattern)
         if cleared > 0:
             total_cleared += cleared
             logger.debug(f'Cleared {cleared} entries from {backend} backend (ttl={ttl})')
     else:
-        with _backends_lock:
-            for (pkg, btype, bttl), backend_instance in list(_backends.items()):
+        with manager._sync_lock:
+            for (pkg, btype, bttl), backend_instance in list(manager.backends.items()):
                 if pkg != package:
                     continue
                 if btype not in backends_to_clear:
@@ -163,6 +153,9 @@ def cache_clear(
                     total_cleared += cleared
                     logger.debug(f'Cleared {cleared} entries from {btype} backend (ttl={bttl})')
 
+    with manager._stats_lock:
+        manager.stats.clear()
+
     return total_cleared
 
 
@@ -178,5 +171,160 @@ def cache_info(fn: Callable[..., Any]) -> CacheInfo:
     Raises
         ValueError: If function is not decorated with @cache
     """
-    _get_meta(fn)  # Validate it's decorated
+    _get_meta(fn)
     return get_cache_info(fn)
+
+
+async def async_cache_get(
+    fn: Callable[..., Any],
+    default: Any = _MISSING,
+    **kwargs: Any,
+) -> Any:
+    """Get a cached value without calling the async function.
+
+    Args:
+        fn: A function decorated with @cache
+        default: Value to return if not found (raises KeyError if not provided)
+        **kwargs: Function arguments to build the cache key
+
+    Returns
+        The cached value or default
+
+    Raises
+        KeyError: If not found and no default provided
+        ValueError: If function is not decorated with @cache
+    """
+    meta = _get_meta(fn, '@cache')
+    cfg = get_config(meta.package)
+
+    key_generator = fn._cache_key_generator
+    base_key = key_generator(**kwargs)
+    cache_key = mangle_key(base_key, cfg.key_prefix, meta.ttl)
+
+    backend = await manager.aget_backend(meta.package, meta.backend, meta.ttl)
+    value = await backend.aget(cache_key)
+
+    if value is NO_VALUE:
+        if default is _MISSING:
+            raise KeyError(f'No cached value for {fn.__name__} with {kwargs}')
+        return default
+
+    return value
+
+
+async def async_cache_set(fn: Callable[..., Any], value: Any, **kwargs: Any) -> None:
+    """Set a cached value directly without calling the async function.
+
+    Args:
+        fn: A function decorated with @cache
+        value: The value to cache
+        **kwargs: Function arguments to build the cache key
+
+    Raises
+        ValueError: If function is not decorated with @cache
+    """
+    meta = _get_meta(fn, '@cache')
+    cfg = get_config(meta.package)
+
+    key_generator = fn._cache_key_generator
+    base_key = key_generator(**kwargs)
+    cache_key = mangle_key(base_key, cfg.key_prefix, meta.ttl)
+
+    backend = await manager.aget_backend(meta.package, meta.backend, meta.ttl)
+    await backend.aset(cache_key, value, meta.ttl)
+
+    logger.debug(f'Set cache for {fn.__name__} with key {cache_key}')
+
+
+async def async_cache_delete(fn: Callable[..., Any], **kwargs: Any) -> None:
+    """Delete a specific cached entry.
+
+    Args:
+        fn: A function decorated with @cache
+        **kwargs: Function arguments to build the cache key
+
+    Raises
+        ValueError: If function is not decorated with @cache
+    """
+    meta = _get_meta(fn, '@cache')
+    cfg = get_config(meta.package)
+
+    key_generator = fn._cache_key_generator
+    base_key = key_generator(**kwargs)
+    cache_key = mangle_key(base_key, cfg.key_prefix, meta.ttl)
+
+    backend = await manager.aget_backend(meta.package, meta.backend, meta.ttl)
+    await backend.adelete(cache_key)
+
+    logger.debug(f'Deleted cache for {fn.__name__} with key {cache_key}')
+
+
+async def async_cache_clear(
+    tag: str | None = None,
+    backend: str | None = None,
+    ttl: int | None = None,
+    package: str | None = None,
+) -> int:
+    """Clear async cache entries matching criteria.
+
+    Args:
+        tag: Clear only entries with this tag
+        backend: Backend type to clear ('memory', 'file', 'redis'). Clears all if None.
+        ttl: Specific TTL region to clear. Clears all TTLs if None.
+        package: Package to clear for. Auto-detected if None.
+
+    Returns
+        Number of entries cleared (may be approximate)
+    """
+    if package is None:
+        package = _get_caller_package()
+
+    if backend is not None:
+        backends_to_clear = [backend]
+    else:
+        backends_to_clear = ['memory', 'file', 'redis']
+
+    pattern = _tag_to_pattern(tag)
+    total_cleared = 0
+
+    if backend is not None and ttl is not None:
+        backend_instance = await manager.aget_backend(package, backend, ttl)
+        cleared = await backend_instance.aclear(pattern)
+        if cleared > 0:
+            total_cleared += cleared
+            logger.debug(f'Cleared {cleared} entries from {backend} backend (ttl={ttl})')
+    else:
+        async with manager._get_async_lock():
+            for (pkg, btype, bttl), backend_instance in list(manager.backends.items()):
+                if pkg != package:
+                    continue
+                if btype not in backends_to_clear:
+                    continue
+                if ttl is not None and bttl != ttl:
+                    continue
+
+                cleared = await backend_instance.aclear(pattern)
+                if cleared > 0:
+                    total_cleared += cleared
+                    logger.debug(f'Cleared {cleared} entries from {btype} backend (ttl={bttl})')
+
+    with manager._stats_lock:
+        manager.stats.clear()
+
+    return total_cleared
+
+
+async def async_cache_info(fn: Callable[..., Any]) -> CacheInfo:
+    """Get cache statistics for an async decorated function.
+
+    Args:
+        fn: A function decorated with @cache
+
+    Returns
+        CacheInfo with hits, misses, and currsize
+
+    Raises
+        ValueError: If function is not decorated with @cache
+    """
+    _get_meta(fn, '@cache')
+    return await get_async_cache_info(fn)

{cachu-0.2.3.dist-info → cachu-0.2.5.dist-info}/METADATA

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: cachu
-Version: 0.2.3
+Version: 0.2.5
 Summary: Flexible caching library with sync and async support for memory, file (SQLite), and Redis backends
 Author: bissli
 License-Expression: 0BSD
 Project-URL: Repository, https://github.com/bissli/cachu.git
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: dogpile.cache
 Requires-Dist: func-timeout
 Provides-Extra: async
 Requires-Dist: aiosqlite; extra == "async"
@@ -69,19 +68,17 @@ cachu.configure(
     key_prefix='v1:',           # Prefix for all cache keys
     file_dir='/var/cache/app',  # Directory for file cache
     redis_url='redis://localhost:6379/0',  # Redis connection URL
-    redis_distributed=False,    # Use distributed locks for Redis
 )
 ```
 
 ### Configuration Options
 
-| Option              | Default                      | Description                                       |
-| ------------------- | ---------------------------- | ------------------------------------------------- |
-| `backend`           | `'memory'`                   | Default backend type                              |
-| `key_prefix`        | `''`                         | Prefix for all cache keys (useful for versioning) |
-| `file_dir`          | `'/tmp'`                     | Directory for file-based caches                   |
-| `redis_url`         | `'redis://localhost:6379/0'` | Redis connection URL                              |
-| `redis_distributed` | `False`                      | Enable distributed locks for Redis                |
+| Option       | Default                      | Description                                       |
+| ------------ | ---------------------------- | ------------------------------------------------- |
+| `backend`    | `'memory'`                   | Default backend type                              |
+| `key_prefix` | `''`                         | Prefix for all cache keys (useful for versioning) |
+| `file_dir`   | `'/tmp'`                     | Directory for file-based caches                   |
+| `redis_url`  | `'redis://localhost:6379/0'` | Redis connection URL                              |
 
 ### Package Isolation
 

cachu-0.2.5.dist-info/RECORD

@@ -0,0 +1,15 @@
+cachu/__init__.py,sha256=b3uooLcOZo5mfJqrTKi1ldBe8gu9k2L3DK4L2B0ifxA,1156
+cachu/config.py,sha256=u5Oqsy4bx3OMk3ImGDCzvO-U-HrRAxaC4dKHE4PUmQw,5909
+cachu/decorator.py,sha256=YIO7n9gEpZNx4UHzWORI2H9mpENxGFnX_WfT9EOhQ8c,17724
+cachu/keys.py,sha256=3em9_umQYFwwF2EwmIK8yWJq8aO2CI1DMRjq6Je3xC8,3747
+cachu/mutex.py,sha256=SJpbKroS43UmuR_UlT9wPXhOnwDYdABo6iLkhrlVqMc,6464
+cachu/operations.py,sha256=Z1zI5nhlEpM1diJQf7XHQ9cpH1HbIkdSizJV6NxLZPE,10216
+cachu/types.py,sha256=FghBN5GhxnrpuT4WUL9iNnAfdoH__cw9_Ag4kHbIXq4,723
+cachu/backends/__init__.py,sha256=hUGASS8kKMebf7O36RUrvpcSfi4KbcJPUwgqgccTbcw,3100
+cachu/backends/memory.py,sha256=XWBoh4x3m6WiTAy4hrmm4NA6NkiTwlRxrAHxvVTG9mo,6473
+cachu/backends/redis.py,sha256=kMVmb2EQJbc6zoSYuLUOFgxnSX_wgA1uiu_8mF0htV0,8307
+cachu/backends/sqlite.py,sha256=RGI8Iycxi7kMAtQmjhIorsf5bLutcyr6Xw_i8iYK3JQ,18181
+cachu-0.2.5.dist-info/METADATA,sha256=78331qx3dAztbUvFmB3WBZhKbi_3b7Qa0F8Kk85s4QE,11748
+cachu-0.2.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+cachu-0.2.5.dist-info/top_level.txt,sha256=g80nNoMvLMzhSwQWV-JotCBqtsLAHeFMBo_g8hCK8hQ,6
+cachu-0.2.5.dist-info/RECORD,,