cachetools 7.2.2__tar.gz → 7.2.3__tar.gz

{cachetools-7.2.2 → cachetools-7.2.3}/CHANGELOG.rst

@@ -1,3 +1,11 @@
+v7.2.3 (2026-10-17)
+===================
+
+- Fix ``@cached`` decorator stacking behavior.
+
+- Minor type stub improvements.
+
+
 v7.2.2 (2026-10-15)
 ===================
 

{cachetools-7.2.2/src/cachetools.egg-info → cachetools-7.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.2.2
+Version: 7.2.3
 Summary: Extensible memoizing collections and decorators
 Author-email: Thomas Kemmer <tkemmer@computer.org>
 Maintainer-email: Thomas Kemmer <tkemmer@computer.org>

{cachetools-7.2.2 → cachetools-7.2.3}/pyproject.toml

@@ -50,6 +50,7 @@ version = {attr = "cachetools.__version__"}
 
 [tool.pyright]
 typeCheckingMode = "standard"
+reportUnnecessaryTypeIgnoreComment = "error"
 
 [tool.ruff.lint]
 ignore = ["DTZ005", "UP031"]

{cachetools-7.2.2 → cachetools-7.2.3}/src/cachetools/__init__.py

@@ -12,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "7.2.2"
+__version__ = "7.2.3"
 
 import collections
 import collections.abc

{cachetools-7.2.2 → cachetools-7.2.3}/src/cachetools/__init__.pyi

@@ -29,7 +29,9 @@ __all__: Final = (
 __version__: str
 
 _P = ParamSpec("_P")
+_Q = ParamSpec("_Q")
 _R = TypeVar("_R")
+_S = TypeVar("_S")
 _T = TypeVar("_T")
 _KT = TypeVar("_KT")
 _VT = TypeVar("_VT")
@@ -153,16 +155,47 @@ class _AbstractCondition(AbstractContextManager[Any], Protocol):
 class _cached_wrapper(Generic[_P, _R]):
     __wrapped__: Callable[_P, _R]
     __name__: str
+    __qualname__: str
     __doc__: str | None
     cache: MutableMapping[Any, Any] | None
     cache_key: Callable[..., Any] = ...
     cache_lock: AbstractContextManager[Any] | None = None
     cache_condition: _AbstractCondition | None = None
+    @overload  # class access, e.g. Cls.method
+    def __get__(
+        self, obj: None, objtype: type | None = None
+    ) -> _cached_wrapper[_P, _R]: ...
+    @overload  # instance access binds the first parameter
+    def __get__(
+        self: _cached_wrapper[Concatenate[_S, _Q], _R],
+        obj: _S,
+        objtype: type | None = None,
+    ) -> _cached_wrapper[_Q, _R]: ...
+    @overload  # fallback, e.g. when wrapped by @staticmethod or @classmethod
+    def __get__(
+        self, obj: object, objtype: type | None = None
+    ) -> _cached_wrapper[_P, _R]: ...
     def __call__(self, /, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
     def cache_clear(self) -> None: ...
 
 @type_check_only
 class _cached_wrapper_info(_cached_wrapper[_P, _R]):
+    @overload
+    def __get__(
+        self, obj: None, objtype: type | None = None
+    ) -> _cached_wrapper_info[_P, _R]: ...
+    @overload
+    def __get__(
+        self: _cached_wrapper_info[Concatenate[_S, _Q], _R],
+        obj: _S,
+        objtype: type | None = None,
+    ) -> _cached_wrapper_info[_Q, _R]: ...
+    # pyright cannot match the self-typed base overload; each return type is
+    # the _cached_wrapper_info subtype of the corresponding base return type
+    @overload
+    def __get__(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, obj: object, objtype: type | None = None
+    ) -> _cached_wrapper_info[_P, _R]: ...
     def cache_info(self) -> _CacheInfo: ...
 
 @overload
@@ -195,6 +228,7 @@ def cached(
 class _cachedmethod_unbound(Generic[_P, _R]):
     __wrapped__: Callable[Concatenate[Any, _P], _R]
     __name__: str
+    __qualname__: str
     __doc__: str | None
     @overload
     def __call__(self, obj: Any, /, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
@@ -206,6 +240,7 @@ class _cachedmethod_unbound(Generic[_P, _R]):
 class _cachedmethod_wrapper(Generic[_P, _R]):
     __wrapped__: Callable[Concatenate[Any, _P], _R]
     __name__: str
+    __qualname__: str
     __doc__: str | None
     cache: MutableMapping[Any, Any]
     cache_key: Callable[..., Any] = ...

{cachetools-7.2.2 → cachetools-7.2.3}/src/cachetools/_cached.py

@@ -11,6 +11,10 @@ import warnings
 # over ease of maintenance, thus providing separate wrappers for
 # all valid combinations of decorator parameters lock, condition and
 # info.
+#
+# Each wrapper calls functools.update_wrapper() before setting its own
+# attributes, so func.__dict__ cannot override wrapper state, e.g. when
+# stacking decorators.
 
 
 def _condition_info(func, cache, key, lock, cond, info):
@@ -52,6 +56,7 @@ def _condition_info(func, cache, key, lock, cond, info):
         with lock:
             return info(hits, misses)
 
+    functools.update_wrapper(wrapper, func)
     wrapper.cache_clear = cache_clear
     wrapper.cache_info = cache_info
     return wrapper
@@ -90,6 +95,7 @@ def _locked_info(func, cache, key, lock, info):
         with lock:
             return info(hits, misses)
 
+    functools.update_wrapper(wrapper, func)
     wrapper.cache_clear = cache_clear
     wrapper.cache_info = cache_info
     return wrapper
@@ -122,6 +128,7 @@ def _unlocked_info(func, cache, key, info):
     def cache_info():
         return info(hits, misses)
 
+    functools.update_wrapper(wrapper, func)
     wrapper.cache_clear = cache_clear
     wrapper.cache_info = cache_info
     return wrapper
@@ -139,6 +146,7 @@ def _uncached_info(func, info):
         nonlocal misses
         misses = 0
 
+    functools.update_wrapper(wrapper, func)
     wrapper.cache_clear = cache_clear
     wrapper.cache_info = lambda: info(0, misses)
     return wrapper
@@ -173,6 +181,7 @@ def _condition(func, cache, key, lock, cond):
         with lock:
             cache.clear()
 
+    functools.update_wrapper(wrapper, func)
     wrapper.cache_clear = cache_clear
     return wrapper
 
@@ -199,6 +208,7 @@ def _locked(func, cache, key, lock):
         with lock:
             cache.clear()
 
+    functools.update_wrapper(wrapper, func)
     wrapper.cache_clear = cache_clear
     return wrapper
 
@@ -217,6 +227,7 @@ def _unlocked(func, cache, key):
             pass  # value too large
         return v
 
+    functools.update_wrapper(wrapper, func)
     wrapper.cache_clear = lambda: cache.clear()
     return wrapper
 
@@ -225,6 +236,7 @@ def _uncached(func):
     def wrapper(*args, **kwargs):
         return func(*args, **kwargs)
 
+    functools.update_wrapper(wrapper, func)
     wrapper.cache_clear = lambda: None
     return wrapper
 
@@ -265,5 +277,4 @@ def _wrapper(func, cache, key, lock=None, cond=None, info=None):
     wrapper.cache_key = key
     wrapper.cache_lock = lock if lock is not None else cond
     wrapper.cache_condition = cond
-
-    return functools.update_wrapper(wrapper, func)
+    return wrapper

{cachetools-7.2.2 → cachetools-7.2.3}/src/cachetools/func.pyi

@@ -1,19 +1,45 @@
 from collections.abc import Callable, Sequence
-from typing import Any, Final, Generic, ParamSpec, TypeVar, overload, type_check_only
+from typing import (
+    Any,
+    Concatenate,
+    Final,
+    Generic,
+    ParamSpec,
+    TypeVar,
+    overload,
+    type_check_only,
+)
 
 from . import _CacheInfo
 
 __all__: Final = ("fifo_cache", "lfu_cache", "lru_cache", "rr_cache", "ttl_cache")
 
 _P = ParamSpec("_P")
-_T = TypeVar("_T")
+_Q = ParamSpec("_Q")
 _R = TypeVar("_R")
+_S = TypeVar("_S")
+_T = TypeVar("_T")
 
 @type_check_only
 class _cachetools_cache_wrapper(Generic[_P, _R]):
     __wrapped__: Callable[_P, _R]
     __name__: str
+    __qualname__: str
     __doc__: str | None
+    @overload  # class access, e.g. Cls.method
+    def __get__(
+        self, obj: None, objtype: type | None = None
+    ) -> _cachetools_cache_wrapper[_P, _R]: ...
+    @overload  # instance access binds the first parameter
+    def __get__(
+        self: _cachetools_cache_wrapper[Concatenate[_S, _Q], _R],
+        obj: _S,
+        objtype: type | None = None,
+    ) -> _cachetools_cache_wrapper[_Q, _R]: ...
+    @overload  # fallback, e.g. when wrapped by @staticmethod or @classmethod
+    def __get__(
+        self, obj: object, objtype: type | None = None
+    ) -> _cachetools_cache_wrapper[_P, _R]: ...
     def __call__(self, /, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
     def cache_info(self) -> _CacheInfo: ...
     def cache_clear(self) -> None: ...

{cachetools-7.2.2 → cachetools-7.2.3/src/cachetools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.2.2
+Version: 7.2.3
 Summary: Extensible memoizing collections and decorators
 Author-email: Thomas Kemmer <tkemmer@computer.org>
 Maintainer-email: Thomas Kemmer <tkemmer@computer.org>

{cachetools-7.2.2 → cachetools-7.2.3}/tests/test_cached.py

@@ -154,6 +154,8 @@ class DecoratorTestMixin(SimplifiedTestCaseProtocol):
         wrapper = cachetools.cached(cache)(self.func)
 
         self.assertEqual(wrapper.__wrapped__, self.func)
+        self.assertEqual(wrapper.__name__, "func")
+        self.assertEqual(wrapper.__qualname__, "DecoratorTestMixin.func")
 
         self.assertEqual(len(cache), 0)
         self.assertEqual(wrapper.__wrapped__(0), 0)
@@ -316,6 +318,21 @@ class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin):
         self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0))
         self.assertEqual(lock.count, 13)
 
+    def test_stacked_decorators(self):
+        inner_cache = self.cache(2)
+        outer_cache = self.cache(2)
+        inner_wrapper = cachetools.cached(inner_cache, info=True)(self.func)
+        outer_wrapper = cachetools.cached(outer_cache, info=True)(inner_wrapper)
+        self.assertIs(outer_wrapper.__wrapped__, inner_wrapper)
+        self.assertIs(outer_wrapper.cache, outer_cache)
+        self.assertEqual(outer_wrapper(0), 0)
+        self.assertEqual(outer_wrapper(0), 0)
+        self.assertEqual(outer_wrapper.cache_info(), (1, 1, 2, 1))
+        self.assertEqual(inner_wrapper.cache_info(), (0, 1, 2, 1))
+        outer_wrapper.cache_clear()
+        self.assertEqual(len(outer_cache), 0)
+        self.assertEqual(len(inner_cache), 1)
+
     def test_zero_size_cache_decorator(self):
         cache = self.cache(0)
         wrapper = cachetools.cached(cache)(self.func)
@@ -386,20 +403,40 @@ class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin):
 
         """
 
+        cache = self.cache(2)
+
         class Cached:
+            @cachetools.cached(cache, key=cachetools.keys.methodkey)
+            def get(self, value: int) -> int:
+                return value
+
             @cachetools.cached(self.cache(2), key=cachetools.keys.methodkey, info=True)
-            def get(self, value):
+            def get_info(self, value):
+                return value
+
+            @staticmethod
+            @cachetools.cached(self.cache(2))
+            def get_static(value: int) -> int:
                 return value
 
         cached = Cached()
-        self.assertEqual(cached.get(1), 1)  # type: ignore
-        self.assertEqual(cached.get(1), 1)  # type: ignore
+        self.assertEqual(cached.get(1), 1)
         self.assertEqual(Cached.get(cached, 1), 1)
-        self.assertEqual(cached.get.cache_info(), (2, 1, 2, 1))
-        self.assertEqual(Cached.get.cache_info(), (2, 1, 2, 1))
+        self.assertEqual(len(cache), 1)
         cached.get.cache_clear()
-        self.assertEqual(cached.get.cache_info(), (0, 0, 2, 0))
-        self.assertEqual(Cached.get.cache_info(), (0, 0, 2, 0))
+        self.assertEqual(len(cache), 0)
+
+        self.assertEqual(cached.get_info(1), 1)
+        self.assertEqual(cached.get_info(1), 1)
+        self.assertEqual(Cached.get_info(cached, 1), 1)
+        self.assertEqual(cached.get_info.cache_info(), (2, 1, 2, 1))
+        self.assertEqual(Cached.get_info.cache_info(), (2, 1, 2, 1))
+        cached.get_info.cache_clear()
+        self.assertEqual(cached.get_info.cache_info(), (0, 0, 2, 0))
+        self.assertEqual(Cached.get_info.cache_info(), (0, 0, 2, 0))
+
+        self.assertEqual(cached.get_static(1), 1)
+        self.assertEqual(Cached.get_static(1), 1)
 
 
 class DictWrapperTest(unittest.TestCase, DecoratorTestMixin):

{cachetools-7.2.2 → cachetools-7.2.3}/tests/test_cachedmethod.py

@@ -1,6 +1,3 @@
-# TODO: type stub overloads for unbound methods?
-# pyright: reportCallIssue=false
-
 import unittest
 import warnings
 
@@ -359,6 +356,7 @@ class MethodDecoratorTestMixin(SimplifiedTestCaseProtocol):
         self.assertEqual(len(cache), 0)
         self.assertEqual(cached.get.__wrapped__(cached, 0), 0)
         self.assertEqual(cached.get.__name__, "get")
+        self.assertEqual(cached.get.__qualname__, "Cached.get")
         self.assertEqual((cached.get.__doc__ or "").strip(), "docstring")
         self.assertEqual(len(cache), 0)
         self.assertEqual(cached.get(0), 1)
@@ -636,7 +634,7 @@ class CacheMethodTest(unittest.TestCase, MethodDecoratorTestMixin):
 
     def test_undecorated_override(self):
         class Child(Cached):
-            def get_info(self, value):  # type: ignore[reportIncompatibleVariableOverride]
+            def get_info(self, value):  # type: ignore
                 return super().get_info(value) + 1
 
         cache = self.cache(2)
@@ -787,6 +785,8 @@ class UnboundMethodTest(unittest.TestCase):
     def test_wrapped_method(self):
         cached = Cached(Cache(2))
         self.assertIs(Cached.get.__wrapped__, cached.get.__wrapped__)
+        self.assertEqual(Cached.get.__name__, "get")
+        self.assertEqual(Cached.get.__qualname__, "Cached.get")
         self.assertEqual(Cached.get.__wrapped__(cached, 1), 0)
         self.assertEqual(Cached.get.__wrapped__(cached, 1), 1)
         self.assertEqual(len(cached.cache), 0)

{cachetools-7.2.2 → cachetools-7.2.3}/tests/test_func.py

@@ -132,10 +132,54 @@ class DecoratorTestMixin(SimplifiedTestCaseProtocol):
         self.assertEqual(cached.get.cache_info(), (0, 0, 2, 0))
         self.assertEqual(Cached.get.cache_info(), (0, 0, 2, 0))
 
+    def test_stacked_decorators(self):
+        inner_wrapper = self.decorator(maxsize=2)(lambda n: n)
+        outer_wrapper = self.decorator(maxsize=3, typed=True)(inner_wrapper)
+        self.assertIs(outer_wrapper.__wrapped__, inner_wrapper)
+        self.assertEqual(
+            inner_wrapper.cache_parameters(), {"maxsize": 2, "typed": False}
+        )
+        self.assertEqual(
+            outer_wrapper.cache_parameters(), {"maxsize": 3, "typed": True}
+        )
+        self.assertEqual(outer_wrapper(1), 1)
+        self.assertEqual(outer_wrapper(1), 1)
+        self.assertEqual(outer_wrapper.cache_info(), (1, 1, 3, 1))
+        self.assertEqual(inner_wrapper.cache_info(), (0, 1, 2, 1))
+        outer_wrapper.cache_clear()
+        self.assertEqual(outer_wrapper.cache_info(), (0, 0, 3, 0))
+        self.assertEqual(inner_wrapper.cache_info(), (0, 1, 2, 1))
+
 
 class FIFODecoratorTest(unittest.TestCase, DecoratorTestMixin):
     DECORATOR = staticmethod(cachetools.func.fifo_cache)
 
+    def test_method_typed(self):
+        """Type-checked by pyright via the stub __get__ overloads."""
+
+        class Cached:
+            @cachetools.func.fifo_cache(maxsize=2)
+            def get(self, n: int) -> int:
+                return n
+
+            @cachetools.func.fifo_cache
+            def get_bare(self, n: int) -> int:
+                return n
+
+            @staticmethod
+            @cachetools.func.fifo_cache
+            def get_static(n: int) -> int:
+                return n
+
+        cached = Cached()
+        result: int = cached.get(1)
+        self.assertEqual(result, 1)
+        self.assertEqual(Cached.get(cached, 1), 1)
+        self.assertEqual(cached.get.cache_info(), (1, 1, 2, 1))
+        self.assertEqual(cached.get_bare(1), 1)
+        self.assertEqual(cached.get_static(1), 1)
+        self.assertEqual(Cached.get_static(1), 1)
+
 
 class LFUDecoratorTest(unittest.TestCase, DecoratorTestMixin):
     DECORATOR = staticmethod(cachetools.func.lfu_cache)