# ConditionalCache
<img alt="ConditionalCache" title="ConditionalCache" src="https://raw.githubusercontent.com/Eric-Canas/ConditionalCache/main/resources/logo.png" width="20%" align="left">
**ConditionalCache** is a set of _decorators_, that provide **conditional function memoization** and **selective cache clearing**.
It works under the same interface that most standard cache decorators like [functools.lru_cache](https://docs.python.org/es/3/library/functools.html#functools.lru_cache) or [cachetools.ttl_cache](https://cachetools.readthedocs.io/en/latest/#cachetools.TTLCache), but unlocking a new `condition` parameter, that will determine if the function result is _memoized_ or not. This feature allows for more granular control over caching behavior, useful for those use cases where we want to store the output only when certain conditions are met. As for example when checking existence in databases.
## Installation
To install **ConditionalCache** simply run:
```bash
pip install conditional-cache
```
## Usage
Working with **ConditionalCache** is as simple and straight-forward as using [functools.lru_cache](https://docs.python.org/es/3/library/functools.html#functools.lru_cache), as it works under the same interface.
```python
from conditional_cache import lru_cache
# Memoize the returned element only when it is different than "Not Found"
@lru_cache(maxsize=64, condition=lambda db_value: db_value != "Not Found")
def element_exists_in_db(element_id: int) -> str:
print(f"Asked to DB: {element_id}")
# For the example let's consider that even elements exists.
return "Found" if element_id % 2 == 0 else "Not Found"
```
When we will call this function, it will be execute **only once** for even numbers, and always for odds.
```python
# Will be executed, and not memoized
print(f"Returned: {element_exists_in_db(element_id=1)}")
# Will be executed again
print(f"Returned: {element_exists_in_db(element_id=1)}\n")
# Will be executed and memoized
print(f"Returned: {element_exists_in_db(element_id=2)}")
# Will return the memoized result without executing again
print(f"Returned: {element_exists_in_db(element_id=2)}")
```
```bash
>> Asked to DB: 1
>> Returned: Not Found
>> Asked to DB: 1
>> Returned: Not Found
>> Asked to DB: 2
>> Returned: Found
>> Returned: Found
```
If during your execution, you perform an action that invalidate a given function result, you can actively remove that element cache:
```python
# Will return the result that was memoized before
print(f"Returned: {element_exists_in_db(element_id=2)}\n")
# Remove the element from the cache
element_exists_in_db.cache_remove(element_id=2)
# Will be executed again and memoized
print(f"Returned: {element_exists_in_db(element_id=2)}")
# Will return the memoized result
print(f"Returned: {element_exists_in_db(element_id=2)}")
```
```bash
>> Returned: Found
>> Asked to DB: 2
>> Returned: Found
>> Returned: Found
```
### Controlling cache size by memory
In addition to `maxsize` (number of elements), you can also limit the cache by **memory usage** with `maxsize_bytes`.
```python
from conditional_cache import lru_cache
@lru_cache(maxsize_bytes=1024) # keep up to ~1 KB of cached data
def heavy_query(x: int) -> str:
print("Executed:", x)
return "X" * (x * 100)
heavy_query(1) # Cached
heavy_query(10) # May evict older entries if too large
```
This way you can avoid **overflowing** your memory if you need to cache large objects like images. If a single result is **too large** to ever fit in the cache, it will just not be stored.
### Time-based expiration (TTL)
Use `ttl_cache` when you want cached entries to automatically expire after a given number of seconds.
```python
import time
from conditional_cache import ttl_cache
@ttl_cache(ttl=3, maxsize=64, condition=lambda r: r is not None)
def fetch_user(user_id: int) -> dict | None:
print("Fetching:", user_id)
return {"id": user_id}
fetch_user(1) # Executed and cached
time.sleep(1)
fetch_user(1) # Retrieved from cache
time.sleep(3)
fetch_user(1) # Expired -> executed again
```
### Unhashable arguments
Unlike `functools`, **ConditionalCache** supports common unhashable types like `list`, `dict`, or `set` as arguments. They are transparently converted to hashable equivalents to avoid headaches.
```python
from conditional_cache import lru_cache
@lru_cache(maxsize=32)
def stringify(a: list, b: dict) -> str:
print("Executed:", a, b)
return str(a) + str(b)
print(stringify([1,2,3], {"x": 42}))
print(stringify([1,2,3], {"x": 42})) # retrieved from cache
```
## API Reference
### conditional_cache.lru_cache(maxsize: int = 128, maxsize_bytes: int | None = None, typed: bool = False, condition: callable = lambda x: True)
An _Least Recently Used_ Cache. It works the same way that [functools.lru_cache](https://docs.python.org/es/3/library/functools.html#functools.lru_cache) but accepting **conditional storage** and **selective item removing** through <decorated_function>.cache_remove(**args)
- `maxsize`: **int**. The maximum amount of elements to keep cached. Once the cache is full, new elements will start to override oldest ones.
- `maxsize_bytes`: **int | None**. The maximum amount of memory (in bytes, as estimated by `sys.getsizeof`) to keep cached. Useful when caching large objects. If a single item is larger than this budget, it will simply not be cached.
- `typed`: **bool**. Works the same way that [functools.lru_cache](https://docs.python.org/es/3/library/functools.html#functools.lru_cache). If `True`, function arguments of different types will be cached separately.
- `condition`: **callable**. It must be a function that receives a single parameter as input (the output of the _decorated_ method) and returns a `boolean`. `True` if the result should be cached or `False` if it should not.
### conditional_cache.ttl_cache(maxsize: int = 128, maxsize_bytes: int | None = None, typed: bool = False, ttl: int = 60, condition: callable = lambda x: True)
A _Time-To-Live_ cache. Behaves like `lru_cache` with the same conditional storage and selective removal features, but cached entries automatically expire after `ttl` seconds.
- `maxsize`: **int**. Maximum number of elements to keep cached.
- `maxsize_bytes`: **int | None**. Maximum memory budget for cached data. Items larger than this budget are not cached.
- `typed`: **bool**. If `True`, function arguments of different types are cached separately.
- `ttl`: **int**. Time-to-live in seconds for each cached entry.
- `condition`: **callable**. Receives the function output and returns `True` if it should be cached.
Raw data
{
"_id": null,
"home_page": "https://github.com/Eric-Canas/ConditionalCache",
"name": "conditional-cache",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Eric-Canas",
"author_email": "eric@ericcanas.com",
"download_url": "https://files.pythonhosted.org/packages/c8/2e/69a517945a81a16bff83e99d2a9ac7aa5eb82f6d75f55dfd56bcf001eeae/conditional_cache-1.4.tar.gz",
"platform": null,
"description": "# ConditionalCache\n<img alt=\"ConditionalCache\" title=\"ConditionalCache\" src=\"https://raw.githubusercontent.com/Eric-Canas/ConditionalCache/main/resources/logo.png\" width=\"20%\" align=\"left\">\n\n**ConditionalCache** is a set of _decorators_, that provide **conditional function memoization** and **selective cache clearing**.\n\nIt works under the same interface that most standard cache decorators like [functools.lru_cache](https://docs.python.org/es/3/library/functools.html#functools.lru_cache) or [cachetools.ttl_cache](https://cachetools.readthedocs.io/en/latest/#cachetools.TTLCache), but unlocking a new `condition` parameter, that will determine if the function result is _memoized_ or not. This feature allows for more granular control over caching behavior, useful for those use cases where we want to store the output only when certain conditions are met. As for example when checking existence in databases.\n\n## Installation\n\nTo install **ConditionalCache** simply run:\n\n```bash\npip install conditional-cache\n```\n\n## Usage\nWorking with **ConditionalCache** is as simple and straight-forward as using [functools.lru_cache](https://docs.python.org/es/3/library/functools.html#functools.lru_cache), as it works under the same interface.\n\n```python\nfrom conditional_cache import lru_cache\n\n# Memoize the returned element only when it is different than \"Not Found\"\n@lru_cache(maxsize=64, condition=lambda db_value: db_value != \"Not Found\")\ndef element_exists_in_db(element_id: int) -> str:\n\n print(f\"Asked to DB: {element_id}\")\n # For the example let's consider that even elements exists.\n return \"Found\" if element_id % 2 == 0 else \"Not Found\"\n```\n\nWhen we will call this function, it will be execute **only once** for even numbers, and always for odds.\n\n```python\n# Will be executed, and not memoized\nprint(f\"Returned: {element_exists_in_db(element_id=1)}\")\n# Will be executed again\nprint(f\"Returned: {element_exists_in_db(element_id=1)}\\n\")\n\n# Will be executed and memoized\nprint(f\"Returned: {element_exists_in_db(element_id=2)}\")\n# Will return the memoized result without executing again\nprint(f\"Returned: {element_exists_in_db(element_id=2)}\")\n```\n\n```bash\n>> Asked to DB: 1\n>> Returned: Not Found\n>> Asked to DB: 1\n>> Returned: Not Found\n\n>> Asked to DB: 2\n>> Returned: Found\n>> Returned: Found\n```\n\nIf during your execution, you perform an action that invalidate a given function result, you can actively remove that element cache:\n\n```python\n# Will return the result that was memoized before\nprint(f\"Returned: {element_exists_in_db(element_id=2)}\\n\")\n# Remove the element from the cache\nelement_exists_in_db.cache_remove(element_id=2)\n\n# Will be executed again and memoized\nprint(f\"Returned: {element_exists_in_db(element_id=2)}\")\n# Will return the memoized result\nprint(f\"Returned: {element_exists_in_db(element_id=2)}\")\n```\n\n```bash\n>> Returned: Found\n\n>> Asked to DB: 2\n>> Returned: Found\n>> Returned: Found\n```\n\n### Controlling cache size by memory\nIn addition to `maxsize` (number of elements), you can also limit the cache by **memory usage** with `maxsize_bytes`.\n\n```python\nfrom conditional_cache import lru_cache\n\n@lru_cache(maxsize_bytes=1024) # keep up to ~1 KB of cached data\ndef heavy_query(x: int) -> str:\n print(\"Executed:\", x)\n return \"X\" * (x * 100)\n\nheavy_query(1) # Cached\nheavy_query(10) # May evict older entries if too large\n```\n\nThis way you can avoid **overflowing** your memory if you need to cache large objects like images. If a single result is **too large** to ever fit in the cache, it will just not be stored.\n\n### Time-based expiration (TTL)\nUse `ttl_cache` when you want cached entries to automatically expire after a given number of seconds.\n\n```python\nimport time\nfrom conditional_cache import ttl_cache\n\n@ttl_cache(ttl=3, maxsize=64, condition=lambda r: r is not None)\ndef fetch_user(user_id: int) -> dict | None:\n print(\"Fetching:\", user_id)\n return {\"id\": user_id}\n\nfetch_user(1) # Executed and cached\ntime.sleep(1)\nfetch_user(1) # Retrieved from cache\ntime.sleep(3)\nfetch_user(1) # Expired -> executed again\n```\n\n### Unhashable arguments\nUnlike `functools`, **ConditionalCache** supports common unhashable types like `list`, `dict`, or `set` as arguments. They are transparently converted to hashable equivalents to avoid headaches.\n\n```python\nfrom conditional_cache import lru_cache\n\n@lru_cache(maxsize=32)\ndef stringify(a: list, b: dict) -> str:\n print(\"Executed:\", a, b)\n return str(a) + str(b)\n\nprint(stringify([1,2,3], {\"x\": 42}))\nprint(stringify([1,2,3], {\"x\": 42})) # retrieved from cache\n```\n\n## API Reference\n\n### conditional_cache.lru_cache(maxsize: int = 128, maxsize_bytes: int | None = None, typed: bool = False, condition: callable = lambda x: True)\nAn _Least Recently Used_ Cache. It works the same way that [functools.lru_cache](https://docs.python.org/es/3/library/functools.html#functools.lru_cache) but accepting **conditional storage** and **selective item removing** through <decorated_function>.cache_remove(**args)\n\n- `maxsize`: **int**. The maximum amount of elements to keep cached. Once the cache is full, new elements will start to override oldest ones.\n- `maxsize_bytes`: **int | None**. The maximum amount of memory (in bytes, as estimated by `sys.getsizeof`) to keep cached. Useful when caching large objects. If a single item is larger than this budget, it will simply not be cached.\n- `typed`: **bool**. Works the same way that [functools.lru_cache](https://docs.python.org/es/3/library/functools.html#functools.lru_cache). If `True`, function arguments of different types will be cached separately.\n- `condition`: **callable**. It must be a function that receives a single parameter as input (the output of the _decorated_ method) and returns a `boolean`. `True` if the result should be cached or `False` if it should not.\n\n### conditional_cache.ttl_cache(maxsize: int = 128, maxsize_bytes: int | None = None, typed: bool = False, ttl: int = 60, condition: callable = lambda x: True)\nA _Time-To-Live_ cache. Behaves like `lru_cache` with the same conditional storage and selective removal features, but cached entries automatically expire after `ttl` seconds.\n\n- `maxsize`: **int**. Maximum number of elements to keep cached.\n- `maxsize_bytes`: **int | None**. Maximum memory budget for cached data. Items larger than this budget are not cached.\n- `typed`: **bool**. If `True`, function arguments of different types are cached separately.\n- `ttl`: **int**. Time-to-live in seconds for each cached entry.\n- `condition`: **callable**. Receives the function output and returns `True` if it should be cached.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Conditional cache is a wrapper over functools.lru_cache that allows for conditionally caching based on the output of the function.",
"version": "1.4",
"project_urls": {
"Homepage": "https://github.com/Eric-Canas/ConditionalCache"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "aad08f6af91e817689db88723301b8b59ffa82e099779472e13b0957e5d58419",
"md5": "3da42d88faa88154f15345b7e68ae5c6",
"sha256": "61a53d31372f0dc749bccae7e8694ad60200ca34b8c6ff415e9ca83780aec4b5"
},
"downloads": -1,
"filename": "conditional_cache-1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3da42d88faa88154f15345b7e68ae5c6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 6119,
"upload_time": "2025-08-26T12:20:26",
"upload_time_iso_8601": "2025-08-26T12:20:26.778857Z",
"url": "https://files.pythonhosted.org/packages/aa/d0/8f6af91e817689db88723301b8b59ffa82e099779472e13b0957e5d58419/conditional_cache-1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c82e69a517945a81a16bff83e99d2a9ac7aa5eb82f6d75f55dfd56bcf001eeae",
"md5": "ad1a15ecd98be021095087073f002e53",
"sha256": "f87be16cd342e32656f630a67868b7b1de674740b8159dc1159c854a97aac2e2"
},
"downloads": -1,
"filename": "conditional_cache-1.4.tar.gz",
"has_sig": false,
"md5_digest": "ad1a15ecd98be021095087073f002e53",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 5753,
"upload_time": "2025-08-26T12:20:27",
"upload_time_iso_8601": "2025-08-26T12:20:27.930056Z",
"url": "https://files.pythonhosted.org/packages/c8/2e/69a517945a81a16bff83e99d2a9ac7aa5eb82f6d75f55dfd56bcf001eeae/conditional_cache-1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 12:20:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Eric-Canas",
"github_project": "ConditionalCache",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "circular-dict",
"specs": []
}
],
"lcname": "conditional-cache"
}
JSON
