bpo-42127: Document effect of cached_property on key-sharing dictionaries (GH-22930)

1 files changed, 24 insertions, 9 deletions

diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 186cb4c..75c9d41 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -73,16 +73,31 @@ The :mod:`functools` module defines the following functions:
            def variance(self):
                return statistics.variance(self._data)
 
-   .. versionadded:: 3.8
+   Note, this decorator interferes with the operation of :pep:`412`
+   key-sharing dictionaries.  This means that instance dictionaries
+   can take more space than usual.
 
-   .. note::
+   Also, this decorator requires that the ``__dict__`` attribute on each instance
+   be a mutable mapping. This means it will not work with some types, such as
+   metaclasses (since the ``__dict__`` attributes on type instances are
+   read-only proxies for the class namespace), and those that specify
+   ``__slots__`` without including ``__dict__`` as one of the defined slots
+   (as such classes don't provide a ``__dict__`` attribute at all).
+
+   If a mutable mapping is not available or if space-efficient key sharing
+   is desired, an effect similar to :func:`cached_property` can be achieved
+   by a stacking :func:`property` on top of :func:`cache`::
 
-      This decorator requires that the ``__dict__`` attribute on each instance
-      be a mutable mapping. This means it will not work with some types, such as
-      metaclasses (since the ``__dict__`` attributes on type instances are
-      read-only proxies for the class namespace), and those that specify
-      ``__slots__`` without including ``__dict__`` as one of the defined slots
-      (as such classes don't provide a ``__dict__`` attribute at all).
+       class DataSet:
+           def __init__(self, sequence_of_numbers):
+               self._data = sequence_of_numbers
+
+           @property
+           @cache
+           def stdev(self):
+               return statistics.stdev(self._data)
+
+   .. versionadded:: 3.8
 
 
 .. function:: cmp_to_key(func)
@@ -658,4 +673,4 @@ callable, weak referencable, and can have attributes.  There are some important
 differences.  For instance, the :attr:`~definition.__name__` and :attr:`__doc__` attributes
 are not created automatically.  Also, :class:`partial` objects defined in
 classes behave like static methods and do not transform into bound methods
-during instance attribute look-up.
\ No newline at end of file
+during instance attribute look-up.