bpo-42781: Document the mechanics of cached_property from a user viewpoint (GH-24031)

This commit is contained in:
Raymond Hettinger 2020-12-31 17:05:58 -08:00 committed by GitHub
parent b5711c940f
commit c8a7b8fa1b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 14 additions and 4 deletions

View File

@ -62,16 +62,26 @@ The :mod:`functools` module defines the following functions:
Example:: Example::
class DataSet: class DataSet:
def __init__(self, sequence_of_numbers): def __init__(self, sequence_of_numbers):
self._data = sequence_of_numbers self._data = tuple(sequence_of_numbers)
@cached_property @cached_property
def stdev(self): def stdev(self):
return statistics.stdev(self._data) return statistics.stdev(self._data)
@cached_property The mechanics of :func:`cached_property` are somewhat different from
def variance(self): :func:`property`. A regular property blocks attribute writes unless a
return statistics.variance(self._data) setter is defined. In contrast, a *cached_property* allows writes.
The *cached_property* decorator only runs on lookups and only when an
attribute of the same name doesn't exist. When it does run, the
*cached_property* writes to the attribute with the same name. Subsequent
attribute reads and writes take precedence over the *cached_property*
method and it works like a normal attribute.
The cached value can be cleared by deleting the attribute. This
allows the *cached_property* method to run again.
Note, this decorator interferes with the operation of :pep:`412` Note, this decorator interferes with the operation of :pep:`412`
key-sharing dictionaries. This means that instance dictionaries key-sharing dictionaries. This means that instance dictionaries