cachify 0.1.0__tar.gz

cachify-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pulsar Finance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cachify-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.1
+Name: cachify
+Version: 0.1.0
+Summary: A simple cache library with sync/async support, Memory and Redis backend
+Home-page: https://github.com/PulsarDataSolutions/cachify
+License: MIT
+Keywords: cachify,cache,caching,redis,async,decorator,memoization
+Author: dynalz
+Author-email: git@pulsar.finance
+Requires-Python: >=3.10,<3.15
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: redis[hiredis] (>5.0.0)
+Project-URL: Repository, https://github.com/PulsarDataSolutions/cachify
+Description-Content-Type: text/markdown
+
+# Python Cachify Library
+
+A simple and robust caching library for Python functions, supporting both synchronous and asynchronous code.
+
+## Features
+
+- Cache function results based on function ID and arguments
+- Supports both synchronous and asynchronous functions
+- Thread-safe locking to prevent duplicate cached function calls
+- Configurable Time-To-Live (TTL) for cached items
+- "Never Die" mode for functions that should keep cache refreshed automatically
+- Skip cache functionality to force fresh function execution while updating cache
+- Redis cache for distributed caching across multiple processes/machines
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/PulsarDefi/cachify.git
+cd cachify
+
+# Install the package
+poetry install
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from cachify import cache
+
+# Cache function in sync functions
+@cache(ttl=60) # ttl in seconds
+def expensive_calculation(a, b):
+    # Some expensive operation
+    return a + b
+
+# And async functions
+@cache(ttl=3600) # ttl in seconds
+async def another_calculation(url):
+    # Some expensive IO call
+    return await httpx.get(url).json()
+```
+
+### Redis Cache
+
+For distributed caching across multiple processes or machines, use `rcache`:
+
+```python
+import redis
+from cachify import setup_redis_config, rcache
+
+# Configure Redis (call once at startup)
+setup_redis_config(
+    sync_client=redis.from_url("redis://localhost:6379/0"),
+    key_prefix="myapp",       # default: "key_prefix", prefix searchable on redis "PREFIX:*"
+    lock_timeout=10,          # default: 10, maximum lock lifetime in seconds
+    on_error="silent",        # "silent" (default) or "raise" in case of redis errors
+)
+
+@rcache(ttl=300)
+def get_user(user_id: int) -> dict:
+    return fetch_from_database(user_id)
+
+# Async version
+import redis.asyncio as aredis
+
+setup_redis_config(async_client=aredis.from_url("redis://localhost:6379/0"))
+
+@rcache(ttl=300)
+def get_user_async(user_id: int) -> dict:
+    return await fetch_from_database(user_id)
+```
+
+### Never Die Cache
+
+The `never_die` feature ensures that cached values never expire by automatically refreshing them in the background:
+
+```python
+# Cache with never_die (automatic refresh)
+@cache(ttl=300, never_die=True)
+def critical_operation(data_id: str):
+    # Expensive operation that should always be available from cache
+    return fetch_data_from_database(data_id)
+```
+
+**How Never Die Works:**
+
+1. When a function with `never_die=True` is first called, the result is cached
+2. A background thread monitors all `never_die` functions
+3. On cache expiration (TTL), the function is automatically called again
+4. The cache is updated with the new result
+5. If the refresh operation fails, the existing cached value is preserved
+6. Clients always get fast response times by reading from cache
+
+**Benefits:**
+
+- Cache is always "warm" and ready to serve
+- No user request ever has to wait for the expensive operation
+- If a dependency service from the cached function goes down temporarily, the last successful result is still available
+- Perfect for critical operations where latency must be minimized
+
+### Skip Cache
+
+The `skip_cache` feature allows you to bypass reading from cache while still updating it with fresh results:
+
+```python
+@cache(ttl=300)
+def get_user_data(user_id):
+    # Expensive operation to fetch user data
+    return fetch_from_database(user_id)
+
+# Normal call - uses cache if available
+user = get_user_data(123)
+# Force fresh execution while updating cache
+fresh_user = get_user_data(123, skip_cache=True)
+# Next normal call will get the updated cached value
+updated_user = get_user_data(123)
+```
+
+**How Skip Cache Works:**
+
+1. When `skip_cache=True` is passed, the function bypasses reading from cache
+2. The function executes normally and returns fresh results
+3. The fresh result is stored in the cache, updating any existing cached value
+4. Subsequent calls without `skip_cache=True` will use the updated cached value
+5. The TTL timer resets from when the cache last was updated
+
+**Benefits:**
+
+- Force refresh of potentially stale data while keeping cache warm
+- Ensuring fresh data for critical operations while maintaining cache for other calls
+
+## Testing
+
+Run the test scripts
+
+```bash
+poetry run python -m pytest
+```
+
+## License
+
+MIT
+

cachify-0.1.0/README.md

@@ -0,0 +1,145 @@
+# Python Cachify Library
+
+A simple and robust caching library for Python functions, supporting both synchronous and asynchronous code.
+
+## Features
+
+- Cache function results based on function ID and arguments
+- Supports both synchronous and asynchronous functions
+- Thread-safe locking to prevent duplicate cached function calls
+- Configurable Time-To-Live (TTL) for cached items
+- "Never Die" mode for functions that should keep cache refreshed automatically
+- Skip cache functionality to force fresh function execution while updating cache
+- Redis cache for distributed caching across multiple processes/machines
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/PulsarDefi/cachify.git
+cd cachify
+
+# Install the package
+poetry install
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from cachify import cache
+
+# Cache function in sync functions
+@cache(ttl=60) # ttl in seconds
+def expensive_calculation(a, b):
+    # Some expensive operation
+    return a + b
+
+# And async functions
+@cache(ttl=3600) # ttl in seconds
+async def another_calculation(url):
+    # Some expensive IO call
+    return await httpx.get(url).json()
+```
+
+### Redis Cache
+
+For distributed caching across multiple processes or machines, use `rcache`:
+
+```python
+import redis
+from cachify import setup_redis_config, rcache
+
+# Configure Redis (call once at startup)
+setup_redis_config(
+    sync_client=redis.from_url("redis://localhost:6379/0"),
+    key_prefix="myapp",       # default: "key_prefix", prefix searchable on redis "PREFIX:*"
+    lock_timeout=10,          # default: 10, maximum lock lifetime in seconds
+    on_error="silent",        # "silent" (default) or "raise" in case of redis errors
+)
+
+@rcache(ttl=300)
+def get_user(user_id: int) -> dict:
+    return fetch_from_database(user_id)
+
+# Async version
+import redis.asyncio as aredis
+
+setup_redis_config(async_client=aredis.from_url("redis://localhost:6379/0"))
+
+@rcache(ttl=300)
+def get_user_async(user_id: int) -> dict:
+    return await fetch_from_database(user_id)
+```
+
+### Never Die Cache
+
+The `never_die` feature ensures that cached values never expire by automatically refreshing them in the background:
+
+```python
+# Cache with never_die (automatic refresh)
+@cache(ttl=300, never_die=True)
+def critical_operation(data_id: str):
+    # Expensive operation that should always be available from cache
+    return fetch_data_from_database(data_id)
+```
+
+**How Never Die Works:**
+
+1. When a function with `never_die=True` is first called, the result is cached
+2. A background thread monitors all `never_die` functions
+3. On cache expiration (TTL), the function is automatically called again
+4. The cache is updated with the new result
+5. If the refresh operation fails, the existing cached value is preserved
+6. Clients always get fast response times by reading from cache
+
+**Benefits:**
+
+- Cache is always "warm" and ready to serve
+- No user request ever has to wait for the expensive operation
+- If a dependency service from the cached function goes down temporarily, the last successful result is still available
+- Perfect for critical operations where latency must be minimized
+
+### Skip Cache
+
+The `skip_cache` feature allows you to bypass reading from cache while still updating it with fresh results:
+
+```python
+@cache(ttl=300)
+def get_user_data(user_id):
+    # Expensive operation to fetch user data
+    return fetch_from_database(user_id)
+
+# Normal call - uses cache if available
+user = get_user_data(123)
+# Force fresh execution while updating cache
+fresh_user = get_user_data(123, skip_cache=True)
+# Next normal call will get the updated cached value
+updated_user = get_user_data(123)
+```
+
+**How Skip Cache Works:**
+
+1. When `skip_cache=True` is passed, the function bypasses reading from cache
+2. The function executes normally and returns fresh results
+3. The fresh result is stored in the cache, updating any existing cached value
+4. Subsequent calls without `skip_cache=True` will use the updated cached value
+5. The TTL timer resets from when the cache last was updated
+
+**Benefits:**
+
+- Force refresh of potentially stale data while keeping cache warm
+- Ensuring fresh data for critical operations while maintaining cache for other calls
+
+## Testing
+
+Run the test scripts
+
+```bash
+poetry run python -m pytest
+```
+
+## License
+
+MIT

cachify-0.1.0/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-0.1.0/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-0.1.0/cachify/config/__init__.py

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

cachify-0.1.0/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()