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!

[Sarah Boyce]

From what I understand, I think this is documented: ​https://docs.djangoproject.com/en/5.1/ref/utils/#django.utils.functional.cached_property

The cached value can be treated like an ordinary attribute of the instance:

# clear it, requiring re-computation next time it's called
del person.friends  # or delattr(person, "friends")

# set a value manually, that will persist on the instance until cleared
person.friends = ["Huckleberry Finn", "Tom Sawyer"]

[Jae Hyuck Sa]

Replying to Sarah Boyce:

From what I understand, I think this is documented: ​https://docs.djangoproject.com/en/5.1/ref/utils/#django.utils.functional.cached_property

The cached value can be treated like an ordinary attribute of the instance:

# clear it, requiring re-computation next time it's called
del person.friends  # or delattr(person, "friends")

# set a value manually, that will persist on the instance until cleared
person.friends = ["Huckleberry Finn", "Tom Sawyer"]

I appreciate the feedback. While the current documentation mentions using del to clear cached properties, this approach can raise an AttributeError if the property is not already cached.
A more robust pattern, extensively used in the Django source code, involves:

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

This method avoids potential errors and ensures a smoother experience for developers.
Given that the current documentation acknowledges the possibility of raising an AttributeError, would it be possible to update the documentation to also recommend this more robust method to the readers?

[Sarah Boyce]

You can submit a PR suggesting a tweak, I don't think it needs a ticket to track

[Jae Hyuck Sa]

Replying to Sarah Boyce:

You can submit a PR suggesting a tweak, I don't think it needs a ticket to track

Thank you so much for your kind and helpful response regarding this matter. I really appreciate it. I will proceed with suggesting a PR.