From: Raymond Hettinger <rhettinger@users.noreply.github.com>
Date: Fri, 1 Jan 2021 01:05:58 +0000 (-0800)
Subject: bpo-42781: Document the mechanics of cached_property from a user viewpoint (GH-24031)
X-Git-Tag: v3.10.0a4~29
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=c8a7b8fa1b5f9a6d3052db792018dc27c5a3a794;p=thirdparty%2FPython%2Fcpython.git

bpo-42781: Document the mechanics of cached_property from a user viewpoint (GH-24031)
---

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 75c9d41b43ac..e981bcdf6f25 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -62,16 +62,26 @@ The :mod:`functools` module defines the following functions:
    Example::
 
        class DataSet:
+
            def __init__(self, sequence_of_numbers):
-               self._data = sequence_of_numbers
+               self._data = tuple(sequence_of_numbers)
 
            @cached_property
            def stdev(self):
                return statistics.stdev(self._data)
 
-           @cached_property
-           def variance(self):
-               return statistics.variance(self._data)
+   The mechanics of :func:`cached_property` are somewhat different from
+   :func:`property`.  A regular property blocks attribute writes unless a
+   setter is defined. In contrast, a *cached_property* allows writes.
+
+   The *cached_property* decorator only runs on lookups and only when an
+   attribute of the same name doesn't exist.  When it does run, the
+   *cached_property* writes to the attribute with the same name. Subsequent
+   attribute reads and writes take precedence over the *cached_property*
+   method and it works like a normal attribute.
+
+   The cached value can be cleared by deleting the attribute.  This
+   allows the *cached_property* method to run again.
 
    Note, this decorator interferes with the operation of :pep:`412`
    key-sharing dictionaries.  This means that instance dictionaries