bpo-21145: Add cached_property decorator in functools

ncoghlan · Aug 28, 2018 · May 19, 2018 · May 20, 2018 · May 20, 2018 · May 22, 2018
commit 1cda951b28dfc8a0b1350be7e64926602ee9e0e5
diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst
@@ -20,6 +20,34 @@ function for the purposes of this module.
 
 The :mod:`functools` module defines the following functions:
 
+.. decorator:: cached_property(func)
+
+   Transform a method of a class into a property whose value is computed once
+   and then cached as a normal attribute for the life of the instance. Similar
+   to :func:`property`, with the addition of caching. Useful for expensive
+   computed properties of instances that are otherwise effectively immutable.
+
+   Example::
+
+       class DataSet:
+           def __init__(self, sequence_of_numbers):
+               self.data = sequence_of_numbers
+
+           @cached_property
+           def stdev(self):
+               return statistics.stdev(self.data)
+
+           @cached_property
+           def variance(self):
+               return statistics.variance(self.data)
+
+   .. versionadded:: 3.8
+
+   .. note::
+
+      This decorator does not support classes which define ``__slots__``.
+
+
 .. function:: cmp_to_key(func)
 
    Transform an old-style comparison function to a :term:`key function`.  Used

diff --git a/Lib/functools.py b/Lib/functools.py
@@ -868,3 +868,32 @@ def _method(*args, **kwargs):
     @property
     def __isabstractmethod__(self):
         return getattr(self.func, '__isabstractmethod__', False)
+
+
+################################################################################
+### cached_property() - computed once per instance, cached as attribute
+################################################################################
+
+class cached_property:
+    def __init__(self, func):
+        self.func = func
+        self.__doc__ = func.__doc__
+        self.lock = RLock()
+
+    def __get__(self, instance, cls=None):
+        if instance is None:
+            return self
+        attrname = self.func.__name__
+        try:
+            cache = instance.__dict__
+        except AttributeError:  # objects with __slots__ have no __dict__
+            msg = (
+                f"No '__dict__' attribute on {type(instance).__name__!r} "
+                f"instance to cache {attrname!r} property."
+            )
+            raise TypeError(msg) from None
+        with self.lock:
+            # check if another thread filled cache while we awaited lock
+            if attrname not in cache:
+                cache[attrname] = self.func(instance)
+        return cache[attrname]
diff --git a/Lib/test/test_functools.py b/Lib/test/test_functools.py
@@ -2313,5 +2313,89 @@ def f(*args):
         with self.assertRaisesRegex(TypeError, msg):
             f()
 
+class CachedCostItem:
+    _cost = 1
+
+    def __init__(self):
+        self.lock = py_functools.RLock()
+
+    @py_functools.cached_property
+    def cost(self):
+        """The cost of the item."""
+        with self.lock:
+            self._cost += 1
+        return self._cost
+
+
+class CachedCostItemWait:
+    _cost = 1
+
+    def __init__(self, event):
+        self._cost = 1
+        self.lock = py_functools.RLock()
+        self.event = event
+
+    @py_functools.cached_property
+    def cost(self):
+        self.event.wait(1)
+        with self.lock:
+            self._cost += 1
+        return self._cost
+
+
+class CachedCostItemWithSlots:
+    __slots__ = ('_cost')
+
+    def __init__(self):
+        self._cost = 1
+
+    @py_functools.cached_property
+    def cost(self):
+        """The cost of the item."""
+        return self._cost
+
+
+class TestCachedProperty(unittest.TestCase):
+    def test_cached(self):
+        item = CachedCostItem()
+        self.assertEqual(item.cost, 2)
+        self.assertEqual(item.cost, 2) # not 3
+
+    def test_threaded(self):
+        go = threading.Event()
+        item = CachedCostItemWait(go)
+
+        num_threads = 3
+
+        orig_si = sys.getswitchinterval()
+        sys.setswitchinterval(1e-6)
+        try:
+            threads = [
+                threading.Thread(target=lambda: item.cost)
+                for k in range(num_threads)
+            ]
+            with support.start_threads(threads):
+                go.set()
+        finally:
+            sys.setswitchinterval(orig_si)
+
+        self.assertEqual(item.cost, 2)
+
+
+    def test_object_with_slots(self):
+        item = CachedCostItemWithSlots()
+        with self.assertRaisesRegex(
+                TypeError,
+                "No '__dict__' attribute on 'CachedCostItemWithSlots' instance to cache 'cost' property.",
+        ):
+            item.cost
+
+    def test_access_from_class(self):
+        self.assertIsInstance(CachedCostItem.cost, py_functools.cached_property)
+
+    def test_doc(self):
+        self.assertEqual(CachedCostItem.cost.__doc__, "The cost of the item.")
+
+
 if __name__ == '__main__':
     unittest.main()
diff --git a/Misc/NEWS.d/next/Library/2018-05-18-22-52-34.bpo-21145.AiQMDx.rst b/Misc/NEWS.d/next/Library/2018-05-18-22-52-34.bpo-21145.AiQMDx.rst
@@ -0,0 +1,2 @@
+Add ``functools.cached_property`` decorator, for computed properties cached
+for the life of the instance.
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		Add ``functools.cached_property`` decorator, for computed properties cached
		for the life of the instance.