From 48be6b1ef7a6201e13c87a317361cdb60bd5faa8 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Sat, 24 Oct 2020 18:17:17 -0700 Subject: bpo-42127: Document effect of cached_property on key-sharing dictionaries (GH-22930) --- Doc/library/functools.rst | 33 ++++++++++++++++++++++++--------- 1 file 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. -- cgit v0.12