Skip to content

bpo-42127: Document effect of cached_property on key-sharing dicts #22930

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rhettinger merged 1 commit into from
Oct 25, 2020
Merged

bpo-42127: Document effect of cached_property on key-sharing dicts #22930

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 24 additions & 9 deletions Doc/library/functools.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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.