✅ PR preview is ready!

• fix(cache): preserve on_release behavior in TTLCleanupCache.clear() #14180 👈 (View in Graphite)
• develop

This stack of pull requests is managed by Graphite. Learn more about stacking.

✅ 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.

Summary

This PR fixes a regression introduced by cachetools 7.0.2, which changed TTLCache.clear() to an O(1) implementation that directly clears internal storage, bypassing popitem(). This broke TTLCleanupCache's on_release hook, which relies on popitem() to trigger cleanup callbacks when entries are removed.

The fix adds a clear() override to TTLCleanupCache that iterates via popitem() to preserve on_release semantics. Comment updates in cache_resource_api.py improve documentation clarity around the exception-handling behavior of the per-item clearing loop.

Code Quality

The implementation is clean, minimal, and well-documented:

• ttl_cleanup_cache.py (lines 78-95): The new clear() override uses @override from typing_extensions, includes a thorough docstring explaining the rationale (cachetools 7.0.2 behavior change), and uses the idiomatic while True / except KeyError pattern that matches how popitem() signals an empty cache.
• cache_resource_api.py (lines 707-715): The updated comments are clearer than the originals, accurately describing the exception-stopping behavior of TTLCleanupCache.clear() and why per-item cleanup is still used at the ResourceCache level.

One subtle edge case worth noting: if a user-provided on_release callback raises KeyError, the except KeyError in TTLCleanupCache.clear() would catch it and stop clearing prematurely. In practice this is very low risk because (1) the primary clearing path through ResourceCache._clear() catches all exceptions individually, and (2) user callbacks raising KeyError is an unusual pattern. This is not a blocker.

Test Coverage

Test coverage is adequate:

• ttl_cleanup_cache_test.py::test_clear_calls_on_release (line 95): This existing test directly covers the exact bug by adding 5 items, calling clear(), and asserting all items were released via on_release. Without the new clear() override, this test would fail on cachetools >= 7.0.2.
• cache_resource_api_test.py::test_on_release_fires (line 235): Tests the higher-level st.cache_resource.clear() path including on_release invocations.
• cache_resource_api_test.py::test_on_release_fires_when_cleared_with_exceptions (line 256): Tests that all on_release callbacks fire even when some raise exceptions, via the per-item loop in ResourceCache._clear().

The PR description says "Covered by existing tests," which is accurate. The existing tests already validate the expected behavior; the fix ensures they continue to pass with cachetools 7.0.2+.

Backwards Compatibility

No breaking changes. The fix is purely defensive:

• The clear() override preserves the exact same semantics that existed before cachetools 7.0.2 (items are evicted one-by-one via popitem(), triggering on_release for each).
• The cachetools version constraint (>=5.5,<8) already allows 7.0.2, so this fix is necessary for compatibility across the supported range.
• No public API changes.

Security & Risk

No security concerns. The change is limited to internal cache cleanup logic with no impact on authentication, networking, or data handling. The regression risk is very low given the existing test coverage.

External test recommendation

• Recommend external_test: No
• Triggered categories: None
• Evidence:
  • lib/streamlit/runtime/caching/ttl_cleanup_cache.py: Internal cache cleanup logic only, no routing, auth, websocket, embedding, asset serving, CORS, storage, or security header changes.
  • lib/streamlit/runtime/caching/cache_resource_api.py: Comment-only changes, no behavioral modifications.
• Suggested external_test focus areas: N/A
• Confidence: High
• Assumptions and gaps: None. The changes are entirely internal to the caching subsystem with no external-facing behavior changes.

Accessibility

No frontend changes; accessibility is not applicable.

Recommendations

No blocking issues. One optional suggestion:

1. Optional — guard against KeyError from on_release: The except KeyError in TTLCleanupCache.clear() could theoretically catch a KeyError raised by the _on_release callback rather than by popitem() on an empty cache. A more defensive approach would be to check len(self) > 0 instead of relying on KeyError:

   def clear(self) -> None:
       while len(self) > 0:
           self.popitem()

   This is a very minor edge case and not a blocker, especially since the primary clearing path in ResourceCache._clear() already handles exceptions individually.

Verdict

APPROVED: Clean, minimal fix that correctly preserves on_release semantics against a cachetools 7.0.2 regression, with adequate existing test coverage and no backwards compatibility concerns.

This is an automated AI review by opus-4.6-thinking.

⚠️ AI Review Failed

The AI review job failed to complete. Please check the workflow run for details.

You can retry by adding the 'ai-review' label again or manually triggering the workflow.

I'm going to merge this to get the CI unblocked