Improve Documentation on Clearing Cached Property Values

[Jae Hyuck Sa]

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

Feedback and suggestions from the community are greatly appreciated!