[Python-checkins] bpo-42781: Document the mechanics of cached_property from a user viewpoint (GH-24031) (#24035)

[rhettinger]

https://github.com/python/cpython/commit/8333d421c0d7b90de3ff92002af9fd2c5d5f373c
commit: 8333d421c0d7b90de3ff92002af9fd2c5d5f373c
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2020-12-31T17:36:14-08:00
summary:

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

files:
M Doc/library/functools.rst

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 4869b67cb9416..85d4e74698d2f 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