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

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

cachu/backends/async_redis.py

@@ -1,141 +0,0 @@
-"""Async Redis cache backend implementation using redis.asyncio.
-"""
-import pickle
-import struct
-import time
-from collections.abc import AsyncIterator
-from typing import TYPE_CHECKING, Any
-
-from . import NO_VALUE
-from .async_base import AsyncBackend
-
-if TYPE_CHECKING:
-    import redis.asyncio as aioredis
-
-
-_METADATA_FORMAT = 'd'
-_METADATA_SIZE = struct.calcsize(_METADATA_FORMAT)
-
-
-def _get_async_redis_module() -> Any:
-    """Import redis.asyncio module, raising helpful error if not installed.
-    """
-    try:
-        import redis.asyncio as aioredis
-        return aioredis
-    except ImportError as e:
-        raise RuntimeError(
-            "Async Redis support requires the 'redis' package (>=4.2.0). "
-            "Install with: pip install cachu[redis]"
-        ) from e
-
-
-async def get_async_redis_client(url: str) -> 'aioredis.Redis':
-    """Create an async Redis client from URL.
-
-    Args:
-        url: Redis URL (e.g., 'redis://localhost:6379/0')
-    """
-    aioredis = _get_async_redis_module()
-    return aioredis.from_url(url)
-
-
-class AsyncRedisBackend(AsyncBackend):
-    """Async Redis cache backend using redis.asyncio.
-    """
-
-    def __init__(self, url: str, distributed_lock: bool = False) -> None:
-        self._url = url
-        self._distributed_lock = distributed_lock
-        self._client: aioredis.Redis | None = None
-
-    async def _get_client(self) -> 'aioredis.Redis':
-        """Lazy-load async Redis client.
-        """
-        if self._client is None:
-            self._client = await get_async_redis_client(self._url)
-        return self._client
-
-    def _pack_value(self, value: Any, created_at: float) -> bytes:
-        """Pack value with creation timestamp.
-        """
-        metadata = struct.pack(_METADATA_FORMAT, created_at)
-        pickled = pickle.dumps(value)
-        return metadata + pickled
-
-    def _unpack_value(self, data: bytes) -> tuple[Any, float]:
-        """Unpack value and creation timestamp.
-        """
-        created_at = struct.unpack(_METADATA_FORMAT, data[:_METADATA_SIZE])[0]
-        value = pickle.loads(data[_METADATA_SIZE:])
-        return value, created_at
-
-    async def get(self, key: str) -> Any:
-        """Get value by key. Returns NO_VALUE if not found.
-        """
-        client = await self._get_client()
-        data = await client.get(key)
-        if data is None:
-            return NO_VALUE
-        value, _ = self._unpack_value(data)
-        return 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.
-        """
-        client = await self._get_client()
-        data = await client.get(key)
-        if data is None:
-            return NO_VALUE, None
-        value, created_at = self._unpack_value(data)
-        return value, created_at
-
-    async def set(self, key: str, value: Any, ttl: int) -> None:
-        """Set value with TTL in seconds.
-        """
-        client = await self._get_client()
-        now = time.time()
-        packed = self._pack_value(value, now)
-        await client.setex(key, ttl, packed)
-
-    async def delete(self, key: str) -> None:
-        """Delete value by key.
-        """
-        client = await self._get_client()
-        await client.delete(key)
-
-    async def clear(self, pattern: str | None = None) -> int:
-        """Clear entries matching pattern. Returns count of cleared entries.
-        """
-        client = await self._get_client()
-        if pattern is None:
-            pattern = '*'
-
-        count = 0
-        async for key in client.scan_iter(match=pattern):
-            await client.delete(key)
-            count += 1
-        return count
-
-    async def keys(self, pattern: str | None = None) -> AsyncIterator[str]:
-        """Iterate over keys matching pattern.
-        """
-        client = await self._get_client()
-        redis_pattern = pattern or '*'
-        async for key in client.scan_iter(match=redis_pattern):
-            yield key.decode() if isinstance(key, bytes) else 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 Redis connection.
-        """
-        if self._client is not None:
-            await self._client.close()
-            self._client = None