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

This commit is contained in:
Raymond Hettinger 2020-10-24 18:17:17 -07:00 committed by GitHub
parent c579ad14d3
commit 48be6b1ef7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 25 additions and 10 deletions

View File

@ -73,17 +73,32 @@ The :mod:`functools` module defines the following functions:
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)
@ -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.
during instance attribute look-up.