From 7a2296eb5bb05a4109392f8333e934d576d79d35 Mon Sep 17 00:00:00 2001
From: Daniele Procida <daniele@vurt.org>
Date: Wed, 7 Aug 2013 18:47:07 +0100
Subject: [PATCH] Fixed #20870 -- Documented
 django.utils.functional.cached_property

---
 docs/ref/utils.txt | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/ref/utils.txt b/docs/ref/utils.txt
index 599797bedb9..8ecd69626cc 100644
--- a/docs/ref/utils.txt
+++ b/docs/ref/utils.txt
@@ -431,6 +431,50 @@ Atom1Feed
 .. module:: django.utils.functional
     :synopsis: Functional programming tools.
 
+.. class:: cached_property(object)
+
+    The ``@cached_property`` decorator caches the result of a method with a
+    single ``self`` argument as a property. The cached result will persist as
+    long as the instance does.
+
+    Consider a typical case, where a view might need to call a model's method
+    to perform some computation, before placing the model instance into the
+    context, where the template might invoke the method once more::
+
+        # the model
+        class Person(models.Model):
+
+            def friends(self):
+                # expensive computation
+                ...
+                return friends
+
+        # in the view:
+        if person.friends():
+
+        # in the template:
+        {% for friend in person.friends %}
+
+    ``friends()`` will be called twice. Since the instance ``person`` in
+    the view and the template are the same, ``@cached_property`` can avoid
+    that::
+
+        from django.utils.functional import cached_property
+
+        @cached_property
+        def friends(self):
+            # expensive computation
+            ...
+            return friends
+
+    Note that as the method is now a property, in Python code it will need to
+    be invoked appropriately::
+
+        # in the view:
+        if person.friends:
+
+    You may clear the cached result using ``del person.friends``.
+
 .. function:: allow_lazy(func, *resultclasses)
 
     Django offers many utility functions (particularly in ``django.utils``) that