Repository navigation
Conversation
Documentation build overview
252 files changed ·
|
resolves python#102618 This definition of `cached_method` is based on the discussion on DPO: https://discuss.python.org/t/107164 Some tradeoffs need to be made in any version of such a decorator. In this particular implementation, the choices made are as follows: - lru_cache will be used under the hood, and `cache_clear()` and `cache_info()` will be exposed - caches will be stored in a separate dict, indexed by `id(self)` -- meaning instances do not need to be hashable and will not share caches - weakrefs will be used to delete entries from the cache, so the instances must be weak-referencable - lru_cache itself is not threadsafe, but initialization of the caches is threadsafe -- this avoids confusing scenarios in which cache entries "disappear" New documentation is included, marked for 3.16, and a small number of new tests are added.
Thanks to feedback from @jaraco, this adjustment makes the public interface for `cached_method` a function which is responsible for the argument management, rather than trying to use `__call__` on the descriptor itself. This frees up `__call__` to lookup the relevant LRU-cached function and invoke it, which makes the `_cached_method` descriptor suitable for use as a `property.fget` callable. Tests are updated to indicate that a decorator can be prepared and then used repeatedly (which was previously an explicit error), and can be used under a property decorator.
- Fix doc references - Use imperative mood in a comment Co-authored-by: Jason R. Coombs <308610+jaraco@users.noreply.github.com>
|
Jelle pointed out to me that although I have tried to be careful about the locking I included, to minimize contention, the lock I defined is per- I'll push a change to remove the locking and clarify the thread-safety documentation. |
|
@willingc , this is the PR that I mentioned to you; you said you wanted a ping to take a look. 🙂 |
Although this logic tried to avoid lock contention, there were still scenarios under which it was possible and could negatively impact users. Removal and adjustment of the documentation puts responsibility for locking/safety onto users, similar to other parts of the stdlib.
|
FWIW. The |
Co-authored-by: Edgar Ramírez Mondragón <16805946+edgarrmondragon@users.noreply.github.com>
jaraco
left a comment
There was a problem hiding this comment.
In my opinion, this implementation is fairly clean and simple. The documentation shows pretty clearly what the user's expectations should be. The tradeoffs chosen have been well considered and a reasonable path elected. I propose to get this merged and give it some exposure through the beta releases. From there iterate or pivot.
StanFromIreland
left a comment
There was a problem hiding this comment.
This needs a What's New in 3.16 entry.
Rather than doing an old-style deferred import, with explanatory comments for why the deferred import style is used. Convert these to a top-level `lazy import weakref`. No explanatory comment is used, on the grounds that the new syntax is sufficiently low in cognitive cost that experienced maintainers will quickly recognize it and assume that the pattern is used to either break a cycle or reduce import costs.
|
I've applied the lazy import change. My commit message explains why I did not preserve any comment about it, but I'm open to feedback on that. I also added the What's New entry. |
hugovk
left a comment
There was a problem hiding this comment.
We have docs tooling that will update next to whatever the next pre-release is, for example:
"Added in version 3.16.0a0 (unreleased)"
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Stan Ulbrych <stan@python.org>
Co-authored-by: Stan Ulbrych <stan@python.org>
And add it to functools' `__all__` list.
Multiple weakrefs can be created when there are concurrent writes to a "new cache". When they finalize, their attempts to clear the dict should be kept safe by using a pop() default.
In order for `help(functools.cached_method)` to show the docstring, it needs to be attached to the public interface, not the implementation. This docstring was "misplaced" in the course of refactors to this code during review.
Co-authored-by: Stan Ulbrych <stan@python.org>
|
I just saw #154069 . If that goes in, this should get updated to also use |
|
This PR is stale because it has been open for 90 days with no activity. |
|
The docs should specify what happens in code like this: @dataclass
class Equity:
str: symbol
@cached_method(maxsize=16)
def opening_price(self, date):
return expensive_query(self.symbol, date)
e1 = Equity('GOOG')
print(e1.opening_price, date(2020, 2, 20)) # Miss ? Unhashable instances allowed
print(e1.opening_price, date(2020, 2, 20)) # Hit
print(e1.opening_price, date(2020, 2, 25)) # Miss
e2 = Equity('GOOG')
print(e2.opening_price, date(2020, 2, 20)) # ? Cross-instance caching
e1.symbol = 'ALPB'
print(e1.opening_price, date(2020, 2, 20)) # ? Detect attribute change
del e1 # ? Immediate clear |
|
|
||
| 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 caches are cleared. |
There was a problem hiding this comment.
or until the entry ages out of the lru (pretty much like any other entry).
There was a problem hiding this comment.
Yep! I tried to improve this in a subtle way, by correcting "relevant caches are cleared" to "relevant cache entries are cleared".
We can adjust it more -- my goal is to be both precise and concise. 😁
- Note "cache entries" rather than "caches", thereby capturing that eviction from an LRU cache covers the GC issue for cache/lru_cache - Add a note on hashability, next to the note about weakref. This provides a forum for explaining that `id()` is used and what the implications of that choice are.
|
Thanks for the review! I added a doc note about hashability, which explains that
I'm not sure what, if anything, to add about two of these noted cases:
|
|
|
||
| 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 |
There was a problem hiding this comment.
What about static methods, class methods, and properties?
I prefer that we explicitly rule these out in the docs or document how cached_method composes with @classmethod, @staticmethod, and @property, including which decorator orders are supported.
A few points to consider:
-
Class methods with
@cached_methodvs. class methods with@lru_cache:class C: @classmethod @cached_method(maxsize=128) def method(cls, arg): ...
This creates a separate cache for each class, whereas
@classmethod+@lru_cachealso works, but uses a shared cache whose keys includecls. In the latter caseclsmust be hashable, and refs toclsare kept in cache entries (which is mostly fine, as normally classes are long-lived and hashable).One limitation of the current composition is that
C.method.cache_info()andC.method.cache_clear()are unavailable.Could we clarify whether this combination is supported and decide how users should inspect or clear its caches in this case?
-
@staticmethod+@cached_methodproblems:class C: @staticmethod @cached_method def method(x): return x.value
Here, the identity of
xselects a separate cache, there is noCinstance involved. Ifxsupports weak references, this can appear to work, despite having different semantics from ordinary function caching.It also changes the calling convention, i.e.
C.method(x=obj)fails because the wrapper does not preserve the original function's first parameter name. A static method with no arguments fails too, as does one whose first argument cannot be weakly referenced, such as an integer or string.Nowadays you can do:
class C: @staticmethod @lru_cache(maxsize=128) def method(arg): ...
Could the documentation explicitly recommend this pattern? or
@cache, and discourage@staticmethodabove@cached_methodas unsuitable for general static methods? The inner decorator cannot generally detect the surroundingstaticmethodat decoration time. -
@property+@cached_method:from dataclasses import dataclass from functools import cached_method from math import hypot @dataclass(frozen=True) class Point: __slots__ = ("x", "y", "__weakref__",) x: float y: float @property @cached_method def distance_from_origin(self) -> float: return hypot(self.x, self.y) if __name__ == "__main__": point = Point(3, 4) print(point.distance_from_origin) # computes 5.0 print(point.distance_from_origin) # returns the cached value
(This example uses explicit slots because
dataclass(slots=True, weakref_slot=True)currently fails with this composition).This is now an alternative to
cached_propertywith different semantics. It works without an instance__dict__, whereascached_propertyrequires a mutable instance dictionary. It also preserves ordinary property setter behavior. On otherwise mutable instances, a getter-only property prevents assignment, whilecached_propertypermits overwriting the cached value. It would be nice to document (or rule out) this composition.
Finally, putting cached_method above classmethod, staticmethod, or property does not currently provide the corresponding descriptor behavior. It would help to document these unsupported orders, and consider clearer errors where the decorator can identify them.
Explicit support for an outer cached_method could be a separate API choice (which has its advantages, e.g. making cached_method idiomatic/intrinsic for methods, enforce only one way to make cached properties).
There was a problem hiding this comment.
My inclination is to say that cached_method does not support static methods or classmethods. I don't think there's any strong reason that someone would want it for those cases, if they're also aware of the cache/lru_cache decorators. I'm also not sure how it could work even if we did want support, at least with cached_method as the inner decorator. I think a documentation addition is sufficient.
For property, supporting that composition was intentional -- @jaraco suggested it early in the process for this feature. To me it makes sense, since the methods decorated by properties (all of getters, setters, and deleters) behave like ordinary instance methods.
Although I like the idea of superseding cached_property, as you note they have different APIs. I'm personally against any deprecation in the near term.
It would help to document these unsupported orders, and consider clearer errors where the decorator can identify them.
I can work a bit on dedicated detection and error messages where possible. I think it should be possible to catch these all.
Explicit support for an outer
cached_methodcould be a separate API choice (which has its advantages, e.g. makingcached_methodidiomatic/intrinsic for methods, enforce only one way to make cached properties).
I'm open to it in the future, but if we can agree to start without it, I'd be happier.
I think cached_method makes more sense as the inner decorator for property, and as the outer decorator for classmethod and staticmethod. But that is likely to confuse end users. And, as above, I'm not sure there's much compelling need for cached_method(classmethod(...)).
There was a problem hiding this comment.
I'm trying hard to keep the docs short and easy to read, but I added a new paragraph and note-directive to address composition with property, classmethod, and staticmethod.
I'm aware that it technically works in some of the classmethod and staticmethod cases, so I'm simply documenting it as "unsupported", and intentionally not specifying what that means exactly. I hope that's satisfactory. I think trying to detect and raise a TypeError isn't worthwhile, given that it can only be done in a subset of cases.
| def __get__(self, instance, owner=None): | ||
| if instance is None: | ||
| return self | ||
| return self._get_or_create_cached_func(instance) |
There was a problem hiding this comment.
Instances can be temporary, we need to keep the ref alive here:
from functools import cached_method
class C:
def __init__(self, x):
self.x = x
@cached_method
def value(self):
return self.x
C(10).value()
# AttributeError: 'NoneType' object has no attribute 'x'The same problem affects saved callbacks:
c = C(10)
callback = c.value
del c
callback() # kaboomMy idea is to create a bound method object here in __get__ and return that.
There was a problem hiding this comment.
My idea is to create a bound method object here in
__get__and return that.
I like this idea. I'll give it a try. And I think we can make one or both of the above failure cases into unit tests.
There was a problem hiding this comment.
I need to take more time to test it and think about it, but initial results seem good with this patch:
def __get__(self, instance, owner=None):
if instance is None:
return self
- return self._get_or_create_cached_func(instance)
+ unbound_func = self._get_or_create_cached_func(instance)
+
+ @wraps(unbound_func)
+ def bound_func(self, *args, **kwargs):
+ return unbound_func(*args, **kwargs)
+
+ return MethodType(bound_func, instance)I find it somewhat disappointing that this means reconstructing a bound method on every call though.
There was a problem hiding this comment.
You could create an instance of a callable class instead of using a real bound method.
Something along the lines of:
class _bound_cached_method:
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"<bound cached method {self.func.__qualname__} of {self.inst!r}>"
def __call__(self, /, *args, **kwargs):
return self.func(*args, **kwargs)This does have the benefit of having a __repr__ that indicates that it's a cached method and also provides access to the cache_ methods of the underlying lru_cache without needing to dig around in __wrapped__.
There was a problem hiding this comment.
I like the addition of a useful repr. I also added one to the descriptor itself, as <unbound cached method {self.func.__qualname__}>. That results in a nice symmetry.
I took @DavidCEllis' version above pretty much verbatim.
Co-authored-by: Bartosz Sławecki <bartosz@ilikepython.com>
A specialized "_bound_cached_method" type provides a dedicated repr, and resolves the issue noted in review that an instance could be released by GC before the cached method has been called. Co-authored-by: David Ellis <15880420+DavidCEllis@users.noreply.github.com>
Declare how it stacks with `@property`, and does not stack with classmethod or staticmethod.
resolves #102618
This definition of
cached_methodis based on the discussion on DPO:https://discuss.python.org/t/107164
Some tradeoffs need to be made in any version of such a decorator. In this particular implementation, the choices made are as follows:
lru_cache will be used under the hood, and
cache_clear()andcache_info()will be exposedcaches will be stored in a separate dict, indexed by
id(self)-- meaning instances do not need to be hashable and will not share cachesweakrefs will be used to delete entries from the cache, so the instances must be weak-referencable
lru_cache itself is not threadsafe, but initialization of the caches is threadsafe -- this avoids confusing scenarios in which cache entries "disappear"EDIT: in response to review feedback, this locking was removed; users can lock if they want thread safety
New documentation is included, marked for 3.16, and a small number of new
tests are added.
In addition to @rhettinger's review, as the listed owner for functools, @sobolevn expressed interest in reviewing changes.
@kenahoo and @stevendaprano may also want a look based on their prior interest.
Everyone I've spoken with about this change1 has been supportive of the core idea. In particular @jaraco noted that he would support this addition, and maintains a very different implementation. There are many other ways of writing this, with different tradeoffs. Perhaps the most notable class of those are versions which store caches on the instance itself, like this one suggested here in the DPO discussion -- this writes the cached method into
__dict__, similarly tocached_property.Of course, I'm happy to alter or re-approach any part of this per review! 😄
Footnotes
at PyCon US 2026 ↩