Add a method to cached_property for clearing its cached value

[Jae Hyuck Sa]

I would like to propose an enhancement to Django's cached_property. Currently, cached_property does not provide a built-in way to clear its cached value from an instance. To reset the cached value, developers must manually delete the property from the instance's dict.

This proposal was inspired by a suggestion made by Jacob Tyler Walls on this pull request(​https://github.com/django/django/pull/18534#:~:text=5%20days%20ago-,jacobtylerwalls%20reviewed%204%20days%20ago,-View%20reviewed%20changes), where it was recommended to expose this functionality on cached_property rather than implementing it individually for each property.

By incorporating this functionality, developers can avoid implementing custom methods for each property, which will promote cleaner and more maintainable code.

Feedback and suggestions from the community are greatly appreciated!

[Simon Charette]

Given that there appears to be a consensus to move to functools.cached_property once we drop support for Python 3.11 (see #30949) I would see the addition of this method as a step that prevents us from doing that.

What benefits are there in doing

SomeClass.some_cached_property.clear_cache(some_class_instance)

over

some_class_instance.__dict__.pop("some_cached_property", None)

when you can't be sure the property has been cached and del or delattr otherwise?

It is a pattern ​used extensively in the code base but that we could admittedly document better (#30278)

[Jae Hyuck Sa]

Replying to Simon Charette:

Given that there appears to be a consensus to move to functools.cached_property once we drop support for Python 3.11 (see #30949) I would see the addition of this method as a step that prevents us from doing that.

What benefits are there in doing

SomeClass.some_cached_property.clear_cache(some_class_instance)

over

some_class_instance.__dict__.pop("some_cached_property", None)

when you can't be sure the property has been cached and del or delattr otherwise?

It is a pattern ​used extensively in the code base but that we could admittedly document better (#30278)

Thank you for your feedback. I was not aware of the consensus to move to functools.cached_property once support for Python 3.11 is dropped (see #30949). I understand that adding a method to clear the cache directly on cached_property might hinder this transition. Additionally, I used del because I assumed that the property would always have a cached value. I now realize that there is a standardized pattern for clearing cached properties, which I was not aware of before. I appreciate the feedback and, after considering your points, I agree that better documentation is the appropriate approach. I will raise a new issue to address this in the documentation.

Thank you again for your valuable input.