conditional-cache

library1.5pypypi✓ verified 86d ago

Conditional Cache is a Python library that provides a decorator for conditionally caching function results. It wraps `functools.lru_cache`, allowing caching only if a specified `condition_func` returns `True` based on the function's output. The current version is 1.4, and its release cadence is driven by bug fixes and feature enhancements, maintaining a stable API.

database

pip install conditional-cache

github ↗package ↗

INSTALL

IMPORT

SIG · CONDITIONAL-CACHE

conditional-cache

databasepythonv1.5

Install

1.6s avg

Import

15ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.015s · 17.9MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 1.6s · import 0.014s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

conditional_cache

✓ from conditional_cache import conditional_cache

This example demonstrates how to use the `conditional_cache` decorator. The `compute_value` function will only cache its result if the `cache_if_positive` function returns `True` for that result. Notice how `compute_value(-1, 0)` is computed twice because its result ( -1) does not satisfy the caching condition.

from conditional_cache import conditional_cache import time # Define a condition: only cache results greater than 0 def cache_if_positive(result): return result > 0 @conditional_cache(condition_func=cache_if_positive, maxsize=128) def compute_value(x, y): print(f"Computing {x} + {y}...") time.sleep(0.1) # Simulate work return x + y print("--- First call (result > 0, should cache) ---") print(f"Result: {compute_value(1, 2)}") # Computes, caches print(f"Result: {compute_value(1, 2)}") # From cache print("\n--- Second call (result <= 0, should NOT cache) ---") print(f"Result: {compute_value(-1, 0)}") # Computes, does not cache print(f"Result: {compute_value(-1, 0)}") # Computes again print(f"Cache Info: {compute_value.cache_info()}")

Debug

Known issues

gotchaThe `condition_func` must return a boolean value (`True` or `False`). If it returns a non-boolean, a `ValueError` will be raised when the function is called.

fix

Ensure your `condition_func` explicitly returns `True` to cache or `False` to not cache. For example, `lambda result: result is not None`.

affects: All

gotchaArguments to `conditional_cache` (like `maxsize`, `typed`) are passed directly to `functools.lru_cache`. Understand `lru_cache`'s behavior regarding mutable arguments and cache invalidation.

fix

Review `functools.lru_cache` documentation to understand how it handles arguments and what causes cache misses, especially with default `typed=False`.

affects: All

gotchaIf the `condition_func` has side effects or takes a long time to execute, it will impact the performance of every function call, whether cached or not, as it runs *after* the wrapped function and *before* the caching decision.

fix

Design your `condition_func` to be lightweight, pure, and quick to execute. Avoid complex logic or external calls within it.

affects: All

Errors

Common errors & fixes

TypeError: conditional_cache() missing 1 required positional argument: 'condition_func'

The `@conditional_cache` decorator requires the `condition_func` keyword argument to be explicitly provided.

fix

Always pass a function or lambda to `condition_func` within the decorator, e.g., `@conditional_cache(condition_func=my_condition_func)`.

ValueError: The `condition_func` must return a boolean value.

Your `condition_func` returned a value that is not `True` or `False` (e.g., `None`, an integer, a string).

fix

Modify your `condition_func` to guarantee a `True` or `False` return. For instance, `return result is not None` instead of `return result` if `result` could be `None`.

AttributeError: 'function' object has no attribute 'cache_info'

You are trying to access `cache_info()` or `cache_clear()` on a non-decorated function or before the decorator has been correctly applied/initialized.

fix

Ensure the function is correctly decorated with `@conditional_cache(...)` and that you are calling these methods on the decorated function object, e.g., `my_function.cache_info()`.

Upgrade

Version history

1.5latest on PyPI · released May 21, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Eric-Canas/ConditionalCache ↗

packagehttps://pypi.org/project/conditional-cache/ ↗