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

rhettinger webhook-mailer at python.org
Thu Dec 31 20:06:08 EST 2020

commit: c8a7b8fa1b5f9a6d3052db792018dc27c5a3a794
branch: master
author: Raymond Hettinger <rhettinger at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2020-12-31T17:05:58-08:00

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

M Doc/library/functools.rst

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 75c9d41b43acd..e981bcdf6f257 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -62,16 +62,26 @@ The :mod:`functools` module defines the following functions:
        class DataSet:
            def __init__(self, sequence_of_numbers):
-               self._data = sequence_of_numbers
+               self._data = tuple(sequence_of_numbers)
            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

More information about the Python-checkins mailing list