Emit AlruCacheLoopResetWarning on event loop auto-reset

[rodrigobnogueira]

What do these changes do?

Adds a AlruCacheLoopResetWarning (a UserWarning subclass) that is emitted once per cache instance when _check_loop detects an event loop change and auto-clears stale entries.

This follows up on #743, which changed the behavior from raising RuntimeError to silently clearing and rebinding. The warning closes the gap: users who accidentally share a cache across loops in production will now see a clear message without anything breaking.

Users can suppress it cleanly:

# pytest.ini / setup.cfg
filterwarnings = ignore::async_lru.AlruCacheLoopResetWarning

Are there changes in behavior for the user?

Yes. A AlruCacheLoopResetWarning is now emitted on the first event loop change per cache instance. It does not affect functionality — the auto-reset still works exactly as before.

Is it a substantial change?

No. Adds a warning class, a boolean flag, and a warnings.warn() call.

Related issue number

Follow-up to #743 (which closed #611 and #742)

Checklist

• I think the code is well written
• Unit tests for the changes exist
• Documentation reflects the changes
• Add a new news fragment into the CHANGES folder

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.55%. Comparing base (fff4d49) to head (cbdedb1).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #744      +/-   ##
==========================================
+ Coverage   97.45%   97.55%   +0.09%     
==========================================
  Files          15       15              
  Lines        1022     1063      +41     
  Branches       57       59       +2     
==========================================
+ Hits          996     1037      +41     
  Misses         23       23              
  Partials        3        3              

Flag	Coverage Δ
unit	96.51% <100.00%> (+0.13%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[codspeed-hq]

Merging this PR will not alter performance

✅ 63 untouched benchmarks
⏩ 4 skipped benchmarks¹

---

_{Comparing rodrigobnogueira:fix/loop-reset-warning (cbdedb1) with master (fff4d49)}

Footnotes

1. 4 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[rodrigobnogueira]

Demo:

import asyncio
from async_lru import alru_cache

@alru_cache(maxsize=32)
async def fetch_data(item_id: int) -> str:
    print(f"Fetching {item_id}...")
    await asyncio.sleep(0.1)
    return f"Data for {item_id}"

async def main() -> None:
    # First loop usage
    await fetch_data(1)
    await fetch_data(1)

if __name__ == "__main__":
    print("--- Running on Event Loop 1 ---")
    asyncio.run(main())

    print("\n--- Running on Event Loop 2 (Should trigger warning) ---")
    asyncio.run(main())

    print("\n--- Running on Event Loop 3 (Should NOT trigger warning) ---")
    asyncio.run(main())

Output:

--- Running on Event Loop 1 ---
Fetching 1...
--- Running on Event Loop 2 (Should trigger warning) ---
/tmp/demo_warning.py:14: AlruCacheLoopResetWarning: alru_cache detected event loop change and auto-cleared stale entries. This is safe but unusual outside of tests (pytest-anyio, etc.).
  await fetch_data(1)
Fetching 1...
--- Running on Event Loop 3 (Should NOT trigger warning) ---
Fetching 1...