feat: add cache_contains() for read-only key lookup (#746)

* feat: add cache_contains method to check cache presence without affecting counters

* docs: update README and tests to include examples for cache_contains method

* refactor: add type hints to coro functions in cache_contains tests

Author: rahulkaushal04

README.rst

@@ -104,6 +104,23 @@ The library supports explicit invalidation for specific function call by
 The method returns `True` if corresponding arguments set was cached already, `False`
 otherwise.
 
+To check whether a specific set of arguments is present in the cache without
+affecting hit/miss counters or LRU ordering, use `cache_contains()`:
+
+.. code-block:: python
+
+    @alru_cache(maxsize=32)
+    async def func(arg1, arg2):
+        return arg1 + arg2
+
+    await func(1, arg2=2)
+
+    func.cache_contains(1, arg2=2)  # True
+    func.cache_contains(3, arg2=4)  # False
+
+The method returns `True` if the result for the given arguments is cached, `False`
+otherwise.
+
 Limitations
 -----------
 

async_lru/__init__.py

@@ -150,6 +150,14 @@ def _check_loop(self, loop: asyncio.AbstractEventLoop) -> None:
             self.cache_clear()
             self.__first_loop = loop
 
+    def cache_contains(self, /, *args: Hashable, **kwargs: Any) -> bool:
+        """Check if the given arguments are in the cache.
+
+        Does not affect hit/miss counters or LRU ordering.
+        """
+        key = _make_key(args, kwargs, self.__typed)
+        return key in self.__cache
+
     def cache_invalidate(self, /, *args: Hashable, **kwargs: Any) -> bool:
         key = _make_key(args, kwargs, self.__typed)
 
@@ -326,6 +334,9 @@ def __init__(
         self.__instance = instance
         self.__wrapper = wrapper
 
+    def cache_contains(self, /, *args: Hashable, **kwargs: Any) -> bool:
+        return self.__wrapper.cache_contains(self.__instance, *args, **kwargs)
+
     def cache_invalidate(self, /, *args: Hashable, **kwargs: Any) -> bool:
         return self.__wrapper.cache_invalidate(self.__instance, *args, **kwargs)
 

tests/test_cache_contains.py

@@ -0,0 +1,131 @@
+import asyncio
+from typing import Callable
+
+from async_lru import alru_cache
+
+
+async def test_cache_contains_basic(check_lru: Callable[..., None]) -> None:
+    @alru_cache(maxsize=4)
+    async def coro(val: int) -> int:
+        return val
+
+    assert coro.cache_contains(1) is False
+    await coro(1)
+    assert coro.cache_contains(1) is True
+    assert coro.cache_contains(2) is False
+    check_lru(coro, hits=0, misses=1, cache=1, tasks=0, maxsize=4)
+
+
+async def test_cache_contains_does_not_affect_counters(
+    check_lru: Callable[..., None],
+) -> None:
+    @alru_cache(maxsize=4)
+    async def coro(val: int) -> int:
+        return val
+
+    await coro(1)
+    for _ in range(10):
+        coro.cache_contains(1)
+        coro.cache_contains(99)
+
+    # hits/misses must stay unchanged after cache_contains calls
+    check_lru(coro, hits=0, misses=1, cache=1, tasks=0, maxsize=4)
+
+
+async def test_cache_contains_does_not_change_lru_order() -> None:
+    @alru_cache(maxsize=2)
+    async def coro(val: int) -> int:
+        return val
+
+    await coro(1)
+    await coro(2)
+
+    # Peek at key 1 without refreshing its LRU position
+    assert coro.cache_contains(1) is True
+
+    # Adding a third entry must evict key 1 (oldest), not key 2
+    await coro(3)
+
+    assert coro.cache_contains(1) is False
+    assert coro.cache_contains(2) is True
+    assert coro.cache_contains(3) is True
+
+
+async def test_cache_contains_after_invalidate_and_clear() -> None:
+    @alru_cache(maxsize=4)
+    async def coro(val: int) -> int:
+        return val
+
+    await coro(1)
+    await coro(2)
+
+    coro.cache_invalidate(1)
+    assert coro.cache_contains(1) is False
+    assert coro.cache_contains(2) is True  # unaffected
+
+    coro.cache_clear()
+    assert coro.cache_contains(2) is False
+
+
+async def test_cache_contains_with_kwargs() -> None:
+    @alru_cache(maxsize=4)
+    async def coro(a: int, b: int = 10) -> int:
+        return a + b
+
+    await coro(1, b=20)
+    assert coro.cache_contains(1, b=20) is True
+    assert coro.cache_contains(1, b=30) is False
+    assert coro.cache_contains(1) is False
+
+
+async def test_cache_contains_respects_typed_flag() -> None:
+    @alru_cache(maxsize=4, typed=True)
+    async def coro(val: int) -> int:
+        return val
+
+    await coro(1)
+    assert coro.cache_contains(1) is True
+    assert coro.cache_contains(1.0) is False
+
+
+async def test_cache_contains_pending_task() -> None:
+    event = asyncio.Event()
+
+    @alru_cache(maxsize=4)
+    async def coro(val: int) -> int:
+        await event.wait()
+        return val
+
+    task = asyncio.ensure_future(coro(1))
+    await asyncio.sleep(0)
+
+    # Key must be present even while the underlying task is still running
+    assert coro.cache_contains(1) is True
+
+    event.set()
+    await task
+
+
+async def test_cache_contains_after_ttl_expiry() -> None:
+    @alru_cache(maxsize=4, ttl=0.05)
+    async def coro(val: int) -> int:
+        return val
+
+    await coro(1)
+    assert coro.cache_contains(1) is True
+
+    await asyncio.sleep(0.1)
+    assert coro.cache_contains(1) is False
+
+
+async def test_cache_contains_on_method() -> None:
+    class MyService:
+        @alru_cache(maxsize=4)
+        async def fetch(self, key: int) -> int:
+            return key * 2
+
+    svc = MyService()
+    await svc.fetch(5)
+
+    assert svc.fetch.cache_contains(5) is True
+    assert svc.fetch.cache_contains(6) is False