cachu 0.1.3__py3-none-any.whl → 0.2.0__py3-none-any.whl

cachu/__init__.py

@@ -1,7 +1,13 @@
 """Flexible caching library with support for memory, file, and Redis backends.
 """
-__version__ = '0.1.3'
+__version__ = '0.2.0'
 
+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.redis import get_redis_client
 from .config import configure, disable, enable, get_all_configs, get_config
 from .config import is_disabled
@@ -24,4 +30,15 @@ __all__ = [
     'cache_info',
     'get_backend',
     'get_redis_client',
+    'Backend',
+    'AsyncBackend',
+    'async_cache',
+    'async_cache_get',
+    'async_cache_set',
+    'async_cache_delete',
+    'async_cache_clear',
+    'async_cache_info',
+    'get_async_backend',
+    'get_async_cache_info',
+    'clear_async_backends',
 ]

cachu/async_decorator.py

@@ -0,0 +1,261 @@
+"""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 = 300,
+) -> 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]

cachu/async_operations.py

@@ -0,0 +1,178 @@
+"""Async cache CRUD operations.
+"""
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from .backends import NO_VALUE
+from .config import _get_caller_package, get_config
+from .async_decorator import _get_async_backend, get_async_cache_info
+from .async_decorator import _async_backends, _async_backends_lock
+from .keys import mangle_key
+from .types import CacheInfo, CacheMeta
+
+logger = logging.getLogger(__name__)
+
+_MISSING = object()
+
+
+def _get_meta(fn: Callable[..., Any]) -> 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 @async_cache')
+    return meta
+
+
+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 @async_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 @async_cache
+    """
+    meta = _get_meta(fn)
+    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 _get_async_backend(meta.package, meta.backend, meta.ttl)
+    value = await backend.get(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 @async_cache
+        value: The value to cache
+        **kwargs: Function arguments to build the cache key
+
+    Raises
+        ValueError: If function is not decorated with @async_cache
+    """
+    meta = _get_meta(fn)
+    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 _get_async_backend(meta.package, meta.backend, meta.ttl)
+    await backend.set(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 @async_cache
+        **kwargs: Function arguments to build the cache key
+
+    Raises
+        ValueError: If function is not decorated with @async_cache
+    """
+    meta = _get_meta(fn)
+    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 _get_async_backend(meta.package, meta.backend, meta.ttl)
+    await backend.delete(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']
+
+    if tag:
+        from .keys import _normalize_tag
+        pattern = f'*|{_normalize_tag(tag)}|*'
+    else:
+        pattern = None
+
+    total_cleared = 0
+
+    if backend is not None and ttl is not None:
+        backend_instance = await _get_async_backend(package, backend, ttl)
+        cleared = await backend_instance.clear(pattern)
+        if cleared > 0:
+            total_cleared += cleared
+            logger.debug(f'Cleared {cleared} entries from {backend} backend (ttl={ttl})')
+    else:
+        async with _async_backends_lock:
+            for (pkg, btype, bttl), backend_instance in list(_async_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.clear(pattern)
+                if cleared > 0:
+                    total_cleared += cleared
+                    logger.debug(f'Cleared {cleared} entries from {btype} backend (ttl={bttl})')
+
+    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 @async_cache
+
+    Returns
+        CacheInfo with hits, misses, and currsize
+
+    Raises
+        ValueError: If function is not decorated with @async_cache
+    """
+    _get_meta(fn)
+    return await get_async_cache_info(fn)

cachu/backends/__init__.py

@@ -1,8 +1,8 @@
 """Cache backend implementations.
 """
 from abc import ABC, abstractmethod
-from typing import Any
 from collections.abc import Iterator
+from typing import Any
 
 NO_VALUE = object()
 
@@ -45,3 +45,8 @@ class Backend(ABC):
     def count(self, pattern: str | None = None) -> int:
         """Count keys matching pattern.
         """
+
+
+from .async_base import AsyncBackend
+
+__all__ = ['Backend', 'AsyncBackend', 'NO_VALUE']

cachu/backends/async_base.py

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

cachu/backends/async_memory.py

@@ -0,0 +1,111 @@
+"""Async memory cache backend implementation.
+"""
+import asyncio
+import fnmatch
+import pickle
+import time
+from collections.abc import AsyncIterator
+from typing import Any
+
+from . import NO_VALUE
+from .async_base import AsyncBackend
+
+
+class AsyncMemoryBackend(AsyncBackend):
+    """Async in-memory cache backend using asyncio.Lock.
+    """
+
+    def __init__(self) -> None:
+        self._cache: dict[str, tuple[bytes, float, float]] = {}
+        self._lock = asyncio.Lock()
+
+    async def get(self, key: str) -> Any:
+        """Get value by key. Returns NO_VALUE if not found or expired.
+        """
+        async with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return NO_VALUE
+
+            pickled_value, created_at, expires_at = entry
+            if time.time() > expires_at:
+                del self._cache[key]
+                return NO_VALUE
+
+            return pickle.loads(pickled_value)
+
+    async def get_with_metadata(self, key: str) -> tuple[Any, float | None]:
+        """Get value and creation timestamp. Returns (NO_VALUE, None) if not found.
+        """
+        async with self._lock:
+            entry = self._cache.get(key)
+            if entry is None:
+                return NO_VALUE, None
+
+            pickled_value, created_at, expires_at = entry
+            if time.time() > expires_at:
+                del self._cache[key]
+                return NO_VALUE, None
+
+            return pickle.loads(pickled_value), created_at
+
+    async def set(self, key: str, value: Any, ttl: int) -> None:
+        """Set value with TTL in seconds.
+        """
+        now = time.time()
+        pickled_value = pickle.dumps(value)
+        async with self._lock:
+            self._cache[key] = (pickled_value, now, now + ttl)
+
+    async def delete(self, key: str) -> None:
+        """Delete value by key.
+        """
+        async with self._lock:
+            self._cache.pop(key, None)
+
+    async def clear(self, pattern: str | None = None) -> int:
+        """Clear entries matching pattern. Returns count of cleared entries.
+        """
+        async 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)
+
+    async def keys(self, pattern: str | None = None) -> AsyncIterator[str]:
+        """Iterate over keys matching pattern.
+        """
+        now = time.time()
+        async with self._lock:
+            all_keys = list(self._cache.keys())
+
+        for key in all_keys:
+            async with self._lock:
+                entry = self._cache.get(key)
+                if entry is None:
+                    continue
+                _, _, expires_at = entry
+                if now > expires_at:
+                    del self._cache[key]
+                    continue
+
+            if pattern is None or fnmatch.fnmatch(key, pattern):
+                yield key
+
+    async def count(self, pattern: str | None = None) -> int:
+        """Count keys matching pattern.
+        """
+        count = 0
+        async for _ in self.keys(pattern):
+            count += 1
+        return count
+
+    async def close(self) -> None:
+        """Close the backend (no-op for memory backend).
+        """
+        pass