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

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]

cachu/async_operations.py

@@ -1,178 +0,0 @@
-"""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/async_base.py

@@ -1,50 +0,0 @@
-"""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

@@ -1,111 +0,0 @@
-"""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