django.utils.functional.cached_property should be documented

[Daniele Procida]

It's a very common pattern in Django to find oneself calling a method in a view to check something - if MyModel.mymethod(): - then a moment later in the template {% for things in mymodel.mymethod %} - so mymethod() gets called twice.

If mymethod()` is very expensive, this could be a problem.

django.utils.functional.cached_property already exists and solves the problem. Doesn't it deserve to be documented so that we can all enjoy it?

​https://github.com/django/django/blob/master/django/utils/functional.py#L38

[Tim Graham]

​django-developers thread asking if OK to document this has received a couple +1's with a caveat from Aymeric: "The main drawback of the current implementation is that it's impossible to clear the cached value. That should be mentioned in the docs."

[Anssi Kääriäinen]

It doesn't seem to be impossible:

from django.utils.functional import cached_property


class Foobar(object):
    i = 0

    @cached_property
    def foo(self):
        Foobar.i += 1
        return Foobar.i

f = Foobar()
print f.foo
print f.foo
del f.foo
print f.foo
print f.foo
OUT:
1
1
2
2

If we want to document that is a different thing. That forces the implementation to have the cached value in self.__dict__, but on the other hand that seems to be the only way to implement cached_property...

[Daniele Procida]

​https://github.com/django/django/pull/1449 (closed; left here for reference only)

New pull request: ​https://github.com/django/django/pull/1452

[Tim Graham <timograham@…>]

In 7a2296eb5bb05a4109392f8333e934d576d79d35:

Fixed #20870 -- Documented django.utils.functional.cached_property

[Tim Graham <timograham@…>]

In e8ea55212bc1520da2e9b87af9990505c5baa000:

[1.5.x] Fixed #20870 -- Documented django.utils.functional.cached_property

Backport of 7a2296eb5b from master

[Tim Graham <timograham@…>]

In 25ce1e0e0a37d7be7ceff1e37bcb9ebd78a959d9:

[1.6.x] Fixed #20870 -- Documented django.utils.functional.cached_property

Backport of 7a2296eb5b from master

[Daniele Procida]

​https://github.com/django/django/pull/1452 was accepted before I had a chance to add ​https://github.com/django/django/pull/1455

[Tim Graham <timograham@…>]

In 7e6af9d40ce0232deb9d4c6943beef0b62a20a08:

Added more on @cached_property, refs #20870

[Tim Graham <timograham@…>]

In bf55bbdcb55b830e3d34b07a067584bce4e6f158:

[1.5.x] Added more on @cached_property, refs #20870

Backport of 7e6af9d40c from master

[Tim Graham <timograham@…>]

In 9cc7407f2c6b457c1b8f1e7c2a57e7b065d9bc41:

[1.6.x] Added more on @cached_property, refs #20870

Backport of 7e6af9d40c from master