cachify 0.1.0__py3-none-any.whl

cachify/redis/lock.py

@@ -0,0 +1,232 @@
+import asyncio
+import contextlib
+import threading
+import time
+from contextlib import asynccontextmanager, contextmanager
+from dataclasses import dataclass, field
+from typing import AsyncIterator, Iterator, Literal, overload
+
+from redis.lock import Lock
+from redis.asyncio.lock import Lock as AsyncLock
+
+from cachify.config import logger
+from cachify.redis.config import get_redis_config
+
+HEARTBEAT_INTERVAL = 1
+
+
+@dataclass
+class _ActiveLockBase:
+    """Base class for active lock tracking with shared logic."""
+
+    timeout: float
+    last_extended_at: float = field(default_factory=time.monotonic)
+
+    def should_extend(self) -> bool:
+        elapsed = time.monotonic() - self.last_extended_at
+        return elapsed >= self.timeout / 2
+
+    def mark_extended(self):
+        self.last_extended_at = time.monotonic()
+
+
+@dataclass
+class _ActiveAsyncLock(_ActiveLockBase):
+    """Tracks an async lock that needs heartbeat extension."""
+
+    lock: AsyncLock = field(kw_only=True)
+
+    async def extend(self) -> bool:
+        try:
+            await self.lock.extend(self.timeout)
+            self.mark_extended()
+            return True
+        except Exception:
+            return False
+
+
+@dataclass
+class _ActiveSyncLock(_ActiveLockBase):
+    """Tracks a sync lock that needs heartbeat extension."""
+
+    lock: Lock = field(kw_only=True)
+
+    def extend(self) -> bool:
+        try:
+            self.lock.extend(self.timeout)
+            self.mark_extended()
+            return True
+        except Exception:
+            return False
+
+
+class _AsyncHeartbeatManager:
+    """Manages heartbeat extensions for all async Redis locks."""
+
+    _locks: dict[str, _ActiveAsyncLock] = {}
+    _task: asyncio.Task | None = None
+
+    @classmethod
+    def register(cls, key: str, lock: AsyncLock, timeout: float):
+        cls._locks[key] = _ActiveAsyncLock(timeout=timeout, lock=lock)
+        cls._ensure_worker_running()
+
+    @classmethod
+    def unregister(cls, key: str):
+        cls._locks.pop(key, None)
+
+    @classmethod
+    def reset(cls):
+        """Cancel worker and clear state. Used for testing cleanup."""
+        cls._locks.clear()
+        if cls._task is not None and not cls._task.done():
+            with contextlib.suppress(RuntimeError):
+                cls._task.cancel()
+        cls._task = None
+
+    @classmethod
+    def _ensure_worker_running(cls):
+        if cls._task is None or cls._task.done():
+            cls._task = asyncio.create_task(cls._worker())
+
+    @classmethod
+    async def _worker(cls):
+        while True:
+            await asyncio.sleep(HEARTBEAT_INTERVAL)
+
+            if not cls._locks:
+                cls._task = None
+                return
+
+            for key, active in list(cls._locks.items()):
+                if not active.should_extend():
+                    continue
+                if not await active.extend():
+                    logger.warning(f"Failed to extend lock, it may have expired", extra={"lock_key": key})
+
+
+class _SyncHeartbeatManager:
+    """Manages heartbeat extensions for all sync Redis locks."""
+
+    _locks: dict[str, _ActiveSyncLock] = {}
+    _thread: threading.Thread | None = None
+    _state_lock: threading.Lock = threading.Lock()
+
+    @classmethod
+    def register(cls, key: str, lock: Lock, timeout: float):
+        with cls._state_lock:
+            cls._locks[key] = _ActiveSyncLock(timeout=timeout, lock=lock)
+            cls._ensure_worker_running()
+
+    @classmethod
+    def unregister(cls, key: str):
+        cls._locks.pop(key, None)
+
+    @classmethod
+    def reset(cls):
+        """Clear state. Used for testing cleanup. Thread exits on next iteration when _locks is empty."""
+        cls._locks.clear()
+        cls._thread = None
+
+    @classmethod
+    def _ensure_worker_running(cls):
+        if cls._thread is None or not cls._thread.is_alive():
+            cls._thread = threading.Thread(target=cls._worker, daemon=True)
+            cls._thread.start()
+
+    @classmethod
+    def _worker(cls):
+        while True:
+            time.sleep(HEARTBEAT_INTERVAL)
+
+            with cls._state_lock:
+                if not cls._locks:
+                    cls._thread = None
+                    return
+                locks_snapshot = list(cls._locks.items())
+
+            for key, active in locks_snapshot:
+                if not active.should_extend():
+                    continue
+                if not active.extend():
+                    logger.warning(f"Failed to extend lock, it may have expired", extra={"lock_key": key})
+
+
+class RedisLockManager:
+    """Distributed lock manager using Redis locks."""
+
+    @classmethod
+    def _make_lock_key(cls, cache_key: str) -> str:
+        """Create a Redis lock key."""
+        config = get_redis_config()
+        return f"{config.key_prefix}:lock:{cache_key}"
+
+    @overload
+    @classmethod
+    def _get_lock(cls, cache_key: str, is_async: Literal[True]) -> AsyncLock: ...
+
+    @overload
+    @classmethod
+    def _get_lock(cls, cache_key: str, is_async: Literal[False]) -> Lock: ...
+
+    @classmethod
+    def _get_lock(cls, cache_key: str, is_async: bool) -> Lock | AsyncLock:
+        """Get client and create lock."""
+        config = get_redis_config()
+        client = config.get_client(is_async)
+        lock_key = cls._make_lock_key(cache_key)
+        return client.lock(
+            lock_key,
+            timeout=config.lock_timeout,
+            blocking=True,
+            blocking_timeout=None,
+            thread_local=False,  # Required for heartbeat extension from background thread
+        )
+
+    @classmethod
+    @contextmanager
+    def sync_lock(cls, cache_key: str) -> Iterator[None]:
+        """
+        Acquire a distributed lock for sync operations.
+
+        Uses Redis lock with blocking behavior - waits for lock holder to finish.
+        Lock is automatically extended via heartbeat to prevent expiration during long operations.
+        """
+        config = get_redis_config()
+        lock = cls._get_lock(cache_key, is_async=False)
+        acquired = False
+
+        try:
+            acquired = lock.acquire()
+            if acquired:
+                _SyncHeartbeatManager.register(lock.name, lock, config.lock_timeout)
+                yield
+        finally:
+            if acquired:
+                _SyncHeartbeatManager.unregister(lock.name)
+                with contextlib.suppress(Exception):
+                    lock.release()
+
+    @classmethod
+    @asynccontextmanager
+    async def async_lock(cls, cache_key: str) -> AsyncIterator[None]:
+        """
+        Acquire a distributed lock for async operations.
+
+        Uses Redis lock with blocking behavior - waits for lock holder to finish.
+        Lock is automatically extended via heartbeat to prevent expiration during long operations.
+        """
+        config = get_redis_config()
+        lock = cls._get_lock(cache_key, is_async=True)
+        acquired = False
+
+        try:
+            acquired = await lock.acquire()
+            if acquired:
+                _AsyncHeartbeatManager.register(lock.name, lock, config.lock_timeout)  # type: ignore
+                yield
+        finally:
+            if acquired:
+                _AsyncHeartbeatManager.unregister(lock.name)  # type: ignore
+                with contextlib.suppress(Exception):
+                    await lock.release()

cachify/redis_cache.py

@@ -0,0 +1,27 @@
+from typing import Callable
+
+from cachify.cache import base_cache
+from cachify.redis.lock import RedisLockManager
+from cachify.storage.redis_storage import RedisStorage
+from cachify.types import CacheConfig, CacheKeyFunction, F, Number
+
+_REDIS_CONFIG = CacheConfig(
+    storage=RedisStorage,
+    sync_lock=RedisLockManager.sync_lock,
+    async_lock=RedisLockManager.async_lock,
+)
+
+
+def redis_cache(
+    ttl: Number = 300,
+    never_die: bool = False,
+    cache_key_func: CacheKeyFunction | None = None,
+    ignore_fields: tuple[str, ...] = (),
+) -> Callable[[F], F]:
+    """
+    Redis cache decorator. See `base_cache` for full documentation.
+
+    Requires setup_redis_config() to be called before use.
+    Uses Redis for distributed caching across multiple processes/machines.
+    """
+    return base_cache(ttl, never_die, cache_key_func, ignore_fields, _REDIS_CONFIG)

cachify/storage/__init__.py

@@ -0,0 +1,9 @@
+from cachify.storage.memory_storage import MemoryCacheEntry, MemoryStorage
+from cachify.storage.redis_storage import RedisCacheEntry, RedisStorage
+
+__all__ = [
+    "MemoryCacheEntry",
+    "MemoryStorage",
+    "RedisCacheEntry",
+    "RedisStorage",
+]

cachify/storage/memory_storage.py

@@ -0,0 +1,52 @@
+import contextlib
+import time
+from typing import Any
+
+from cachify.types import CacheEntry, Number
+
+_CACHE_CLEAR_INTERVAL_SECONDS: int = 10
+
+
+class MemoryCacheEntry(CacheEntry): ...
+
+
+class MemoryStorage:
+    """In-memory cache storage implementing CacheStorage protocol."""
+
+    _CACHE: dict[str, MemoryCacheEntry] = {}
+
+    @classmethod
+    def clear_expired_cached_items(cls):
+        """Clear expired cached items from the cache."""
+        while True:
+            with contextlib.suppress(Exception):
+                for key, entry in list(cls._CACHE.items()):
+                    if entry.is_expired():
+                        del cls._CACHE[key]
+
+            time.sleep(_CACHE_CLEAR_INTERVAL_SECONDS)
+
+    @classmethod
+    def set(cls, cache_key: str, result: Any, ttl: Number | None):
+        cls._CACHE[cache_key] = MemoryCacheEntry(result, ttl)
+
+    @classmethod
+    def get(cls, cache_key: str, skip_cache: bool) -> MemoryCacheEntry | None:
+        if skip_cache:
+            return None
+        if entry := cls._CACHE.get(cache_key):
+            if not entry.is_expired():
+                return entry
+        return None
+
+    @classmethod
+    async def aset(cls, cache_key: str, result: Any, ttl: Number | None):
+        cls.set(cache_key, result, ttl)
+
+    @classmethod
+    async def aget(cls, cache_key: str, skip_cache: bool) -> MemoryCacheEntry | None:
+        return cls.get(cache_key, skip_cache)
+
+    @classmethod
+    def clear(cls):
+        cls._CACHE.clear()

cachify/storage/redis_storage.py

@@ -0,0 +1,138 @@
+import pickle
+import time
+from typing import Any, overload
+
+from cachify.redis.config import get_redis_config
+from cachify.config import logger
+from cachify.types import CacheEntry, Number
+
+
+class RedisCacheEntry(CacheEntry):
+    @classmethod
+    def time(cls) -> float:
+        return time.time()
+
+
+class RedisStorage:
+    """Redis cache storage implementing CacheStorage protocol."""
+
+    @classmethod
+    def _make_key(cls, cache_key: str) -> str:
+        """Create a Redis key from cache_key."""
+        config = get_redis_config()
+        return f"{config.key_prefix}:{cache_key}"
+
+    @classmethod
+    def _serialize(cls, entry: RedisCacheEntry) -> bytes:
+        """Serialize a cache entry to bytes."""
+        try:
+            return pickle.dumps(entry, protocol=pickle.HIGHEST_PROTOCOL)
+        except (pickle.PicklingError, TypeError, AttributeError) as exc:
+            raise TypeError(
+                f"Failed to serialize cache entry. Object of type {type(entry.result).__name__} "
+                f"cannot be pickled. Ensure the cached result is serializable."
+            ) from exc
+
+    @classmethod
+    def _deserialize(cls, data: bytes) -> RedisCacheEntry:
+        """Deserialize bytes to a cache entry."""
+        return pickle.loads(data)
+
+    @overload
+    @classmethod
+    def _prepare_set(cls, cache_key: str, result: Any, ttl: None) -> tuple[str, bytes, None]: ...
+
+    @overload
+    @classmethod
+    def _prepare_set(cls, cache_key: str, result: Any, ttl: Number) -> tuple[str, bytes, int]: ...
+
+    @classmethod
+    def _prepare_set(cls, cache_key: str, result: Any, ttl: Number | None) -> tuple[str, bytes, int | None]:
+        """Prepare key, data, and expiry in milliseconds for set operations."""
+        key = cls._make_key(cache_key)
+        data = cls._serialize(RedisCacheEntry(result, ttl))
+        if ttl is None:
+            return key, data, None
+
+        return key, data, int(ttl * 1000)
+
+    @classmethod
+    def _handle_error(cls, exc: Exception, operation: str, cache_key: str):
+        """Handle Redis errors based on config."""
+        config = get_redis_config()
+        if config.on_error == "raise":
+            raise
+
+        logger.debug(f"Redis operation error: {exc}", extra={"operation": operation, "cache_key": cache_key})
+
+    @classmethod
+    def _handle_get_result(cls, data: bytes | None) -> RedisCacheEntry | None:
+        """Process get result and return entry if valid."""
+        if data is None:
+            return None
+
+        entry = cls._deserialize(data)
+        if entry.is_expired():
+            return None
+
+        return entry
+
+    @classmethod
+    def set(cls, cache_key: str, result: Any, ttl: Number | None):
+        """Store a result in Redis cache."""
+        config = get_redis_config()
+        client = config.get_client(is_async=False)
+        key, data, expiry_ms = cls._prepare_set(cache_key, result, ttl)
+        try:
+            if expiry_ms is None:
+                client.set(key, data)
+                return
+
+            client.psetex(key, expiry_ms, data)
+        except Exception as exc:
+            cls._handle_error(exc, "set", cache_key)
+
+    @classmethod
+    def get(cls, cache_key: str, skip_cache: bool) -> RedisCacheEntry | None:
+        """Retrieve a cache entry from Redis."""
+        if skip_cache:
+            return None
+
+        config = get_redis_config()
+        client = config.get_client(is_async=False)
+        key = cls._make_key(cache_key)
+        try:
+            return cls._handle_get_result(client.get(key))  # type: ignore[arg-type]
+        except Exception as exc:
+            cls._handle_error(exc, "get", cache_key)
+            return None
+
+    @classmethod
+    async def aset(cls, cache_key: str, result: Any, ttl: Number | None):
+        """Store a result in Redis cache (async)."""
+        config = get_redis_config()
+        client = config.get_client(is_async=True)
+        key, data, expiry_ms = cls._prepare_set(cache_key, result, ttl)
+        try:
+            if expiry_ms is None:
+                await client.set(key, data)
+                return
+
+            await client.psetex(key, expiry_ms, data)
+        except Exception as exc:
+            cls._handle_error(exc, "aset", cache_key)
+
+    @classmethod
+    async def aget(cls, cache_key: str, skip_cache: bool) -> RedisCacheEntry | None:
+        """Retrieve a cache entry from Redis (async)."""
+        if skip_cache:
+            return None
+
+        config = get_redis_config()
+        client = config.get_client(is_async=True)
+        key = cls._make_key(cache_key)
+        try:
+            return cls._handle_get_result(await client.get(key))  # type: ignore[arg-type]
+        except Exception as exc:
+            cls._handle_error(exc, "aget", cache_key)
+            return None

cachify/types/__init__.py

@@ -0,0 +1,95 @@
+import time
+from dataclasses import dataclass, field
+from typing import Any, AsyncContextManager, Callable, ContextManager, Hashable, Protocol, TypeAlias, TypedDict, TypeVar
+
+Number: TypeAlias = int | float
+CacheKeyFunction: TypeAlias = Callable[[tuple, dict], Hashable]
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+@dataclass
+class CacheEntry:
+    """Base cache entry with TTL and expiration tracking."""
+
+    result: Any
+    ttl: float | None
+
+    cached_at: float = field(init=False)
+    expires_at: float = field(init=False)
+
+    @classmethod
+    def time(cls) -> float:
+        return time.monotonic()
+
+    def __post_init__(self):
+        self.cached_at = self.time()
+        self.expires_at = 0 if self.ttl is None else self.cached_at + self.ttl
+
+    def is_expired(self) -> bool:
+        if self.ttl is None:
+            return False
+
+        return self.time() > self.expires_at
+
+
+@dataclass(frozen=True, slots=True)
+class CacheConfig:
+    """Configuration for cache, grouping storage, lock, and never_die registration."""
+
+    storage: "CacheStorage"
+    sync_lock: Callable[[str], ContextManager]
+    async_lock: Callable[[str], AsyncContextManager]
+
+
+class CacheEntryProtocol(Protocol):
+    """Protocol for cache entry objects."""
+
+    result: Any
+
+    def is_expired(self) -> bool: ...
+
+
+class CacheStorage(Protocol):
+    """Protocol defining the interface for cache storage."""
+
+    def get(self, cache_key: str, skip_cache: bool) -> CacheEntryProtocol | None:
+        """Retrieve a cache entry. Returns None if not found, expired, or skip_cache is True."""
+        ...
+
+    def set(self, cache_key: str, result: Any, ttl: Number | None):
+        """Store a result in the cache with optional TTL."""
+        ...
+
+    async def aget(self, cache_key: str, skip_cache: bool) -> CacheEntryProtocol | None:
+        """Async version of get."""
+        ...
+
+    async def aset(self, cache_key: str, result: Any, ttl: Number | None):
+        """Async version of set."""
+        ...
+
+
+class CacheKwargs(TypedDict, total=False):
+    """
+    ### Description
+    This type can be used in conjuction with `Unpack` to provide static type
+    checking for the parameters added by the `@cache()` decorator.
+
+    This type is completely optional and `skip_cache` will work regardless
+    of what static type checkers complain about.
+
+    ### Example
+    ```
+    @cache()
+    def function_with_cache(**_: Unpack[CacheKwargs]): ...
+
+    # pylance/pyright should not complain
+    function_with_cache(skip_cache=True)
+    ```
+
+    ### Notes
+    Prior to Python 3.11, `Unpack` is only available with typing_extensions
+    """
+
+    skip_cache: bool

cachify/utils/arguments.py

@@ -0,0 +1,65 @@
+import hashlib
+import inspect
+import pickle
+from collections.abc import Callable, Generator
+from inspect import Signature
+from typing import Any
+
+from cachify.types import CacheKeyFunction
+from cachify.utils.functions import get_function_id
+
+
+def _cache_key_fingerprint(value: object) -> str:
+    payload = pickle.dumps(value, protocol=pickle.HIGHEST_PROTOCOL)
+    return hashlib.blake2b(payload, digest_size=16).hexdigest()
+
+
+def _iter_arguments(
+    function_signature: Signature,
+    args: tuple,
+    kwargs: dict,
+    ignore_fields: tuple[str, ...],
+) -> Generator[Any, None, None]:
+    bound = function_signature.bind_partial(*args, **kwargs)
+    bound.apply_defaults()
+
+    for name, value in bound.arguments.items():
+        if name in ignore_fields:
+            continue
+
+        param = function_signature.parameters[name]
+
+        # Positional variable arguments can just be yielded like so
+        if param.kind == param.VAR_POSITIONAL:
+            yield from value
+            continue
+
+        # Keyword variable arguments need to be unpacked from .items()
+        if param.kind == param.VAR_KEYWORD:
+            yield from value.items()
+            continue
+
+        yield name, value
+
+
+def create_cache_key(
+    function: Callable[..., Any],
+    cache_key_func: CacheKeyFunction | None,
+    ignore_fields: tuple[str, ...],
+    args: tuple,
+    kwargs: dict,
+) -> str:
+    function_id = get_function_id(function)
+
+    if not cache_key_func:
+        function_signature = inspect.signature(function)
+        items = tuple(_iter_arguments(function_signature, args, kwargs, ignore_fields))
+        return f"{function_id}:{_cache_key_fingerprint(items)}"
+
+    cache_key = cache_key_func(args, kwargs)
+    try:
+        return f"{function_id}:{_cache_key_fingerprint(cache_key)}"
+    except TypeError as exc:
+        raise ValueError(
+            "Cache key function must return a hashable cache key - be careful with mutable types (list, dict, set) and non built-in types"
+        ) from exc

cachify/utils/decorator_factory.py

@@ -0,0 +1,44 @@
+import inspect
+from typing import Callable
+
+from cachify._async import async_decorator
+from cachify._sync import sync_decorator
+from cachify.types import CacheConfig, CacheKeyFunction, F, Number
+
+
+def create_cache_decorator(
+    ttl: Number,
+    never_die: bool,
+    cache_key_func: CacheKeyFunction | None,
+    ignore_fields: tuple[str, ...],
+    config: CacheConfig,
+) -> Callable[[F], F]:
+    """
+    Create a cache decorator with the given configuration.
+
+    This is a shared factory used by both memory_cache and redis_cache
+    to avoid code duplication.
+    """
+    if cache_key_func and ignore_fields:
+        raise ValueError("Either cache_key_func or ignore_fields can be provided, but not both")
+
+    def decorator(function: F) -> F:
+        if inspect.iscoroutinefunction(function):
+            return async_decorator(
+                function=function,
+                ttl=ttl,
+                never_die=never_die,
+                cache_key_func=cache_key_func,
+                ignore_fields=ignore_fields,
+                config=config,
+            )
+        return sync_decorator(
+            function=function,
+            ttl=ttl,
+            never_die=never_die,
+            cache_key_func=cache_key_func,
+            ignore_fields=ignore_fields,
+            config=config,
+        )
+
+    return decorator

cachify/utils/functions.py

@@ -0,0 +1,10 @@
+import functools
+from typing import Any, Callable
+
+
+@functools.cache
+def get_function_id(function: Callable[..., Any]) -> str:
+    """
+    Returns the unique identifier for the function, which is a combination of its module and qualified name.
+    """
+    return f"{function.__module__}.{function.__qualname__}"

cachify/utils/locks.py

@@ -0,0 +1,6 @@
+import asyncio
+import threading
+from collections import defaultdict
+
+ASYNC_LOCKS: defaultdict[str, asyncio.Lock] = defaultdict(asyncio.Lock)
+SYNC_LOCKS: defaultdict[str, threading.Lock] = defaultdict(threading.Lock)