Add argument-specific cache clearing

Author: shaypal5

README.rst

@@ -133,6 +133,15 @@ The Cachier wrapper adds a ``clear_cache()`` function to each wrapped function.
 
   foo.clear_cache()
 
+To clear only the cache entry for a specific call, pass the same arguments to ``clear_cache()`` that you would pass to the wrapped function:
+
+.. code-block:: python
+
+  foo.clear_cache(arg1, arg2)
+  foo.clear_cache(arg1, arg2=arg2)
+
+The asynchronous ``aclear_cache()`` helper supports the same argument-specific form.
+
 General Configuration
 ----------------------
 

src/cachier/core.py

@@ -48,9 +48,9 @@ class _CachierWrappedFunc(Protocol[_P, _R_co]):
 
     def __call__(self, *args: _P.args, **kwargs: _P.kwargs) -> _R_co: ...  # pragma: no cover
 
-    clear_cache: Callable[[], Any]
+    clear_cache: Callable[..., Any]
     clear_being_calculated: Callable[[], Any]
-    aclear_cache: Callable[[], Any]
+    aclear_cache: Callable[..., Any]
     aclear_being_calculated: Callable[[], Any]
     cache_dpath: Callable[[], Optional[str]]
     precache_value: Callable[..., Any]
@@ -219,6 +219,13 @@ def _is_async_redis_client(client: Any) -> bool:
     return all(inspect.iscoroutinefunction(getattr(client, name, None)) for name in method_names)
 
 
+def _convert_public_cache_args(func, _is_method: bool, args: tuple, kwds: dict) -> dict:
+    """Convert cache-management arguments to canonical cache-key kwargs."""
+    if _is_method:
+        args = (None, *args)
+    return _convert_args_kwargs(func, _is_method=_is_method, args=args, kwds=kwds)
+
+
 def cachier(
     hash_func: Optional[HashFunc] = None,
     hash_params: Optional[HashFunc] = None,
@@ -733,9 +740,14 @@ async def func_wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
             def func_wrapper(*args: _P.args, **kwargs: _P.kwargs) -> _R:
                 return _call(*args, **kwargs)  # type: ignore[arg-type]
 
-        def _clear_cache():
-            """Clear the cache."""
-            core.clear_cache()
+        def _clear_cache(*args, **kwds):
+            """Clear the cache, or only the entry matching the provided arguments."""
+            if args or kwds:
+                kwargs = _convert_public_cache_args(func, core.func_is_method, args, kwds)
+                key = core.get_key((), kwargs)
+                core.clear_cache_entry(key)
+            else:
+                core.clear_cache()
             if is_coroutine:
                 return _ImmediateAwaitable()
             return None
@@ -747,9 +759,14 @@ def _clear_being_calculated():
                 return _ImmediateAwaitable()
             return None
 
-        async def _aclear_cache():
-            """Clear the cache asynchronously."""
-            await core.aclear_cache()
+        async def _aclear_cache(*args, **kwds):
+            """Clear the cache asynchronously, or only the entry matching the provided arguments."""
+            if args or kwds:
+                kwargs = _convert_public_cache_args(func, core.func_is_method, args, kwds)
+                key = core.get_key((), kwargs)
+                await core.aclear_cache_entry(key)
+            else:
+                await core.aclear_cache()
 
         async def _aclear_being_calculated():
             """Mark all entries in this cache as not being calculated asynchronously."""

src/cachier/cores/base.py

@@ -274,6 +274,18 @@ async def aclear_cache(self) -> None:
         """
         await asyncio.to_thread(self.clear_cache)
 
+    @abc.abstractmethod
+    def clear_cache_entry(self, key: str) -> None:
+        """Clear the cache entry mapped by the given key."""
+
+    async def aclear_cache_entry(self, key: str) -> None:
+        """Async-compatible variant of :meth:`clear_cache_entry`.
+
+        By default this runs in a thread to avoid blocking the event loop.
+
+        """
+        await asyncio.to_thread(self.clear_cache_entry, key)
+
     @abc.abstractmethod
     def clear_being_calculated(self) -> None:
         """Mark all entries in this cache as not being calculated."""

src/cachier/cores/memory.py

@@ -126,6 +126,11 @@ def clear_cache(self) -> None:
             # Update size metrics after clearing
             self._update_size_metrics()
 
+    def clear_cache_entry(self, key: str) -> None:
+        with self.lock:
+            self.cache.pop(self._hash_func_key(key), None)
+            self._update_size_metrics()
+
     def clear_being_calculated(self) -> None:
         with self.lock:
             for entry in self.cache.values():

src/cachier/cores/mongo.py

@@ -249,6 +249,14 @@ async def aclear_cache(self) -> None:
         mongo_collection = await self._ensure_collection_async()
         await mongo_collection.delete_many(filter={"func": self._func_str})
 
+    def clear_cache_entry(self, key: str) -> None:
+        mongo_collection = self._ensure_collection()
+        mongo_collection.delete_one(filter={"func": self._func_str, "key": key})
+
+    async def aclear_cache_entry(self, key: str) -> None:
+        mongo_collection = await self._ensure_collection_async()
+        await mongo_collection.delete_one(filter={"func": self._func_str, "key": key})
+
     def clear_being_calculated(self) -> None:
         mongo_collection = self._ensure_collection()
         mongo_collection.update_many(

src/cachier/cores/pickle.py

@@ -416,6 +416,17 @@ def clear_cache(self) -> None:
         else:
             self._save_cache({})
 
+    def clear_cache_entry(self, key: str) -> None:
+        if self.separate_files:
+            with suppress(FileNotFoundError):
+                os.remove(f"{self.cache_fpath}_{key}")
+            return
+
+        with self.lock:
+            cache = self.get_cache_dict()
+            cache.pop(key, None)
+            self._save_cache(cache)
+
     def clear_being_calculated(self) -> None:
         if self.separate_files:
             self._clear_being_calculated_all_cache_files()

src/cachier/cores/redis.py

@@ -353,6 +353,16 @@ def clear_cache(self) -> None:
         except Exception as e:
             warnings.warn(f"Redis clear_cache failed: {e}", stacklevel=2)
 
+    def clear_cache_entry(self, key: str) -> None:
+        """Clear the cache entry mapped by the given key."""
+        redis_client = self._resolve_redis_client()
+        redis_key = self._get_redis_key(key)
+
+        try:
+            redis_client.delete(redis_key)
+        except Exception as e:
+            warnings.warn(f"Redis clear_cache_entry failed: {e}", stacklevel=2)
+
     async def aclear_cache(self) -> None:
         """Clear the cache of this core asynchronously."""
         redis_client = await self._resolve_redis_client_async()
@@ -365,6 +375,16 @@ async def aclear_cache(self) -> None:
         except Exception as e:
             warnings.warn(f"Redis clear_cache failed: {e}", stacklevel=2)
 
+    async def aclear_cache_entry(self, key: str) -> None:
+        """Clear the cache entry mapped by the given key asynchronously."""
+        redis_client = await self._resolve_redis_client_async()
+        redis_key = self._get_redis_key(key)
+
+        try:
+            await redis_client.delete(redis_key)
+        except Exception as e:
+            warnings.warn(f"Redis clear_cache_entry failed: {e}", stacklevel=2)
+
     def clear_being_calculated(self) -> None:
         """Mark all entries in this cache as not being calculated."""
         redis_client = self._resolve_redis_client()

src/cachier/cores/s3.py

@@ -333,6 +333,15 @@ def clear_cache(self) -> None:
         except Exception as exc:
             _safe_warn(f"S3 clear_cache failed: {exc}")
 
+    def clear_cache_entry(self, key: str) -> None:
+        """Delete the cache entry mapped by the given key from S3."""
+        client = self._get_s3_client()
+        s3_key = self._get_s3_key(key)
+        try:
+            client.delete_object(Bucket=self.s3_bucket, Key=s3_key)
+        except Exception as exc:
+            _safe_warn(f"S3 clear_cache_entry failed: {exc}")
+
     def clear_being_calculated(self) -> None:
         """Reset the ``_processing`` flag on all entries for this function in S3."""
         client = self._get_s3_client()

src/cachier/cores/sql.py

@@ -434,12 +434,28 @@ def clear_cache(self) -> None:
             session.execute(delete(CacheTable).where(CacheTable.function_id == self._func_str))
             session.commit()
 
+    def clear_cache_entry(self, key: str) -> None:
+        session_factory = self._get_sync_session()
+        with self._lock, session_factory() as session:
+            session.execute(
+                delete(CacheTable).where(and_(CacheTable.function_id == self._func_str, CacheTable.key == key))
+            )
+            session.commit()
+
     async def aclear_cache(self) -> None:
         session_factory = await self._get_async_session()
         async with session_factory() as session:
             await session.execute(delete(CacheTable).where(CacheTable.function_id == self._func_str))
             await session.commit()
 
+    async def aclear_cache_entry(self, key: str) -> None:
+        session_factory = await self._get_async_session()
+        async with session_factory() as session:
+            await session.execute(
+                delete(CacheTable).where(and_(CacheTable.function_id == self._func_str, CacheTable.key == key))
+            )
+            await session.commit()
+
     def clear_being_calculated(self) -> None:
         session_factory = self._get_sync_session()
         with self._lock, session_factory() as session:

tests/mongo_tests/test_mongo_core.py

@@ -139,6 +139,28 @@ def _test_mongo_caching(arg_1, arg_2):
     assert val6 == val5
 
 
+@pytest.mark.mongo
+def test_mongo_clear_cache_for_specific_arguments():
+    """clear_cache can remove one Mongo cache entry by function arguments."""
+
+    @cachier(mongetter=_test_mongetter)
+    def _test_mongo_caching(arg_1, arg_2):
+        """Some function."""
+        return random() + arg_1 + arg_2
+
+    _test_mongo_caching.clear_cache()
+    val1 = _test_mongo_caching(1, arg_2=2)
+    val2 = _test_mongo_caching(3, arg_2=4)
+    assert _test_mongo_caching(1, arg_2=2) == val1
+    assert _test_mongo_caching(3, arg_2=4) == val2
+
+    _test_mongo_caching.clear_cache(1, arg_2=2)
+
+    assert _test_mongo_caching(1, arg_2=2) != val1
+    assert _test_mongo_caching(3, arg_2=4) == val2
+    _test_mongo_caching.clear_cache()
+
+
 @pytest.mark.mongo
 def test_mongo_stale_after():
     """Testing MongoDB core stale_after functionality."""