cachify 0.2.0__tar.gz → 0.3.0__tar.gz

{cachify-0.2.0 → cachify-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Pulsar Finance
+Copyright (c) 2026 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

{cachify-0.2.0 → cachify-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachify
-Version: 0.2.0
+Version: 0.3.0
 Summary: A simple cache library with sync/async support, Memory and Redis backend
 License: MIT
 License-File: LICENSE
@@ -28,6 +28,19 @@ Description-Content-Type: text/markdown
 
 A simple and robust caching library for Python functions, supporting both synchronous and asynchronous code.
 
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Redis Cache](#redis-cache)
+  - [Never Die Cache](#never-die-cache)
+  - [Skip Cache](#skip-cache)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Features
 
 - Cache function results based on function ID and arguments
@@ -41,12 +54,14 @@ A simple and robust caching library for Python functions, supporting both synchr
 ## Installation
 
 ```bash
-# Clone the repository
-git clone https://github.com/PulsarDefi/cachify.git
-cd cachify
+# Using pip
+pip install cachify
+
+# Using poetry
+poetry add cachify
 
-# Install the package
-poetry install
+# Using uv
+uv add cachify
 ```
 
 ## Usage
@@ -57,18 +72,58 @@ poetry install
 from cachify import cache
 
 # Cache function in sync functions
-@cache(ttl=60) # ttl in seconds
+@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
+@cache(ttl=3600)  # ttl in seconds
 async def another_calculation(url):
     # Some expensive IO call
     return await httpx.get(url).json()
 ```
 
+### Decorator Parameters
+
+| Parameter        | Type            | Default | Description                                                    |
+| ---------------- | --------------- | ------- | -------------------------------------------------------------- |
+| `ttl`            | `int \| float`  | `300`   | Time to live for cached items in seconds                       |
+| `never_die`      | `bool`          | `False` | If True, cache refreshes automatically in background           |
+| `cache_key_func` | `Callable`      | `None`  | Custom function to generate cache keys                         |
+| `ignore_fields`  | `Sequence[str]` | `()`    | Function parameters to exclude from cache key                  |
+| `no_self`        | `bool`          | `False` | If True, ignores the first parameter (usually `self` or `cls`) |
+
+### Custom Cache Key Function
+
+Use `cache_key_func` when you need custom control over how cache keys are generated:
+
+```python
+from cachify import cache
+
+def custom_key(args: tuple, kwargs: dict) -> str:
+    user_id = kwargs.get("user_id") or args[0]
+    return f"user:{user_id}"
+
+@cache(ttl=60, cache_key_func=custom_key)
+def get_user_profile(user_id: int):
+    return fetch_from_database(user_id)
+```
+
+### Ignore Fields
+
+Use `ignore_fields` to exclude specific parameters from the cache key. Useful when some arguments don't affect the result:
+
+```python
+from cachify import cache
+
+@cache(ttl=300, ignore_fields=("logger", "request_id"))
+def fetch_data(query: str, logger: Logger, request_id: str):
+    # Cache key only uses 'query', ignoring logger and request_id
+    logger.info(f"Fetching data for request {request_id}")
+    return database.execute(query)
+```
+
 ### Redis Cache
 
 For distributed caching across multiple processes or machines, use `rcache`:
@@ -80,7 +135,7 @@ 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:*"
+    key_prefix="myapp",       # default: "cachify", 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
 )
@@ -95,7 +150,7 @@ 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:
+async def get_user_async(user_id: int) -> dict:
     return await fetch_from_database(user_id)
 ```
 
@@ -166,7 +221,11 @@ Run the test scripts
 poetry run python -m pytest
 ```
 
+## Contributing
+
+Contributions are welcome! Feel free to open an issue or submit a pull request.
+
 ## License
 
-MIT
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/PulsarDataSolutions/cachify/blob/master/LICENSE) file for details.
 

{cachify-0.2.0 → cachify-0.3.0}/README.md

@@ -2,6 +2,19 @@
 
 A simple and robust caching library for Python functions, supporting both synchronous and asynchronous code.
 
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Redis Cache](#redis-cache)
+  - [Never Die Cache](#never-die-cache)
+  - [Skip Cache](#skip-cache)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Features
 
 - Cache function results based on function ID and arguments
@@ -15,12 +28,14 @@ A simple and robust caching library for Python functions, supporting both synchr
 ## Installation
 
 ```bash
-# Clone the repository
-git clone https://github.com/PulsarDefi/cachify.git
-cd cachify
+# Using pip
+pip install cachify
+
+# Using poetry
+poetry add cachify
 
-# Install the package
-poetry install
+# Using uv
+uv add cachify
 ```
 
 ## Usage
@@ -31,18 +46,58 @@ poetry install
 from cachify import cache
 
 # Cache function in sync functions
-@cache(ttl=60) # ttl in seconds
+@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
+@cache(ttl=3600)  # ttl in seconds
 async def another_calculation(url):
     # Some expensive IO call
     return await httpx.get(url).json()
 ```
 
+### Decorator Parameters
+
+| Parameter        | Type            | Default | Description                                                    |
+| ---------------- | --------------- | ------- | -------------------------------------------------------------- |
+| `ttl`            | `int \| float`  | `300`   | Time to live for cached items in seconds                       |
+| `never_die`      | `bool`          | `False` | If True, cache refreshes automatically in background           |
+| `cache_key_func` | `Callable`      | `None`  | Custom function to generate cache keys                         |
+| `ignore_fields`  | `Sequence[str]` | `()`    | Function parameters to exclude from cache key                  |
+| `no_self`        | `bool`          | `False` | If True, ignores the first parameter (usually `self` or `cls`) |
+
+### Custom Cache Key Function
+
+Use `cache_key_func` when you need custom control over how cache keys are generated:
+
+```python
+from cachify import cache
+
+def custom_key(args: tuple, kwargs: dict) -> str:
+    user_id = kwargs.get("user_id") or args[0]
+    return f"user:{user_id}"
+
+@cache(ttl=60, cache_key_func=custom_key)
+def get_user_profile(user_id: int):
+    return fetch_from_database(user_id)
+```
+
+### Ignore Fields
+
+Use `ignore_fields` to exclude specific parameters from the cache key. Useful when some arguments don't affect the result:
+
+```python
+from cachify import cache
+
+@cache(ttl=300, ignore_fields=("logger", "request_id"))
+def fetch_data(query: str, logger: Logger, request_id: str):
+    # Cache key only uses 'query', ignoring logger and request_id
+    logger.info(f"Fetching data for request {request_id}")
+    return database.execute(query)
+```
+
 ### Redis Cache
 
 For distributed caching across multiple processes or machines, use `rcache`:
@@ -54,7 +109,7 @@ 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:*"
+    key_prefix="myapp",       # default: "cachify", 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
 )
@@ -69,7 +124,7 @@ 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:
+async def get_user_async(user_id: int) -> dict:
     return await fetch_from_database(user_id)
 ```
 
@@ -140,6 +195,10 @@ Run the test scripts
 poetry run python -m pytest
 ```
 
+## Contributing
+
+Contributions are welcome! Feel free to open an issue or submit a pull request.
+
 ## License
 
-MIT
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/PulsarDataSolutions/cachify/blob/master/LICENSE) file for details.

{cachify-0.2.0 → cachify-0.3.0}/cachify/cache.py

@@ -1,6 +1,6 @@
 import functools
 import inspect
-from typing import Any, Callable, cast
+from typing import Any, Callable, Sequence, cast
 
 from cachify.features.never_die import register_never_die_function
 from cachify.types import CacheConfig, CacheKeyFunction, F, Number
@@ -73,7 +73,8 @@ def base_cache(
     ttl: Number,
     never_die: bool,
     cache_key_func: CacheKeyFunction | None,
-    ignore_fields: tuple[str, ...],
+    ignore_fields: Sequence[str],
+    no_self: bool,
     config: CacheConfig,
 ) -> Callable[[F], F]:
     """
@@ -83,7 +84,8 @@ def base_cache(
         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
+        ignore_fields: Sequence of strings with the function params to ignore when creating the cache key
+        no_self: if True, the first parameter (typically 'self' for methods) will be ignored when creating the cache key
         config: Cache configuration specifying storage, locks, and never_die registration
 
     Features:
@@ -91,17 +93,23 @@ def base_cache(
         - 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:
+
+    if cache_key_func and (ignore_fields or no_self):
         raise ValueError("Either cache_key_func or ignore_fields can be provided, but not both")
 
     def decorator(function: F) -> F:
+        ignore = tuple(ignore_fields)
+
+        if no_self:
+            ignore += function.__code__.co_varnames[:1]
+
         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,
+                ignore_fields=ignore,
                 config=config,
             )
         return _sync_decorator(
@@ -109,7 +117,7 @@ def base_cache(
             ttl=ttl,
             never_die=never_die,
             cache_key_func=cache_key_func,
-            ignore_fields=ignore_fields,
+            ignore_fields=ignore,
             config=config,
         )
 

{cachify-0.2.0 → cachify-0.3.0}/cachify/features/never_die.py

@@ -140,19 +140,19 @@ def _refresh_never_die_caches():
 
                 if entry.loop.is_closed():
                     logger.debug(
-                        f"Loop is closed, skipping future creation",
+                        "Loop is closed, skipping future creation",
                         extra={"function": entry.function.__qualname__},
                         exc_info=True,
                     )
                     continue
 
+                coroutine = _run_async_function_and_cache(entry)
                 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",
+                        "Loop is closed, skipping future creation",
                         extra={"function": entry.function.__qualname__},
                         exc_info=True,
                     )

{cachify-0.2.0 → cachify-0.3.0}/cachify/memory_cache.py

@@ -1,18 +1,22 @@
+import asyncio
 import threading
-from typing import Callable
+from collections import defaultdict
+from typing import Callable, Sequence
 
 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()
 
+_ASYNC_LOCKS: defaultdict[str, asyncio.Lock] = defaultdict(asyncio.Lock)
+_SYNC_LOCKS: defaultdict[str, threading.Lock] = defaultdict(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],
+    sync_lock=_SYNC_LOCKS.__getitem__,
+    async_lock=_ASYNC_LOCKS.__getitem__,
 )
 
 
@@ -30,8 +34,9 @@ def cache(
     ttl: Number = 300,
     never_die: bool = False,
     cache_key_func: CacheKeyFunction | None = None,
-    ignore_fields: tuple[str, ...] = (),
+    ignore_fields: Sequence[str] = (),
+    no_self: bool = False,
 ) -> 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)
+    return base_cache(ttl, never_die, cache_key_func, ignore_fields, no_self, _MEMORY_CONFIG)

{cachify-0.2.0 → cachify-0.3.0}/cachify/redis_cache.py

@@ -1,4 +1,4 @@
-from typing import Callable
+from typing import Callable, Sequence
 
 from cachify.cache import base_cache
 from cachify.redis.lock import RedisLockManager
@@ -16,7 +16,8 @@ def redis_cache(
     ttl: Number = 300,
     never_die: bool = False,
     cache_key_func: CacheKeyFunction | None = None,
-    ignore_fields: tuple[str, ...] = (),
+    ignore_fields: Sequence[str] = (),
+    no_self: bool = False,
 ) -> Callable[[F], F]:
     """
     Redis cache decorator. See `base_cache` for full documentation.
@@ -24,4 +25,4 @@ def redis_cache(
     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)
+    return base_cache(ttl, never_die, cache_key_func, ignore_fields, no_self, _REDIS_CONFIG)

{cachify-0.2.0 → cachify-0.3.0}/cachify/utils/arguments.py

@@ -1,17 +1,12 @@
-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.errors import CacheKeyError
 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()
+from cachify.utils.hash import object_hash
 
 
 def _iter_arguments(
@@ -54,12 +49,12 @@ def create_cache_key(
     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)}"
+        return f"{function_id}:{object_hash(items)}"
 
     cache_key = cache_key_func(args, kwargs)
     try:
-        return f"{function_id}:{_cache_key_fingerprint(cache_key)}"
+        return f"{function_id}:{object_hash(cache_key)}"
     except TypeError as exc:
-        raise ValueError(
+        raise CacheKeyError(
             "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-0.3.0/cachify/utils/errors.py

@@ -0,0 +1,2 @@
+class CacheKeyError(ValueError):
+    pass

cachify-0.3.0/cachify/utils/hash.py

@@ -0,0 +1,18 @@
+import hashlib
+import pickle
+from typing import Any
+
+from cachify.utils.errors import CacheKeyError
+
+
+def object_hash(value: Any) -> str:
+    try:
+        payload = pickle.dumps(value, protocol=pickle.HIGHEST_PROTOCOL)
+
+    except Exception as exc:
+        raise CacheKeyError(
+            "Unable to serialize object for hashing - ensure all parts of the object are pickleable. "
+            "Hint: create a custom __reduce__ method for the suspected object if necessary."
+        ) from exc
+
+    return hashlib.blake2b(payload, digest_size=16).hexdigest()

{cachify-0.2.0 → cachify-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "cachify"
-version = "0.2.0"
+version = "0.3.0"
 description = "A simple cache library with sync/async support, Memory and Redis backend"
 license = "MIT"
 readme = "README.md"

cachify-0.2.0/cachify/utils/decorator_factory.py

@@ -1,44 +0,0 @@
-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-0.2.0/cachify/utils/locks.py

@@ -1,6 +0,0 @@
-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)

{cachify-0.2.0 → cachify-0.3.0}/cachify/__init__.py

@@ -12,13 +12,13 @@ rcache = redis_cache
 
 __all__ = [
     "__version__",
-    "cache",
     "rcache",
-    "redis_cache",
-    "setup_redis_config",
+    "clear_never_die_registry",
+    "cache",
+    "DEFAULT_KEY_PREFIX",
     "get_redis_config",
     "reset_redis_config",
-    "DEFAULT_KEY_PREFIX",
+    "setup_redis_config",
+    "redis_cache",
     "CacheKwargs",
-    "clear_never_die_registry",
 ]