[Django] #35745: Improve Documentation on Clearing Cached Property Values

[Django]

#35745: Improve Documentation on Clearing Cached Property Values
-------------------------------+-----------------------------------------
Reporter: Jae Hyuck Sa | Type: Uncategorized
Status: new | Component: Documentation
Version: 5.1 | Severity: Normal
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+-----------------------------------------
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
--
Ticket URL: <https://code.djangoproject.com/ticket/35745>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#35745: Improve Documentation on Clearing Cached Property Values
-------------------------------+-----------------------------------------

Reporter: Jae Hyuck Sa | Owner: Jae Hyuck Sa
Type: Uncategorized | Status: assigned
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:

Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+-----------------------------------------

Changes (by Jae Hyuck Sa ):

* owner: (none) => Jae Hyuck Sa
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/35745#comment:1>

[Django]

#35745: Improve Documentation on Clearing Cached Property Values
-------------------------------+-----------------------------------------
Reporter: Jae Hyuck Sa | Owner: Jae Hyuck Sa
Type: Uncategorized | Status: assigned
Component: Documentation | Version: 5.1
Severity: Normal | Resolution:
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+-----------------------------------------

Description changed by Jae Hyuck Sa :

Old 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

New 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

Feedback and suggestions from the community are greatly appreciated!

--
--
Ticket URL: <https://code.djangoproject.com/ticket/35745#comment:2>

[Django]

#35745: Improve Documentation on Clearing Cached Property Values
-------------------------------+-----------------------------------------
Reporter: Jae Hyuck Sa | Owner: Jae Hyuck Sa

Type: Uncategorized | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: invalid

Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+-----------------------------------------

Changes (by Sarah Boyce):

* resolution: => invalid
* status: assigned => closed

Comment:

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:
>
> {{{#!python
> # 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"]
> }}}
--
Ticket URL: <https://code.djangoproject.com/ticket/35745#comment:3>

[Django]

#35745: Improve Documentation on Clearing Cached Property Values
-------------------------------+-----------------------------------------
Reporter: Jae Hyuck Sa | Owner: Jae Hyuck Sa
Type: Uncategorized | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+-----------------------------------------

Comment (by Jae Hyuck Sa ):

Replying to [comment:3 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:
> >
> > {{{#!python
> > # 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?
--
Ticket URL: <https://code.djangoproject.com/ticket/35745#comment:4>

[Django]

#35745: Improve Documentation on Clearing Cached Property Values
-------------------------------+-----------------------------------------
Reporter: Jae Hyuck Sa | Owner: Jae Hyuck Sa
Type: Uncategorized | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+-----------------------------------------

Comment (by Sarah Boyce):

You can submit a PR suggesting a tweak, I don't think it needs a ticket to
track
--
Ticket URL: <https://code.djangoproject.com/ticket/35745#comment:5>

[Django]

#35745: Improve Documentation on Clearing Cached Property Values
-------------------------------+-----------------------------------------
Reporter: Jae Hyuck Sa | Owner: Jae Hyuck Sa
Type: Uncategorized | Status: closed
Component: Documentation | Version: 5.1
Severity: Normal | Resolution: invalid
Keywords: | Triage Stage: Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------+-----------------------------------------

Comment (by Jae Hyuck Sa ):

Replying to [comment:5 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.
--
Ticket URL: <https://code.djangoproject.com/ticket/35745#comment:6>