cachu 0.2.4__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

@@ -6,8 +6,7 @@ from typing import Any
 
 from .backends import NO_VALUE
 from .config import _get_caller_package, get_config
-from .decorator import async_manager, get_async_cache_info, get_cache_info
-from .decorator import manager
+from .decorator import get_async_cache_info, get_cache_info, manager
 from .keys import _tag_to_pattern, mangle_key
 from .types import CacheInfo, CacheMeta
 
@@ -140,7 +139,7 @@ def cache_clear(
             total_cleared += cleared
             logger.debug(f'Cleared {cleared} entries from {backend} backend (ttl={ttl})')
     else:
-        with manager._backends_lock:
+        with manager._sync_lock:
             for (pkg, btype, bttl), backend_instance in list(manager.backends.items()):
                 if pkg != package:
                     continue
@@ -184,7 +183,7 @@ async def async_cache_get(
     """Get a cached value without calling the async function.
 
     Args:
-        fn: A function decorated with @async_cache
+        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
 
@@ -193,17 +192,17 @@ async def async_cache_get(
 
     Raises
         KeyError: If not found and no default provided
-        ValueError: If function is not decorated with @async_cache
+        ValueError: If function is not decorated with @cache
     """
-    meta = _get_meta(fn, '@async_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 async_manager.get_backend(meta.package, meta.backend, meta.ttl)
-    value = await backend.get(cache_key)
+    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:
@@ -217,22 +216,22 @@ async def async_cache_set(fn: Callable[..., Any], value: Any, **kwargs: Any) ->
     """Set a cached value directly without calling the async function.
 
     Args:
-        fn: A function decorated with @async_cache
+        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 @async_cache
+        ValueError: If function is not decorated with @cache
     """
-    meta = _get_meta(fn, '@async_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 async_manager.get_backend(meta.package, meta.backend, meta.ttl)
-    await backend.set(cache_key, value, 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}')
 
@@ -241,21 +240,21 @@ async def async_cache_delete(fn: Callable[..., Any], **kwargs: Any) -> None:
     """Delete a specific cached entry.
 
     Args:
-        fn: A function decorated with @async_cache
+        fn: A function decorated with @cache
         **kwargs: Function arguments to build the cache key
 
     Raises
-        ValueError: If function is not decorated with @async_cache
+        ValueError: If function is not decorated with @cache
     """
-    meta = _get_meta(fn, '@async_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 async_manager.get_backend(meta.package, meta.backend, meta.ttl)
-    await backend.delete(cache_key)
+    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}')
 
@@ -289,14 +288,14 @@ async def async_cache_clear(
     total_cleared = 0
 
     if backend is not None and ttl is not None:
-        backend_instance = await async_manager.get_backend(package, backend, ttl)
-        cleared = await backend_instance.clear(pattern)
+        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 async_manager._backends_lock:
-            for (pkg, btype, bttl), backend_instance in list(async_manager.backends.items()):
+        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:
@@ -304,13 +303,13 @@ async def async_cache_clear(
                 if ttl is not None and bttl != ttl:
                     continue
 
-                cleared = await backend_instance.clear(pattern)
+                cleared = await backend_instance.aclear(pattern)
                 if cleared > 0:
                     total_cleared += cleared
                     logger.debug(f'Cleared {cleared} entries from {btype} backend (ttl={bttl})')
 
-    async with async_manager._stats_lock:
-        async_manager.stats.clear()
+    with manager._stats_lock:
+        manager.stats.clear()
 
     return total_cleared
 
@@ -319,13 +318,13 @@ async def async_cache_info(fn: Callable[..., Any]) -> CacheInfo:
     """Get cache statistics for an async decorated function.
 
     Args:
-        fn: A function decorated with @async_cache
+        fn: A function decorated with @cache
 
     Returns
         CacheInfo with hits, misses, and currsize
 
     Raises
-        ValueError: If function is not decorated with @async_cache
+        ValueError: If function is not decorated with @cache
     """
-    _get_meta(fn, '@async_cache')
+    _get_meta(fn, '@cache')
     return await get_async_cache_info(fn)

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

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: cachu
-Version: 0.2.4
+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"

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,,

cachu/async_decorator.py

@@ -1,262 +0,0 @@
-"""Async cache decorator implementation.
-"""
-import asyncio
-import logging
-import os
-import time
-from collections.abc import Awaitable, Callable
-from functools import wraps
-from typing import Any
-
-from .backends import NO_VALUE
-from .backends.async_base import AsyncBackend
-from .backends.async_memory import AsyncMemoryBackend
-from .config import _get_caller_package, get_config, is_disabled
-from .keys import make_key_generator, mangle_key
-from .types import CacheEntry, CacheInfo, CacheMeta
-
-logger = logging.getLogger(__name__)
-
-_async_backends: dict[tuple[str | None, str, int], AsyncBackend] = {}
-_async_backends_lock = asyncio.Lock()
-
-_async_stats: dict[int, tuple[int, int]] = {}
-_async_stats_lock = asyncio.Lock()
-
-
-async def _get_async_backend(package: str | None, backend_type: str, ttl: int) -> AsyncBackend:
-    """Get or create an async backend instance.
-    """
-    key = (package, backend_type, ttl)
-
-    async with _async_backends_lock:
-        if key in _async_backends:
-            return _async_backends[key]
-
-        cfg = get_config(package)
-
-        if backend_type == 'memory':
-            backend: AsyncBackend = AsyncMemoryBackend()
-        elif backend_type == 'file':
-            from .backends.async_sqlite import AsyncSqliteBackend
-
-            if ttl < 60:
-                filename = f'cache{ttl}sec.db'
-            elif ttl < 3600:
-                filename = f'cache{ttl // 60}min.db'
-            else:
-                filename = f'cache{ttl // 3600}hour.db'
-
-            if package:
-                filename = f'{package}_{filename}'
-
-            filepath = os.path.join(cfg.file_dir, filename)
-            backend = AsyncSqliteBackend(filepath)
-        elif backend_type == 'redis':
-            from .backends.async_redis import AsyncRedisBackend
-            backend = AsyncRedisBackend(cfg.redis_url, cfg.redis_distributed)
-        else:
-            raise ValueError(f'Unknown backend type: {backend_type}')
-
-        _async_backends[key] = backend
-        logger.debug(f"Created async {backend_type} backend for package '{package}', {ttl}s TTL")
-        return backend
-
-
-async def get_async_backend(
-    backend_type: str | None = None,
-    package: str | None = None,
-    *,
-    ttl: int,
-) -> AsyncBackend:
-    """Get an async backend instance.
-
-    Args:
-        backend_type: 'memory', 'file', or 'redis'. Uses config default if None.
-        package: Package name. Auto-detected if None.
-        ttl: TTL in seconds (used for backend separation).
-    """
-    if package is None:
-        package = _get_caller_package()
-
-    if backend_type is None:
-        cfg = get_config(package)
-        backend_type = cfg.backend
-
-    return await _get_async_backend(package, backend_type, ttl)
-
-
-def async_cache(
-    ttl: int = 300,
-    backend: str | None = None,
-    tag: str = '',
-    exclude: set[str] | None = None,
-    cache_if: Callable[[Any], bool] | None = None,
-    validate: Callable[[CacheEntry], bool] | None = None,
-    package: str | None = None,
-) -> Callable[[Callable[..., Awaitable[Any]]], Callable[..., Awaitable[Any]]]:
-    """Async cache decorator with configurable backend and behavior.
-
-    Args:
-        ttl: Time-to-live in seconds (default: 300)
-        backend: Backend type ('memory', 'file', 'redis'). Uses config default if None.
-        tag: Tag for grouping related cache entries
-        exclude: Parameter names to exclude from cache key
-        cache_if: Function to determine if result should be cached.
-                  Called with result value, caches if returns True.
-        validate: Function to validate cached entries before returning.
-                  Called with CacheEntry, returns False to recompute.
-        package: Package name for config isolation. Auto-detected if None.
-
-    Per-call control via reserved kwargs (not passed to function):
-        _skip_cache: If True, bypass cache completely for this call
-        _overwrite_cache: If True, execute function and overwrite cached value
-
-    Example:
-        @async_cache(ttl=300, tag='users')
-        async def get_user(user_id: int) -> dict:
-            return await fetch_user(user_id)
-
-        # Normal call
-        user = await get_user(123)
-
-        # Skip cache
-        user = await get_user(123, _skip_cache=True)
-
-        # Force refresh
-        user = await get_user(123, _overwrite_cache=True)
-    """
-    resolved_package = package if package is not None else _get_caller_package()
-
-    if backend is None:
-        cfg = get_config(resolved_package)
-        resolved_backend = cfg.backend
-    else:
-        resolved_backend = backend
-
-    def decorator(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
-        key_generator = make_key_generator(fn, tag, exclude)
-
-        meta = CacheMeta(
-            ttl=ttl,
-            backend=resolved_backend,
-            tag=tag,
-            exclude=exclude or set(),
-            cache_if=cache_if,
-            validate=validate,
-            package=resolved_package,
-            key_generator=key_generator,
-        )
-
-        @wraps(fn)
-        async def wrapper(*args: Any, **kwargs: Any) -> Any:
-            skip_cache = kwargs.pop('_skip_cache', False)
-            overwrite_cache = kwargs.pop('_overwrite_cache', False)
-
-            if is_disabled() or skip_cache:
-                return await fn(*args, **kwargs)
-
-            backend_instance = await _get_async_backend(resolved_package, resolved_backend, ttl)
-            cfg = get_config(resolved_package)
-
-            base_key = key_generator(*args, **kwargs)
-            cache_key = mangle_key(base_key, cfg.key_prefix, ttl)
-
-            if not overwrite_cache:
-                value, created_at = await backend_instance.get_with_metadata(cache_key)
-
-                if value is not NO_VALUE:
-                    if validate is not None and created_at is not None:
-                        entry = CacheEntry(
-                            value=value,
-                            created_at=created_at,
-                            age=time.time() - created_at,
-                        )
-                        if not validate(entry):
-                            logger.debug(f'Cache validation failed for {fn.__name__}')
-                        else:
-                            await _record_async_hit(wrapper)
-                            return value
-                    else:
-                        await _record_async_hit(wrapper)
-                        return value
-
-            await _record_async_miss(wrapper)
-            result = await fn(*args, **kwargs)
-
-            should_cache = cache_if is None or cache_if(result)
-
-            if should_cache:
-                await backend_instance.set(cache_key, result, ttl)
-                logger.debug(f'Cached {fn.__name__} with key {cache_key}')
-
-            return result
-
-        wrapper._cache_meta = meta  # type: ignore
-        wrapper._cache_key_generator = key_generator  # type: ignore
-
-        return wrapper
-
-    return decorator
-
-
-async def _record_async_hit(fn: Callable[..., Any]) -> None:
-    """Record a cache hit for the async function.
-    """
-    fn_id = id(fn)
-    async with _async_stats_lock:
-        hits, misses = _async_stats.get(fn_id, (0, 0))
-        _async_stats[fn_id] = (hits + 1, misses)
-
-
-async def _record_async_miss(fn: Callable[..., Any]) -> None:
-    """Record a cache miss for the async function.
-    """
-    fn_id = id(fn)
-    async with _async_stats_lock:
-        hits, misses = _async_stats.get(fn_id, (0, 0))
-        _async_stats[fn_id] = (hits, misses + 1)
-
-
-async def get_async_cache_info(fn: Callable[..., Any]) -> CacheInfo:
-    """Get cache statistics for an async decorated function.
-
-    Args:
-        fn: A function decorated with @async_cache
-
-    Returns
-        CacheInfo with hits, misses, and currsize
-    """
-    fn_id = id(fn)
-
-    async with _async_stats_lock:
-        hits, misses = _async_stats.get(fn_id, (0, 0))
-
-    meta = getattr(fn, '_cache_meta', None)
-    if meta is None:
-        return CacheInfo(hits=hits, misses=misses, currsize=0)
-
-    backend_instance = await _get_async_backend(meta.package, meta.backend, meta.ttl)
-    cfg = get_config(meta.package)
-
-    fn_name = getattr(fn, '__wrapped__', fn).__name__
-    pattern = f'*:{cfg.key_prefix}{fn_name}|*'
-
-    currsize = await backend_instance.count(pattern)
-
-    return CacheInfo(hits=hits, misses=misses, currsize=currsize)
-
-
-async def clear_async_backends(package: str | None = None) -> None:
-    """Clear all async backend instances for a package. Primarily for testing.
-    """
-    async with _async_backends_lock:
-        if package is None:
-            for backend in _async_backends.values():
-                await backend.close()
-            _async_backends.clear()
-        else:
-            keys_to_delete = [k for k in _async_backends if k[0] == package]
-            for key in keys_to_delete:
-                await _async_backends[key].close()
-                del _async_backends[key]