cachify 0.1.0__py3-none-any.whl

cachify/__init__.py

@@ -0,0 +1,22 @@
+from .features.never_die import clear_never_die_registry
+from .memory_cache import cache
+from .redis import DEFAULT_KEY_PREFIX, get_redis_config, reset_redis_config, setup_redis_config
+from .redis_cache import redis_cache
+from .types import CacheKwargs
+
+__version__ = "0.1.0"
+
+rcache = redis_cache
+
+__all__ = [
+    "__version__",
+    "cache",
+    "rcache",
+    "redis_cache",
+    "setup_redis_config",
+    "get_redis_config",
+    "reset_redis_config",
+    "DEFAULT_KEY_PREFIX",
+    "CacheKwargs",
+    "clear_never_die_registry",
+]

cachify/cache.py

@@ -0,0 +1,116 @@
+import functools
+import inspect
+from typing import Any, Callable, cast
+
+from cachify.features.never_die import register_never_die_function
+from cachify.types import CacheConfig, CacheKeyFunction, F, Number
+from cachify.utils.arguments import create_cache_key
+
+
+def _async_decorator(
+    function: F,
+    ttl: Number,
+    never_die: bool,
+    cache_key_func: CacheKeyFunction | None,
+    ignore_fields: tuple[str, ...],
+    config: CacheConfig,
+) -> F:
+    @functools.wraps(function)
+    async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+        skip_cache = kwargs.pop("skip_cache", False)
+        cache_key = create_cache_key(function, cache_key_func, ignore_fields, args, kwargs)
+
+        if cache_entry := await config.storage.aget(cache_key, skip_cache):
+            return cache_entry.result
+
+        async with config.async_lock(cache_key):
+            if cache_entry := await config.storage.aget(cache_key, skip_cache):
+                return cache_entry.result
+
+            result = await function(*args, **kwargs)
+            await config.storage.aset(cache_key, result, None if never_die else ttl)
+
+            if never_die:
+                register_never_die_function(function, ttl, args, kwargs, cache_key_func, ignore_fields, config)
+
+            return result
+
+    return cast(F, async_wrapper)
+
+
+def _sync_decorator(
+    function: F,
+    ttl: Number,
+    never_die: bool,
+    cache_key_func: CacheKeyFunction | None,
+    ignore_fields: tuple[str, ...],
+    config: CacheConfig,
+) -> F:
+    @functools.wraps(function)
+    def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+        skip_cache = kwargs.pop("skip_cache", False)
+        cache_key = create_cache_key(function, cache_key_func, ignore_fields, args, kwargs)
+
+        if cache_entry := config.storage.get(cache_key, skip_cache):
+            return cache_entry.result
+
+        with config.sync_lock(cache_key):
+            if cache_entry := config.storage.get(cache_key, skip_cache):
+                return cache_entry.result
+
+            result = function(*args, **kwargs)
+            config.storage.set(cache_key, result, None if never_die else ttl)
+
+            if never_die:
+                register_never_die_function(function, ttl, args, kwargs, cache_key_func, ignore_fields, config)
+
+            return result
+
+    return cast(F, sync_wrapper)
+
+
+def base_cache(
+    ttl: Number,
+    never_die: bool,
+    cache_key_func: CacheKeyFunction | None,
+    ignore_fields: tuple[str, ...],
+    config: CacheConfig,
+) -> Callable[[F], F]:
+    """
+    Base cache decorator factory used by both memory and Redis cache implementations.
+
+    Args:
+        ttl: Time to live for cached items in seconds
+        never_die: If True, the cache will never expire and will be recalculated based on the ttl
+        cache_key_func: Custom cache key function, used for more complex cache scenarios
+        ignore_fields: Tuple of strings with the function params to ignore when creating the cache key
+        config: Cache configuration specifying storage, locks, and never_die registration
+
+    Features:
+        - Works for both sync and async functions
+        - Only allows one execution at a time per function+args
+        - Makes subsequent calls wait for the first call to complete
+    """
+    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/config/__init__.py

@@ -0,0 +1,4 @@
+import logging
+
+logger = logging.getLogger("cachify")
+logger.addHandler(logging.NullHandler())

cachify/features/never_die.py

@@ -0,0 +1,219 @@
+import asyncio
+import functools
+import inspect
+import threading
+import time
+from asyncio import AbstractEventLoop
+from concurrent.futures import Future as ConcurrentFuture
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from cachify.config import logger
+from cachify.types import CacheConfig, CacheKeyFunction, Number
+from cachify.utils.arguments import create_cache_key
+
+_NEVER_DIE_THREAD: threading.Thread | None = None
+_NEVER_DIE_LOCK: threading.Lock = threading.Lock()
+_NEVER_DIE_REGISTRY: list["NeverDieCacheEntry"] = []
+_NEVER_DIE_CACHE_THREADS: dict[str, threading.Thread] = {}
+_NEVER_DIE_CACHE_FUTURES: dict[str, ConcurrentFuture] = {}
+
+_MAX_BACKOFF: int = 10
+_BACKOFF_MULTIPLIER: float = 1.25
+_REFRESH_INTERVAL_SECONDS: float = 0.1
+
+
+@dataclass
+class NeverDieCacheEntry:
+    function: Callable[..., Any]
+    ttl: Number
+    args: tuple
+    kwargs: dict
+    cache_key_func: CacheKeyFunction | None
+    ignore_fields: tuple[str, ...]
+    loop: AbstractEventLoop | None
+    config: CacheConfig
+
+    def __post_init__(self):
+        self._backoff: float = 1
+        self._expires_at: float = time.monotonic() + self.ttl
+
+    @functools.cached_property
+    def cache_key(self) -> str:
+        return create_cache_key(
+            self.function,
+            self.cache_key_func,
+            self.ignore_fields,
+            self.args,
+            self.kwargs,
+        )
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, NeverDieCacheEntry):
+            return False
+        return self.cache_key == other.cache_key
+
+    def __hash__(self) -> int:
+        return hash(self.cache_key)
+
+    def is_expired(self) -> bool:
+        return time.monotonic() > self._expires_at
+
+    def reset(self):
+        self._backoff = 1
+        self._expires_at = time.monotonic() + self.ttl
+
+    def revive(self):
+        self._backoff = min(self._backoff * _BACKOFF_MULTIPLIER, _MAX_BACKOFF)
+        self._expires_at = time.monotonic() + self.ttl * self._backoff
+
+
+def _run_sync_function_and_cache(entry: NeverDieCacheEntry):
+    """Run a function and cache its result"""
+    try:
+        with entry.config.sync_lock(entry.cache_key):
+            result = entry.function(*entry.args, **entry.kwargs)
+            entry.config.storage.set(entry.cache_key, result, None)
+            entry.reset()
+    except BaseException:
+        entry.revive()
+        logger.debug(
+            "Exception caching function with never_die",
+            extra={"function": entry.function.__qualname__},
+            exc_info=True,
+        )
+
+
+async def _run_async_function_and_cache(entry: NeverDieCacheEntry):
+    """Run a function and cache its result"""
+    try:
+        async with entry.config.async_lock(entry.cache_key):
+            result = await entry.function(*entry.args, **entry.kwargs)
+            await entry.config.storage.aset(entry.cache_key, result, None)
+            entry.reset()
+    except BaseException:
+        entry.revive()
+        logger.debug(
+            "Exception caching function with never_die",
+            extra={"function": entry.function.__qualname__},
+            exc_info=True,
+        )
+
+
+def _cache_is_being_set(entry: NeverDieCacheEntry) -> bool:
+    if entry.loop:
+        return entry.cache_key in _NEVER_DIE_CACHE_FUTURES and not _NEVER_DIE_CACHE_FUTURES[entry.cache_key].done()
+    return entry.cache_key in _NEVER_DIE_CACHE_THREADS and _NEVER_DIE_CACHE_THREADS[entry.cache_key].is_alive()
+
+
+def _clear_dead_futures():
+    """Clear dead futures from the cache future registry"""
+    for cache_key, thread in list(_NEVER_DIE_CACHE_FUTURES.items()):
+        if thread.done():
+            del _NEVER_DIE_CACHE_FUTURES[cache_key]
+
+
+def _clear_dead_threads():
+    """Clear dead threads from the cache thread registry"""
+    for cache_key, thread in list(_NEVER_DIE_CACHE_THREADS.items()):
+        if thread.is_alive():
+            continue
+        del _NEVER_DIE_CACHE_THREADS[cache_key]
+
+
+def _refresh_never_die_caches():
+    """Background thread function that periodically refreshes never_die cache entries"""
+    while True:
+        try:
+            for entry in list(_NEVER_DIE_REGISTRY):
+                if not entry.is_expired():
+                    continue
+
+                if _cache_is_being_set(entry):
+                    continue
+
+                if not entry.loop:  # sync
+                    thread = threading.Thread(target=_run_sync_function_and_cache, args=(entry,), daemon=True)
+                    thread.start()
+                    _NEVER_DIE_CACHE_THREADS[entry.cache_key] = thread
+                    continue
+
+                if entry.loop.is_closed():
+                    logger.debug(
+                        f"Loop is closed, skipping future creation",
+                        extra={"function": entry.function.__qualname__},
+                        exc_info=True,
+                    )
+                    continue
+
+                try:
+                    coroutine = _run_async_function_and_cache(entry)
+                    future = asyncio.run_coroutine_threadsafe(coroutine, entry.loop)
+                except RuntimeError:
+                    coroutine.close()
+                    logger.debug(
+                        f"Loop is closed, skipping future creation",
+                        extra={"function": entry.function.__qualname__},
+                        exc_info=True,
+                    )
+                    continue
+
+                _NEVER_DIE_CACHE_FUTURES[entry.cache_key] = future
+        finally:
+            time.sleep(_REFRESH_INTERVAL_SECONDS)
+            _clear_dead_futures()
+            _clear_dead_threads()
+
+
+def _start_never_die_thread():
+    """Start the background thread if it's not already running"""
+    global _NEVER_DIE_THREAD
+    with _NEVER_DIE_LOCK:
+        if _NEVER_DIE_THREAD and _NEVER_DIE_THREAD.is_alive():
+            return
+
+        _NEVER_DIE_THREAD = threading.Thread(target=_refresh_never_die_caches, daemon=True)
+        _NEVER_DIE_THREAD.start()
+
+
+def register_never_die_function(
+    function: Callable[..., Any],
+    ttl: Number,
+    args: tuple,
+    kwargs: dict,
+    cache_key_func: CacheKeyFunction | None,
+    ignore_fields: tuple[str, ...],
+    config: CacheConfig,
+):
+    """Register a function for never_die cache refreshing"""
+    is_async = inspect.iscoroutinefunction(function)
+
+    entry = NeverDieCacheEntry(
+        function=function,
+        ttl=ttl,
+        args=args,
+        kwargs=kwargs,
+        cache_key_func=cache_key_func,
+        ignore_fields=ignore_fields,
+        loop=asyncio.get_running_loop() if is_async else None,
+        config=config,
+    )
+
+    with _NEVER_DIE_LOCK:
+        if entry not in _NEVER_DIE_REGISTRY:
+            _NEVER_DIE_REGISTRY.append(entry)
+
+    _start_never_die_thread()
+
+
+def clear_never_die_registry():
+    """
+    Clear all entries from the never_die registry.
+
+    Useful for testing to prevent background threads from
+    accessing resources that have been cleaned up.
+    """
+    with _NEVER_DIE_LOCK:
+        _NEVER_DIE_REGISTRY.clear()
+        _NEVER_DIE_CACHE_THREADS.clear()
+        _NEVER_DIE_CACHE_FUTURES.clear()

cachify/memory_cache.py

@@ -0,0 +1,37 @@
+import threading
+from typing import Callable
+
+from cachify.cache import base_cache
+from cachify.storage.memory_storage import MemoryStorage
+from cachify.types import CacheConfig, CacheKeyFunction, F, Number
+from cachify.utils.locks import ASYNC_LOCKS, SYNC_LOCKS
+
+_CACHE_CLEAR_THREAD: threading.Thread | None = None
+_CACHE_CLEAR_LOCK: threading.Lock = threading.Lock()
+
+_MEMORY_CONFIG = CacheConfig(
+    storage=MemoryStorage,
+    sync_lock=lambda cache_key: SYNC_LOCKS[cache_key],
+    async_lock=lambda cache_key: ASYNC_LOCKS[cache_key],
+)
+
+
+def _start_cache_clear_thread():
+    """This is to avoid memory leaks by clearing expired cache items periodically."""
+    global _CACHE_CLEAR_THREAD
+    with _CACHE_CLEAR_LOCK:
+        if _CACHE_CLEAR_THREAD and _CACHE_CLEAR_THREAD.is_alive():
+            return
+        _CACHE_CLEAR_THREAD = threading.Thread(target=MemoryStorage.clear_expired_cached_items, daemon=True)
+        _CACHE_CLEAR_THREAD.start()
+
+
+def cache(
+    ttl: Number = 300,
+    never_die: bool = False,
+    cache_key_func: CacheKeyFunction | None = None,
+    ignore_fields: tuple[str, ...] = (),
+) -> Callable[[F], F]:
+    """In-memory cache decorator. See `base_cache` for full documentation."""
+    _start_cache_clear_thread()
+    return base_cache(ttl, never_die, cache_key_func, ignore_fields, _MEMORY_CONFIG)

cachify/redis/__init__.py

@@ -0,0 +1,19 @@
+from cachify.redis.config import (
+    DEFAULT_KEY_PREFIX,
+    DEFAULT_LOCK_TIMEOUT,
+    RedisConfig,
+    get_redis_config,
+    reset_redis_config,
+    setup_redis_config,
+)
+from cachify.redis.lock import RedisLockManager
+
+__all__ = [
+    "DEFAULT_KEY_PREFIX",
+    "DEFAULT_LOCK_TIMEOUT",
+    "RedisConfig",
+    "RedisLockManager",
+    "get_redis_config",
+    "reset_redis_config",
+    "setup_redis_config",
+]

cachify/redis/config.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, get_args, overload
+
+if TYPE_CHECKING:
+    from redis import Redis
+    from redis.asyncio import Redis as AsyncRedis
+
+OnErrorType = Literal["silent", "raise"]
+
+DEFAULT_KEY_PREFIX = "cachify"
+DEFAULT_LOCK_TIMEOUT = 10
+
+
+@dataclass
+class RedisConfig:
+    """Configuration for Redis cache backend."""
+
+    sync_client: Redis | None
+    async_client: AsyncRedis | None
+    key_prefix: str
+    lock_timeout: int
+    on_error: OnErrorType
+
+    @overload
+    def get_client(self, is_async: Literal[True]) -> AsyncRedis: ...
+
+    @overload
+    def get_client(self, is_async: Literal[False]) -> Redis: ...
+
+    def get_client(self, is_async: bool) -> Redis | AsyncRedis:
+        """Get the appropriate Redis client based on is_async flag."""
+        if is_async:
+            client = self.async_client
+        else:
+            client = self.sync_client
+
+        if not client:
+            mode = "async" if is_async else "sync"
+            raise RuntimeError(
+                f"Redis {mode} client not configured."
+                f"Provide {mode}_client in setup_redis_config() to use @redis_cache on {mode} functions."
+            )
+        return client
+
+
+_redis_config: RedisConfig | None = None
+
+
+def setup_redis_config(
+    sync_client: Redis | None = None,
+    async_client: AsyncRedis | None = None,
+    key_prefix: str = DEFAULT_KEY_PREFIX,
+    lock_timeout: int = DEFAULT_LOCK_TIMEOUT,
+    on_error: OnErrorType = "silent",
+):
+    """
+    Configure the Redis cache backend.
+
+    Must be called before using @redis_cache decorator.
+    Can only be called once. Use reset_redis_config() first if reconfiguration is needed.
+
+    Args:
+        sync_client: Redis sync client instance (redis.Redis)
+        async_client: Redis async client instance (redis.asyncio.Redis)
+        key_prefix: Prefix for all cache keys in Redis (default: "cache")
+        lock_timeout: Timeout in seconds for distributed locks (default: 10)
+        on_error: Error handling mode - "silent" treats errors as cache miss,
+                  "raise" propagates exceptions (default: "silent")
+
+    Raises:
+        ValueError: If neither sync_client nor async_client is provided
+        RuntimeError: If called twice without reset_redis_config() first
+    """
+    global _redis_config
+
+    if _redis_config is not None:
+        raise RuntimeError("Redis config already set. Call reset_redis_config() first if you need to reconfigure.")
+
+    if sync_client is None and async_client is None:
+        raise ValueError("At least one of sync_client or async_client must be provided")
+
+    if on_error not in get_args(OnErrorType):
+        raise ValueError(f"on_error must be one of {get_args(OnErrorType)}")
+
+    _redis_config = RedisConfig(
+        sync_client=sync_client,
+        async_client=async_client,
+        key_prefix=key_prefix,
+        lock_timeout=lock_timeout,
+        on_error=on_error,
+    )
+
+
+def get_redis_config() -> RedisConfig:
+    """
+    Get the current Redis configuration.
+
+    Raises:
+        RuntimeError: If setup_redis_config() has not been called
+    """
+    if _redis_config is None:
+        raise RuntimeError("Redis not configured. Call setup_redis_config() before using @redis_cache")
+    return _redis_config
+
+
+def reset_redis_config():
+    """
+    Reset the Redis configuration to allow reconfiguration.
+
+    Useful for testing or when you need to change Redis connection settings.
+    """
+    global _redis_config
+    _redis_config = None