Opened 2 months ago
Last modified 2 months ago
#35745 closed Uncategorized
Improve Documentation on Clearing Cached Property Values — at Initial Version
| Reported by: | Jae Hyuck Sa | Owned by: | |
|---|---|---|---|
| Component: | Documentation | Version: | 5.1 |
| Severity: | Normal | Keywords: | |
| Cc: | Triage Stage: | Unreviewed | |
| Has patch: | no | Needs documentation: | no |
| Needs tests: | no | Patch needs improvement: | no |
| Easy pickings: | no | UI/UX: | no |
Description
The process of clearing cached values from Django's cached_property is currently undocumented, even though it is a pattern used extensively throughout the codebase. Developers may not be aware of the best practices for resetting cached properties and might attempt to implement custom methods unnecessarily.
After receiving feedback on a related feature proposal, I now understand that Django will eventually transition to using Python's functools.cached_property once support for Python 3.11 is dropped (see #30949). Therefore, adding a method for clearing the cache directly to cached_property might not be the best course of action. Instead, improving the documentation will ensure developers are aware of the correct method for clearing cached values. The recommended pattern for clearing cached values is:
This pattern is used extensively in the codebase, as seen in the following search results: GitHub Search Results(https://github.com/search?q=repo%3Adjango%2Fdjango+%22__dict__.pop%22&type=code).
Related feature discussion: #35743
Consensus on moving to functools.cached_property: #30949