feat: emit AlruCacheLoopResetWarning on event loop auto-reset

Add a UserWarning subclass that fires once per cache instance when
_check_loop detects an event loop change and auto-clears stale entries.
This helps users notice accidental multi-loop usage in production
without breaking anything.

Follow-up to #743.

Author: rodrigo.nogueira

async_lru/__init__.py

@@ -3,6 +3,7 @@
 import inspect
 import random
 import sys
+import warnings
 from functools import _CacheInfo, _make_key, partial, partialmethod
 from typing import (
     Any,
@@ -34,7 +35,7 @@
 
 __version__ = "2.2.0"
 
-__all__ = ("alru_cache",)
+__all__ = ("AlruCacheLoopResetWarning", "alru_cache")
 
 
 _T = TypeVar("_T")
@@ -44,6 +45,9 @@
 _CBP = Union[_CB[_R], "partial[_Coro[_R]]", "partialmethod[_Coro[_R]]"]
 
 
+class AlruCacheLoopResetWarning(UserWarning):
+    """Emitted once per cache instance when a loop change triggers an auto-reset."""
+
 @final
 class _CacheParameters(TypedDict):
     typed: bool
@@ -113,6 +117,7 @@ def __init__(
         self.__hits = 0
         self.__misses = 0
         self.__first_loop: Optional[asyncio.AbstractEventLoop] = None
+        self.__warned_loop_reset = False
 
     @property
     def __tasks(self) -> List["asyncio.Task[_R]"]:
@@ -130,6 +135,15 @@ def _check_loop(self, loop: asyncio.AbstractEventLoop) -> None:
         if self.__first_loop is None:
             self.__first_loop = loop
         elif self.__first_loop is not loop:
+            if not self.__warned_loop_reset:
+                warnings.warn(
+                    "alru_cache detected event loop change and auto-cleared "
+                    "stale entries. This is safe but unusual outside of "
+                    "tests (pytest-anyio, etc.).",
+                    AlruCacheLoopResetWarning,
+                    stacklevel=3,
+                )
+                self.__warned_loop_reset = True
             # Old cache entries hold tasks/handles bound to the previous
             # loop and are invalid here.  Clear and rebind.
             self.cache_clear()

tests/test_thread_safety.py

@@ -1,8 +1,11 @@
 import asyncio
+import warnings
 
-from async_lru import alru_cache
+import pytest
 
+from async_lru import AlruCacheLoopResetWarning, alru_cache
 
+@pytest.mark.filterwarnings("ignore::async_lru.AlruCacheLoopResetWarning")
 def test_cross_loop_auto_resets_cache() -> None:
     @alru_cache(maxsize=100)
     async def cached_func(key: str) -> str:
@@ -24,7 +27,7 @@ async def cached_func(key: str) -> str:
     assert cached_func.cache_info().hits == 0
     assert cached_func.cache_info().misses == 1
 
-
+@pytest.mark.filterwarnings("ignore::async_lru.AlruCacheLoopResetWarning")
 def test_cross_loop_preserves_stats_reset() -> None:
     @alru_cache(maxsize=100)
     async def cached_func(key: str) -> str:
@@ -46,7 +49,7 @@ async def cached_func(key: str) -> str:
     assert cached_func.cache_info().hits == 0
     assert cached_func.cache_info().misses == 1
 
-
+@pytest.mark.filterwarnings("ignore::async_lru.AlruCacheLoopResetWarning")
 def test_invalid_key_does_not_bind_loop() -> None:
     @alru_cache(maxsize=100)
     async def cached_func(key: object) -> str:
@@ -139,7 +142,7 @@ async def run_concurrent() -> list[str]:
     assert results == ["data_test"] * 3
     assert cached_func.cache_info().hits == 2
 
-
+@pytest.mark.filterwarnings("ignore::async_lru.AlruCacheLoopResetWarning")
 def test_multiple_loop_transitions() -> None:
     @alru_cache(maxsize=100)
     async def cached_func(key: str) -> str:
@@ -150,3 +153,45 @@ async def cached_func(key: str) -> str:
         result = loop.run_until_complete(cached_func("test"))
         loop.close()
         assert result == "data_test"
+
+
+def test_loop_change_emits_warning() -> None:
+    @alru_cache(maxsize=100)
+    async def cached_func(key: str) -> str:
+        return f"data_{key}"
+
+    loop1 = asyncio.new_event_loop()
+    loop1.run_until_complete(cached_func("test"))
+    loop1.close()
+
+    loop2 = asyncio.new_event_loop()
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter("always")
+        loop2.run_until_complete(cached_func("test"))
+    loop2.close()
+
+    assert len(w) == 1
+    assert issubclass(w[0].category, AlruCacheLoopResetWarning)
+    assert "event loop change" in str(w[0].message)
+
+
+def test_loop_change_warns_only_once() -> None:
+    @alru_cache(maxsize=100)
+    async def cached_func(key: str) -> str:
+        return f"data_{key}"
+
+    all_warnings: list[warnings.WarningMessage] = []
+    for _ in range(4):
+        loop = asyncio.new_event_loop()
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            loop.run_until_complete(cached_func("test"))
+        loop.close()
+        all_warnings.extend(w)
+
+    reset_warnings = [
+        w for w in all_warnings
+        if issubclass(w.category, AlruCacheLoopResetWarning)
+    ]
+    assert len(reset_warnings) == 1
+