✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

✅ PR preview is ready!

@cursor review

Summary

This PR adds a new TTLCleanupCache class that extends cachetools.TTLCache to support release hooks (callbacks) when items are removed from the cache. This is foundational infrastructure for implementing session-scoped connections and cache expiration hooks as described in the linked spec. The PR also bumps the minimum cachetools version from 4.0 to 5.5, which is required because the expire() method only returns expired items starting in version 5.5.

Key changes:

• New file: lib/streamlit/runtime/caching/ttl_cleanup_cache.py - TTLCleanupCache class
• New file: lib/tests/streamlit/runtime/caching/ttl_cleanup_cache_test.py - Unit tests
• Added OnRelease type alias to cache_utils.py
• Bumped cachetools minimum version from 4.0 to 5.5

Code Quality

Issues Found:

1. Missing from __future__ import annotations in lib/streamlit/runtime/caching/ttl_cleanup_cache.py (line 1-27)

   All other files in the lib/streamlit/runtime/caching/ directory include this import. This is a codebase standard that should be followed for consistency and forward compatibility.

2. Missing from __future__ import annotations in lib/tests/streamlit/runtime/caching/ttl_cleanup_cache_test.py

   All other test files in the same directory include this import.

3. Test file lacks complete type annotations

   According to the Python unit test guide: "New tests should be fully annotated with types." The test class TestTTLCleanupCache is missing return type annotations on test methods (should be -> None).

Suggestions:

4. Incomplete on_release coverage for manual removal operations

   The implementation only overrides popitem() and expire(), which handle automatic evictions (LRU and TTL). However, manual removal operations (clear(), del cache[key], pop(key)) will NOT call on_release.

   The spec states: "This will be called whenever an item is removed from the cache, including via clear calls."

   If this is intentional (only handling automatic evictions), this behavior should be clearly documented in the class docstring. If not, consider overriding __delitem__, pop, and clear methods as well.

5. Exception handling in on_release

   Consider what happens if the on_release callback raises an exception. Currently, an exception would propagate up and could leave the cache in an inconsistent state (e.g., in expire(), some items might have been released while others haven't). Consider wrapping on_release calls in try/except with logging.

Test Coverage

The tests cover the two main automatic eviction scenarios:

• ✅ LRU eviction when cache hits size limit (test_releases_when_hits_size)
• ✅ TTL expiration (test_releases_when_hits_ttl)

Missing Test Cases:

1. Empty cache behavior - What happens when expire() is called on an empty cache?
2. Manual deletion - Tests for del cache[key], cache.pop(key), and cache.clear() to document whether they trigger on_release (even if the answer is "no, they don't")
3. Exception in on_release - Verify the behavior when the callback raises an exception

Backwards Compatibility

⚠️ Breaking Change: cachetools version bump from 4.0 to 5.5

This is a significant version jump. Users who have cachetools==4.x pinned in their requirements may experience dependency resolution failures when upgrading Streamlit.

The bump is necessary because:

• The expire() method in TTLCache only returns expired items starting in cachetools 5.5
• Earlier versions (4.x, 5.0-5.4) either don't have expire() or it returns None

Recommendation: Consider adding a note in the PR description or release notes about this dependency change.

Security & Risk

• Low risk: This is internal infrastructure with no direct user-facing API changes
• No security concerns: The code doesn't handle sensitive data or external inputs
• Regression risk is minimal: The new class is additive and existing cache implementations are unchanged

Recommendations

Required (blocking):

1. Add from __future__ import annotations to the top of lib/streamlit/runtime/caching/ttl_cleanup_cache.py (after the license header)

2. Add from __future__ import annotations to the top of lib/tests/streamlit/runtime/caching/ttl_cleanup_cache_test.py (after the license header)

3. Add return type annotations (-> None) to test methods in the test file

Recommended (non-blocking):

4. Clarify in the TTLCleanupCache docstring that on_release is only called for automatic evictions (LRU/TTL), not manual deletions - OR implement __delitem__, pop, and clear overrides to call on_release for all removal operations

5. Consider wrapping self._on_release(value) calls in try/except to prevent callback exceptions from breaking cache operations:

   def _safe_release(self, value: V) -> None:
       try:
           self._on_release(value)
       except Exception:
           _LOGGER.exception("Error in on_release callback")

6. Add edge case tests for empty cache behavior and document the behavior when manual deletion methods are used

Verdict

CHANGES REQUESTED: The PR is well-structured and the implementation is solid, but it needs to conform to codebase standards by adding from __future__ import annotations to both new files and adding proper type annotations to the test methods. These are straightforward fixes that should be addressed before merging.

This is an automated AI review. Please verify the feedback and use your judgment.

Overall, lgtm 👍 but I think these two aspects from the AI review are probably valid:

Consider what happens if the on_release callback raises an exception. Currently, an exception would propagate up and could leave the cache in an inconsistent state

It might be good to ensure that the cache is always cleaned, but I'm unsure whether we should simply log the error to the console or display it to the user.

The implementation only overrides popitem() and expire(), which handle automatic evictions (LRU and TTL). However, manual removal operations (clear(), del cache[key], pop(key)) will NOT call on_release.

Based on the spec, we likely want to call on_release whenever the item is cleaned through any method?

Consider what happens if the on_release callback raises an exception. Currently, an exception would propagate up and could leave the cache in an inconsistent state

This is not how the base class works.

The implementation only overrides popitem() and expire(), which handle automatic evictions (LRU and TTL). However, manual removal operations (clear(), del cache[key], pop(key)) will NOT call on_release.

I already replied to the AI on this, but it doesn't seem smart enough to listen to older comments. The base class handles this.

an uncaught exception error is shown to the user?

We'll be catching it and wrapping it if possible - but yes, it would end up shown to the user. The wrapping will happen in a higher layer.