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

cachu/decorator.py

@@ -1,4 +1,4 @@
-"""Cache decorator implementation with sync and async support.
+"""Cache decorator implementation with unified sync and async support.
 """
 import asyncio
 import logging
@@ -9,9 +9,9 @@ from collections.abc import Awaitable, Callable
 from functools import wraps
 from typing import Any
 
-from .backends import NO_VALUE, AsyncBackend, Backend
-from .backends.file import FileBackend
-from .backends.memory import AsyncMemoryBackend, MemoryBackend
+from .backends import NO_VALUE, Backend
+from .backends.memory import MemoryBackend
+from .backends.sqlite import SqliteBackend
 from .config import _get_caller_package, get_config, is_disabled
 from .keys import make_key_generator, mangle_key
 from .types import CacheEntry, CacheInfo, CacheMeta
@@ -20,50 +20,79 @@ logger = logging.getLogger(__name__)
 
 
 class CacheManager:
-    """Manages sync cache backends and statistics.
+    """Unified manager for cache backends and statistics.
     """
 
     def __init__(self) -> None:
         self.backends: dict[tuple[str | None, str, int], Backend] = {}
         self.stats: dict[int, tuple[int, int]] = {}
-        self._backends_lock = threading.Lock()
+        self._sync_lock = threading.Lock()
+        self._async_lock: asyncio.Lock | None = None
         self._stats_lock = threading.Lock()
 
-    def get_backend(self, package: str | None, backend_type: str, ttl: int) -> Backend:
-        """Get or create a backend instance.
+    def _get_async_lock(self) -> asyncio.Lock:
+        """Lazy-create async lock (must be called from async context).
         """
-        key = (package, backend_type, ttl)
+        if self._async_lock is None:
+            self._async_lock = asyncio.Lock()
+        return self._async_lock
+
+    def _create_backend(
+        self,
+        package: str | None,
+        backend_type: str,
+        ttl: int,
+    ) -> Backend:
+        """Create a backend instance (called with lock held).
+        """
+        cfg = get_config(package)
 
-        with self._backends_lock:
-            if key in self.backends:
-                return self.backends[key]
-
-            cfg = get_config(package)
-
-            if backend_type == 'memory':
-                backend = MemoryBackend()
-            elif backend_type == 'file':
-                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 = FileBackend(filepath)
-            elif backend_type == 'redis':
-                from .backends.redis import RedisBackend
-                backend = RedisBackend(cfg.redis_url)
+        if backend_type == 'memory':
+            backend: Backend = MemoryBackend()
+        elif backend_type == 'file':
+            if ttl < 60:
+                filename = f'cache{ttl}sec.db'
+            elif ttl < 3600:
+                filename = f'cache{ttl // 60}min.db'
             else:
-                raise ValueError(f'Unknown backend type: {backend_type}')
+                filename = f'cache{ttl // 3600}hour.db'
+
+            if package:
+                filename = f'{package}_{filename}'
 
-            self.backends[key] = backend
-            logger.debug(f"Created {backend_type} backend for package '{package}', {ttl}s TTL")
-            return backend
+            filepath = os.path.join(cfg.file_dir, filename)
+            backend = SqliteBackend(filepath)
+        elif backend_type == 'redis':
+            from .backends.redis import RedisBackend
+            backend = RedisBackend(cfg.redis_url, cfg.lock_timeout)
+        else:
+            raise ValueError(f'Unknown backend type: {backend_type}')
+
+        logger.debug(f"Created {backend_type} backend for package '{package}', {ttl}s TTL")
+        return backend
+
+    def get_backend(self, package: str | None, backend_type: str, ttl: int) -> Backend:
+        """Get or create a backend instance (sync).
+        """
+        key = (package, backend_type, ttl)
+        with self._sync_lock:
+            if key not in self.backends:
+                self.backends[key] = self._create_backend(package, backend_type, ttl)
+            return self.backends[key]
+
+    async def aget_backend(
+        self,
+        package: str | None,
+        backend_type: str,
+        ttl: int,
+    ) -> Backend:
+        """Get or create a backend instance (async).
+        """
+        key = (package, backend_type, ttl)
+        async with self._get_async_lock():
+            if key not in self.backends:
+                self.backends[key] = self._create_backend(package, backend_type, ttl)
+            return self.backends[key]
 
     def record_hit(self, fn: Callable[..., Any]) -> None:
         """Record a cache hit for the function.
@@ -89,110 +118,35 @@ class CacheManager:
             return self.stats.get(fn_id, (0, 0))
 
     def clear(self, package: str | None = None) -> None:
-        """Clear backend instances for a package.
+        """Clear backend instances (sync).
         """
-        with self._backends_lock:
+        with self._sync_lock:
             if package is None:
+                for backend in self.backends.values():
+                    backend.close()
                 self.backends.clear()
             else:
                 keys_to_delete = [k for k in self.backends if k[0] == package]
                 for key in keys_to_delete:
+                    self.backends[key].close()
                     del self.backends[key]
 
-
-class AsyncCacheManager:
-    """Manages async cache backends and statistics.
-    """
-
-    def __init__(self) -> None:
-        self.backends: dict[tuple[str | None, str, int], AsyncBackend] = {}
-        self.stats: dict[int, tuple[int, int]] = {}
-        self._backends_lock = asyncio.Lock()
-        self._stats_lock = asyncio.Lock()
-
-    async def get_backend(
-        self,
-        package: str | None,
-        backend_type: str,
-        ttl: int,
-    ) -> AsyncBackend:
-        """Get or create an async backend instance.
-        """
-        key = (package, backend_type, ttl)
-
-        async with self._backends_lock:
-            if key in self.backends:
-                return self.backends[key]
-
-            cfg = get_config(package)
-
-            if backend_type == 'memory':
-                backend: AsyncBackend = AsyncMemoryBackend()
-            elif backend_type == 'file':
-                from .backends.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.redis import AsyncRedisBackend
-                backend = AsyncRedisBackend(cfg.redis_url)
-            else:
-                raise ValueError(f'Unknown backend type: {backend_type}')
-
-            self.backends[key] = backend
-            logger.debug(f"Created async {backend_type} backend for package '{package}', {ttl}s TTL")
-            return backend
-
-    async def record_hit(self, fn: Callable[..., Any]) -> None:
-        """Record a cache hit for the async function.
-        """
-        fn_id = id(fn)
-        async with self._stats_lock:
-            hits, misses = self.stats.get(fn_id, (0, 0))
-            self.stats[fn_id] = (hits + 1, misses)
-
-    async def record_miss(self, fn: Callable[..., Any]) -> None:
-        """Record a cache miss for the async function.
-        """
-        fn_id = id(fn)
-        async with self._stats_lock:
-            hits, misses = self.stats.get(fn_id, (0, 0))
-            self.stats[fn_id] = (hits, misses + 1)
-
-    async def get_stats(self, fn: Callable[..., Any]) -> tuple[int, int]:
-        """Get (hits, misses) for a function.
-        """
-        fn_id = id(fn)
-        async with self._stats_lock:
-            return self.stats.get(fn_id, (0, 0))
-
-    async def clear(self, package: str | None = None) -> None:
-        """Clear backend instances, calling close() on each.
+    async def aclear(self, package: str | None = None) -> None:
+        """Clear backend instances (async).
         """
-        async with self._backends_lock:
+        async with self._get_async_lock():
             if package is None:
                 for backend in self.backends.values():
-                    await backend.close()
+                    await backend.aclose()
                 self.backends.clear()
             else:
                 keys_to_delete = [k for k in self.backends if k[0] == package]
                 for key in keys_to_delete:
-                    await self.backends[key].close()
+                    await self.backends[key].aclose()
                     del self.backends[key]
 
 
 manager = CacheManager()
-async_manager = AsyncCacheManager()
 
 
 def get_backend(
@@ -218,13 +172,13 @@ def get_backend(
     return manager.get_backend(package, backend_type, ttl)
 
 
-async def get_async_backend(
+async def aget_backend(
     backend_type: str | None = None,
     package: str | None = None,
     *,
     ttl: int,
-) -> AsyncBackend:
-    """Get an async backend instance.
+) -> Backend:
+    """Get a backend instance (async).
 
     Args:
         backend_type: 'memory', 'file', or 'redis'. Uses config default if None.
@@ -238,7 +192,63 @@ async def get_async_backend(
         cfg = get_config(package)
         backend_type = cfg.backend
 
-    return await async_manager.get_backend(package, backend_type, ttl)
+    return await manager.aget_backend(package, backend_type, ttl)
+
+
+def _validate_entry(
+    value: Any,
+    created_at: float | None,
+    validate: Callable[[CacheEntry], bool] | None,
+) -> bool:
+    """Validate a cached entry using the validate callback.
+    """
+    if validate is None or created_at is None:
+        return True
+
+    entry = CacheEntry(
+        value=value,
+        created_at=created_at,
+        age=time.time() - created_at,
+    )
+    return validate(entry)
+
+
+def _attach_helpers(
+    wrapper: Callable[..., Any],
+    key_generator: Callable[..., str],
+    resolved_package: str | None,
+    resolved_backend: str,
+    ttl: int,
+    is_async: bool,
+) -> None:
+    """Attach .invalidate() and .refresh() methods to wrapper.
+    """
+    if is_async:
+        async def invalidate(**kwargs: Any) -> None:
+            backend = await manager.aget_backend(resolved_package, resolved_backend, ttl)
+            cfg = get_config(resolved_package)
+            cache_key = mangle_key(key_generator(**kwargs), cfg.key_prefix, ttl)
+            await backend.adelete(cache_key)
+
+        async def refresh(**kwargs: Any) -> Any:
+            await invalidate(**kwargs)
+            return await wrapper(**kwargs)
+
+        wrapper.invalidate = invalidate  # type: ignore
+        wrapper.refresh = refresh  # type: ignore
+    else:
+        def invalidate(**kwargs: Any) -> None:
+            backend = manager.get_backend(resolved_package, resolved_backend, ttl)
+            cfg = get_config(resolved_package)
+            cache_key = mangle_key(key_generator(**kwargs), cfg.key_prefix, ttl)
+            backend.delete(cache_key)
+
+        def refresh(**kwargs: Any) -> Any:
+            invalidate(**kwargs)
+            return wrapper(**kwargs)
+
+        wrapper.invalidate = invalidate  # type: ignore
+        wrapper.refresh = refresh  # type: ignore
 
 
 def cache(
@@ -250,7 +260,10 @@ def cache(
     validate: Callable[[CacheEntry], bool] | None = None,
     package: str | None = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    """Cache decorator with configurable backend and behavior.
+    """Universal cache decorator for sync and async functions.
+
+    Automatically detects async functions and uses appropriate code path.
+    Includes dogpile prevention using per-key mutexes.
 
     Args:
         ttl: Time-to-live in seconds (default: 300)
@@ -272,6 +285,10 @@ def cache(
         def get_user(user_id: int) -> dict:
             return fetch_user(user_id)
 
+        @cache(ttl=300, tag='users')
+        async def get_user_async(user_id: int) -> dict:
+            return await fetch_user(user_id)
+
         # Normal call
         user = get_user(123)
 
@@ -280,6 +297,12 @@ def cache(
 
         # Force refresh
         user = get_user(123, _overwrite_cache=True)
+
+        # Invalidate specific entry
+        get_user.invalidate(user_id=123)
+
+        # Refresh specific entry
+        user = get_user.refresh(user_id=123)
     """
     resolved_package = package if package is not None else _get_caller_package()
 
@@ -291,6 +314,7 @@ def cache(
 
     def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
         key_generator = make_key_generator(fn, tag, exclude)
+        is_async = asyncio.iscoroutinefunction(fn)
 
         meta = CacheMeta(
             ttl=ttl,
@@ -303,174 +327,129 @@ def cache(
             key_generator=key_generator,
         )
 
-        @wraps(fn)
-        def wrapper(*args: Any, **kwargs: Any) -> Any:
-            skip_cache = kwargs.pop('_skip_cache', False)
-            overwrite_cache = kwargs.pop('_overwrite_cache', False)
+        if is_async:
+            @wraps(fn)
+            async def async_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 fn(*args, **kwargs)
+                if is_disabled() or skip_cache:
+                    return await fn(*args, **kwargs)
 
-            backend_instance = manager.get_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 = 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:
-                            manager.record_hit(wrapper)
-                            return value
-                    else:
-                        manager.record_hit(wrapper)
-                        return value
-
-            manager.record_miss(wrapper)
-            result = fn(*args, **kwargs)
-
-            should_cache = cache_if is None or cache_if(result)
-
-            if should_cache:
-                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
+                backend_inst = await manager.aget_backend(
+                    resolved_package,
+                    resolved_backend,
+                    ttl,
+                )
+                cfg = get_config(resolved_package)
 
-    return decorator
+                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_inst.aget_with_metadata(cache_key)
 
-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.
+                    if value is not NO_VALUE and _validate_entry(value, created_at, validate):
+                        manager.record_hit(async_wrapper)
+                        return value
 
-    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
+                mutex = backend_inst.get_async_mutex(cache_key)
+                acquired = await mutex.acquire(timeout=cfg.lock_timeout)
+                try:
+                    if not overwrite_cache:
+                        value, created_at = await backend_inst.aget_with_metadata(cache_key)
+                        if value is not NO_VALUE and _validate_entry(value, created_at, validate):
+                            manager.record_hit(async_wrapper)
+                            return value
 
-    Example:
-        @async_cache(ttl=300, tag='users')
-        async def get_user(user_id: int) -> dict:
-            return await fetch_user(user_id)
+                    manager.record_miss(async_wrapper)
+                    result = await fn(*args, **kwargs)
 
-        # Normal call
-        user = await get_user(123)
+                    if cache_if is None or cache_if(result):
+                        await backend_inst.aset(cache_key, result, ttl)
+                        logger.debug(f'Cached {fn.__name__} with key {cache_key}')
 
-        # Skip cache
-        user = await get_user(123, _skip_cache=True)
+                    return result
+                finally:
+                    if acquired:
+                        await mutex.release()
 
-        # Force refresh
-        user = await get_user(123, _overwrite_cache=True)
-    """
-    resolved_package = package if package is not None else _get_caller_package()
+            async_wrapper._cache_meta = meta  # type: ignore
+            async_wrapper._cache_key_generator = key_generator  # type: ignore
+            _attach_helpers(async_wrapper, key_generator, resolved_package, resolved_backend, ttl, is_async=True)
+            return async_wrapper
 
-    if backend is None:
-        cfg = get_config(resolved_package)
-        resolved_backend = cfg.backend
-    else:
-        resolved_backend = backend
+        else:
+            @wraps(fn)
+            def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+                skip_cache = kwargs.pop('_skip_cache', False)
+                overwrite_cache = kwargs.pop('_overwrite_cache', False)
 
-    def decorator(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
-        key_generator = make_key_generator(fn, tag, exclude)
+                if is_disabled() or skip_cache:
+                    return fn(*args, **kwargs)
 
-        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,
-        )
+                backend_inst = manager.get_backend(resolved_package, resolved_backend, ttl)
+                cfg = get_config(resolved_package)
 
-        @wraps(fn)
-        async def wrapper(*args: Any, **kwargs: Any) -> Any:
-            skip_cache = kwargs.pop('_skip_cache', False)
-            overwrite_cache = kwargs.pop('_overwrite_cache', False)
+                base_key = key_generator(*args, **kwargs)
+                cache_key = mangle_key(base_key, cfg.key_prefix, ttl)
 
-            if is_disabled() or skip_cache:
-                return await fn(*args, **kwargs)
+                if not overwrite_cache:
+                    value, created_at = backend_inst.get_with_metadata(cache_key)
 
-            backend_instance = await async_manager.get_backend(
-                resolved_package,
-                resolved_backend,
-                ttl,
-            )
-            cfg = get_config(resolved_package)
+                    if value is not NO_VALUE and _validate_entry(value, created_at, validate):
+                        manager.record_hit(sync_wrapper)
+                        return value
 
-            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 async_manager.record_hit(wrapper)
+                mutex = backend_inst.get_mutex(cache_key)
+                acquired = mutex.acquire(timeout=cfg.lock_timeout)
+                try:
+                    if not overwrite_cache:
+                        value, created_at = backend_inst.get_with_metadata(cache_key)
+                        if value is not NO_VALUE and _validate_entry(value, created_at, validate):
+                            manager.record_hit(sync_wrapper)
                             return value
-                    else:
-                        await async_manager.record_hit(wrapper)
-                        return value
 
-            await async_manager.record_miss(wrapper)
-            result = await fn(*args, **kwargs)
+                    manager.record_miss(sync_wrapper)
+                    result = fn(*args, **kwargs)
 
-            should_cache = cache_if is None or cache_if(result)
+                    if cache_if is None or cache_if(result):
+                        backend_inst.set(cache_key, result, ttl)
+                        logger.debug(f'Cached {fn.__name__} with key {cache_key}')
 
-            if should_cache:
-                await backend_instance.set(cache_key, result, ttl)
-                logger.debug(f'Cached {fn.__name__} with key {cache_key}')
+                    return result
+                finally:
+                    if acquired:
+                        mutex.release()
 
-            return result
+            sync_wrapper._cache_meta = meta  # type: ignore
+            sync_wrapper._cache_key_generator = key_generator  # type: ignore
+            _attach_helpers(sync_wrapper, key_generator, resolved_package, resolved_backend, ttl, is_async=False)
+            return sync_wrapper
 
-        wrapper._cache_meta = meta  # type: ignore
-        wrapper._cache_key_generator = key_generator  # type: ignore
+    return decorator
 
-        return wrapper
 
-    return decorator
+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]]]:
+    """Deprecated: Use @cache instead (auto-detects async).
+    """
+    return cache(
+        ttl=ttl,
+        backend=backend,
+        tag=tag,
+        exclude=exclude,
+        cache_if=cache_if,
+        validate=validate,
+        package=package,
+    )
 
 
 def get_cache_info(fn: Callable[..., Any]) -> CacheInfo:
@@ -503,24 +482,24 @@ 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
+        fn: A function decorated with @cache
 
     Returns
         CacheInfo with hits, misses, and currsize
     """
-    hits, misses = await async_manager.get_stats(fn)
+    hits, misses = manager.get_stats(fn)
 
     meta = getattr(fn, '_cache_meta', None)
     if meta is None:
         return CacheInfo(hits=hits, misses=misses, currsize=0)
 
-    backend_instance = await async_manager.get_backend(meta.package, meta.backend, meta.ttl)
+    backend_instance = await manager.aget_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)
+    currsize = await backend_instance.acount(pattern)
 
     return CacheInfo(hits=hits, misses=misses, currsize=currsize)
 
@@ -534,4 +513,7 @@ def clear_backends(package: str | None = None) -> None:
 async def clear_async_backends(package: str | None = None) -> None:
     """Clear all async backend instances for a package. Primarily for testing.
     """
-    await async_manager.clear(package)
+    await manager.aclear(package)
+
+
+get_async_backend = aget_backend