cachify 0.1.0__tar.gz → 0.2.1__tar.gz

{cachify-0.1.0 → cachify-0.2.1}/LICENSE

@@ -1,21 +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.
+MIT License
+
+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
+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 → cachify-0.2.1}/PKG-INFO

@@ -1,9 +1,9 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: cachify
-Version: 0.1.0
+Version: 0.2.1
 Summary: A simple cache library with sync/async support, Memory and Redis backend
-Home-page: https://github.com/PulsarDataSolutions/cachify
 License: MIT
+License-File: LICENSE
 Keywords: cachify,cache,caching,redis,async,decorator,memoization
 Author: dynalz
 Author-email: git@pulsar.finance
@@ -20,6 +20,7 @@ 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: Homepage, https://github.com/PulsarDataSolutions/cachify
 Project-URL: Repository, https://github.com/PulsarDataSolutions/cachify
 Description-Content-Type: text/markdown
 
@@ -27,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
@@ -40,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
@@ -56,18 +72,57 @@ 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`  | `tuple[str, ...]` | `()`    | Function parameters to exclude from cache key        |
+
+### 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`:
@@ -79,7 +134,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
 )
@@ -94,7 +149,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)
 ```
 
@@ -165,7 +220,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.1.0 → cachify-0.2.1}/README.md

@@ -1,145 +1,203 @@
-# 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
+# Python Cachify Library
+
+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
+- 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
+# Using pip
+pip install cachify
+
+# Using poetry
+poetry add cachify
+
+# Using uv
+uv add cachify
+```
+
+## 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()
+```
+
+### 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`  | `tuple[str, ...]` | `()`    | Function parameters to exclude from cache key        |
+
+### 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`:
+
+```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: "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
+)
+
+@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)
+async 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
+```
+
+## Contributing
+
+Contributions are welcome! Feel free to open an issue or submit a pull request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/PulsarDataSolutions/cachify/blob/master/LICENSE) file for details.

{cachify-0.1.0 → cachify-0.2.1}/cachify/__init__.py

@@ -1,22 +1,23 @@
-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",
-]
+from importlib.metadata import version
+
+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__ = version("cachify")
+
+rcache = redis_cache
+
+__all__ = [
+    "__version__",
+    "cache",
+    "rcache",
+    "redis_cache",
+    "setup_redis_config",
+    "get_redis_config",
+    "reset_redis_config",
+    "DEFAULT_KEY_PREFIX",
+    "CacheKwargs",
+]