bpo-42127: Document effect of cached_property on key-sharing dictionaries (GH-22930) (GH-22955)
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
index 14aa184..4869b67 100644
--- a/Doc/library/functools.rst
+++ b/Doc/library/functools.rst
@@ -73,17 +73,32 @@
def variance(self):
return statistics.variance(self._data)
+ Note, this decorator interferes with the operation of :pep:`412`
+ key-sharing dictionaries. This means that instance dictionaries
+ can take more space than usual.
+
+ 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`::
+
+ 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
- .. note::
-
- 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).
-
.. function:: cmp_to_key(func)
@@ -651,4 +666,4 @@
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.