diff --git a/Doc/library/functools.rst b/Doc/library/functools.rst index 2ce07976c395311..25d28c479cbb9d3 100644 --- a/Doc/library/functools.rst +++ b/Doc/library/functools.rst @@ -57,6 +57,70 @@ The :mod:`!functools` module defines the following functions: .. versionadded:: 3.9 +.. decorator:: cached_method(func) + cached_method(maxsize=None, typed=False) + + Decorator to wrap a method with a bounded or unbounded cache. + + When :func:`cache` or :func:`lru_cache` are used on an instance method, the + instance (``self``) will be stored in the cache. As a result, instances cannot be + garbage collected until the relevant cache entries are cleared. + This decorator uses :func:`lru_cache`, but it wraps the unbound method to accept + a weakref and ensures that caches are cleared when instances are garbage collected. + + This is useful for expensive computations which are consistent with respect to + an instance, for example, those which depend only on immutable attributes. + + Example:: + + class DataSet: + + def __init__(self, sequence_of_ints): + self._data = tuple(sequence_of_ints) + + @cached_method + def shifted(self, shift): + return DataSet([value + shift for value in self._data]) + + On instances, :func:`cached_method` behaves very similarly to :func:`cache`, + providing :func:`!cache_info` and :func:`!cache_clear`. + + :func:`cached_method` does not prevent all possible race conditions in + multi-threaded usage. The function could run more than once on the + same instance, with the same inputs, with the latest run setting the cached + value. The per-instance cache is lazily initialized on first access (via the + descriptor protocol), so parallel access on a single instance can race to + initialize. + + This decorator requires that the instance supports weak references. + Some immutable types and slotted classes without ``__weakref__`` as one of + the defined slots will encounter errors when the cached method is first used. + + Hashability is not required: the cache is indexed by the :func:`id` of + the instances. This also means that distinct instances always get distinct + caches, even if they compare and hash equal. + + *maxsize* and *typed* are supported as keyword arguments to the decorator, + and are passed to the underlying :func:`lru_cache`. + + Composition with :deco:`property` is supported, and has slightly different + mechanics from :func:`cached_property`. As a result, the two decorators can + be combined in cases where the instances do not have a ``__dict__`` -- for + example, on slotted classes. + + .. note:: + + :func:`cached_method` does not support composition with + :deco:`classmethod` or :deco:`staticmethod`. Users who wish to have + caching on :func:`classmethod`\s and :func:`staticmethod`\s should use + :func:`cache` or :func:`lru_cache` instead. + + Because an inner decorator sees a normal function, these combinations + cannot be reliably detected when the method is declared. + + .. versionadded:: next + + .. decorator:: cached_property(func) Transform a method of a class into a property whose value is computed once diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst index f86a6ec69172d8a..064d411609a555a 100644 --- a/Doc/whatsnew/3.16.rst +++ b/Doc/whatsnew/3.16.rst @@ -500,6 +500,14 @@ encodings (Contributed by Petr Viktorin in :gh:`157675`.) +functools +--------- + +* Added :func:`functools.cached_method` decorator for applying a cache to + instance methods. + (Contributed by Stephen Rosen in :gh:`102618`.) + + gzip ---- diff --git a/Lib/functools.py b/Lib/functools.py index a6cc155b65a4b06..9b7b92b6110c5c4 100644 --- a/Lib/functools.py +++ b/Lib/functools.py @@ -12,15 +12,15 @@ __all__ = ['update_wrapper', 'wraps', 'WRAPPER_ASSIGNMENTS', 'WRAPPER_UPDATES', 'total_ordering', 'cache', 'cmp_to_key', 'lru_cache', 'reduce', 'partial', 'partialmethod', 'singledispatch', 'singledispatchmethod', - 'cached_property', 'Placeholder'] + 'cached_method', 'cached_property', 'Placeholder'] from abc import get_cache_token from collections import namedtuple -# import weakref # Deferred to single_dispatch() from operator import itemgetter from reprlib import recursive_repr from types import FunctionType, GenericAlias, MethodType, MappingProxyType, UnionType from _thread import RLock +lazy import weakref ################################################################################ ### update_wrapper() and wraps() decorator @@ -884,11 +884,6 @@ def singledispatch(func): implementations can be registered using the register() attribute of the generic function. """ - # There are many programs that use functools without singledispatch, so we - # trade-off making singledispatch marginally slower for the benefit of - # making start-up of such applications slightly faster. - import weakref - registry = {} dispatch_cache = weakref.WeakKeyDictionary() cache_token = None @@ -1119,6 +1114,125 @@ def __wrapped__(self): def register(self): return self._unbound.register +################################################################################ +### cached_method -- a version of lru_cache() which uses id(self) +################################################################################ + + +class _bound_cached_method: + """ + A wrapper over a cached method which acts like a bound method. + + It holds a reference to the instance and the caching variant of the + function, and it calls the function when called. This is constructed + dynamically whenever a cached method is accessed on an instance. + """ + def __init__(self, func, inst): + self.func = func + self.inst = inst + + update_wrapper(self, self.func) + + self.cache_clear = func.cache_clear + self.cache_info = func.cache_info + self.cache_parameters = func.cache_parameters + + def __repr__(self): + return f"" + + def __call__(self, /, *args, **kwargs): + return self.func(*args, **kwargs) + + +def _cached_method_weakref_callback(cache_dict, id_key): + def callback(ref): + cache_dict.pop(id_key, None) + return callback + + +def _wrap_unbound_cached_method(ref, unbound_method, maxsize, typed): + @wraps(unbound_method) + @lru_cache(maxsize, typed) + def wrapped(*args, **kwargs): + return unbound_method(ref(), *args, **kwargs) + return wrapped + + +class _cached_method: + def __init__(self, func, /, maxsize=None, typed=False): + self._function_table = {} + + self._maxsize = maxsize + self._typed = typed + + self.func = func + update_wrapper(self, func) + + def __call__(self, instance, /, *args, **kwargs): + # a direct call skips construction of a bound cached method, since it + # isn't needed in order to guarantee that `instance` is not released + # before `cached_func` runs + cached_func = self._get_or_create_cached_func(instance) + return cached_func(*args, **kwargs) + + def __repr__(self): + return f"" + + def __get__(self, instance, owner=None): + if instance is None: + return self + # construct a bound method, to guarantee that the instance cannot be + # released until after the returned function is called + unbound_func = self._get_or_create_cached_func(instance) + return _bound_cached_method(unbound_func, instance) + + def _get_or_create_cached_func(self, instance): + instance_id = id(instance) + + try: + ref, cached_func = self._function_table[instance_id] + except KeyError: + cb = _cached_method_weakref_callback(self._function_table, instance_id) + try: + ref = weakref.ref(instance, cb) + except TypeError as exc: + exc.__suppress_context__ = True + raise TypeError( + "`cached_method` requires the instances of " + f"{type(instance).__name__!r} to be weakly referencable" + ) from exc + + cached_func = _wrap_unbound_cached_method( + ref, self.func, self._maxsize, self._typed + ) + self._function_table[instance_id] = ref, cached_func + + return cached_func + + +def cached_method(func=None, /, maxsize=None, typed=False): + """ + A caching decorator for use on instance methods. + + Using cache or lru_cache on methods is problematic because the instance is put into + the cache and cannot be garbage collected until the cache is cleared. This decorator + uses a cache based on `id(self)` and a weakref to clear cache entries. + + The instance must be weak-referencable. + + By default, this provides an infinite sized cache similar to `functools.cache`. Use + *maxsize* and *typed* to set these attributes of the underlying LRU cache. + """ + if maxsize is not None and not isinstance(maxsize, int): + raise TypeError( + 'Expected maxsize to be an integer or None') + if func is None: + def decorator(func): + return _cached_method(func, maxsize=maxsize, typed=typed) + return decorator + else: + return _cached_method(func, maxsize=maxsize, typed=typed) + ################################################################################ ### cached_property() - property result cached as instance attribute diff --git a/Lib/test/test_functools.py b/Lib/test/test_functools.py index 7727cba4f55f4fe..f8d0fbe360f6902 100644 --- a/Lib/test/test_functools.py +++ b/Lib/test/test_functools.py @@ -3869,5 +3869,65 @@ def prop(self): self.assertEqual(t.prop, 1) +class CachedValueAdder: + def __init__(self, value): + self.value = value + + @py_functools.cached_method + def add(self, other): + return self.value + other + + +class TestCachedMethod(unittest.TestCase): + module = py_functools + + def test_cached_usage(self): + one = CachedValueAdder(1) + self.assertEqual(one.add(2), 3) + one.value = 2 + self.assertEqual(one.add(2), 3) # still 3, not 4 + one.add.cache_clear() + self.assertEqual(one.add(2), 4) # now 4 + + def test_cache_info(self): + one = CachedValueAdder(1) + self.assertEqual(one.add.cache_info(), + self.module._CacheInfo(hits=0, misses=0, maxsize=None, currsize=0)) + for _ in range(3): + for i in range(10): + one.add(i) + self.assertEqual(one.add.cache_info(), + self.module._CacheInfo(hits=20, misses=10, maxsize=None, currsize=10)) + one.add.cache_clear() + self.assertEqual(one.add.cache_info(), + self.module._CacheInfo(hits=0, misses=0, maxsize=None, currsize=0)) + + def test_reapplication_is_allowed(self): + decorator = py_functools.cached_method(maxsize=10) + + class MyObject: + @decorator + def a(self): + return 1 + + @decorator + def b(self): + return 2 + + x = MyObject() + self.assertEqual(x.a(), 1) + self.assertEqual(x.b(), 2) + + def test_cached_method_under_property(self): + class MyObject: + @property + @py_functools.cached_method + def foo(self): + return 1 + + x = MyObject() + self.assertEqual(x.foo, 1) + + if __name__ == '__main__': unittest.main() diff --git a/Misc/NEWS.d/next/Library/2026-05-18-11-34-16.gh-issue-102618.4y-SEm.rst b/Misc/NEWS.d/next/Library/2026-05-18-11-34-16.gh-issue-102618.4y-SEm.rst new file mode 100644 index 000000000000000..bb13cb7b89fa90c --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-05-18-11-34-16.gh-issue-102618.4y-SEm.rst @@ -0,0 +1,2 @@ +Added a new ``functools.cached_method`` decorator, which uses weakrefs and +avoids putting ``self`` into the cache.