Improve cache hit/miss reporting for cache.get()

[Harsh3006]

Description

This change fixes incorrect cache hit/miss reporting in the Cache panel for cache.get().

Previously, the Cache panel determined whether a cache.get() call was a hit or a miss solely based on whether the returned value was None. This resulted in two incorrect scenarios:

A missing key with a supplied default (for example, cache.get("missing", "default")) was reported as a cache hit, even though the value was not retrieved from the cache.
A cached value of None was reported as a cache miss, even though the key existed in the cache.

The Cache panel now correctly distinguishes between a missing cache key and a cached value equal to the caller's supplied default while preserving the existing cache.get() behavior.

Fixes #2417

Checklist:

• I have added the relevant tests for this change.
• I have added an item to the Pending section of docs/changes.rst.

AI/LLM Usage

• This PR includes code generated with the help of an AI/LLM

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
debug_toolbar
_compat.py
apps.py
middleware.py
toolbar.py
debug_toolbar/panels
cache.py					127
profiling.py
redirects.py
debug_toolbar/panels/sql
views.py
Project Total

This report was generated by python-coverage-comment-action

[Harsh3006]

@mgstabrani I noticed that CI was still flagging the self.misses += 1 branch for get_or_set() as uncovered. I've added a test for the None return path in a follow-up commit to close the remaining coverage gap.

No get_or_set() logic was changed; this only adds the missing test coverage.

[tim-schilling]

I appreciate the time and effort @Harsh3006, but I think this implementation isn't something we can adopt. I'm open to alternative solutions or ideas, but this as is, I'm not onboard with right now.

This changes what the user is doing and could have downstream effects in people's applications. For example, if someone has another observability tool implemented underneath the toolbar that counts the unique default values passed in, we would break that functionality. And it would break silently while being extremely difficult to debug. They would see some random memory address being passed as the default which would be hard to search on. They'd have to audit all the packages that do something related to caching to track it down to us, and when they do, I suspect they'll be a little upset 😅

Shorter version: The toolbar shouldn't be making changes to function calls without permission from the user.

[Harsh3006]

Thanks @tim-schilling for the explanation. That makes sense. I hadn't considered the effect on downstream instrumentation that may observe the original call arguments.

I spent some more time looking for an alternative that could solve this without modifying the actual cache.get() call, but I couldn't find a fully reliable solution. It seems this is a limitation of the current API: once cache.get() returns, there isn't enough information to determine whether the returned value came from the cache or from the supplied default.

One alternative I considered was comparing the returned value with the supplied default instead of checking for None. This would correctly identify a miss when the key is missing and a non-None default is provided. However, it only shits the ambiguity rather than eliminating it: it would incorrectly report a miss when the cached value happens to be equal to the supplied default.

I also cross-checked this approach against the current test suite, and as expected, these two tests fail:

• test_cached_none_counts_as_hit
• test_cached_value_equal_to_default_counts_as_hit

At this point, the sentinel approach seems to be the only approach I've found that can distinguish these cases reliably, but I understand the concern about modifying the arguments passed to the wrapped function.

[Harsh3006]

@tim-schilling Here are the screenshots showing the template and documentation changes, including a note on the remaining ambiguity and a link to the open discussion.

Updated Cache Panel:

Updated Documentation: