cachetools 7.2.1__tar.gz → 7.2.3__tar.gz

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

@@ -1,3 +1,26 @@
+v7.2.3 (2026-10-17)
+===================
+
+- Fix ``@cached`` decorator stacking behavior.
+
+- Minor type stub improvements.
+
+
+v7.2.2 (2026-10-15)
+===================
+
+- Fix ``@cachedmethod`` for subclasses that override a decorated
+  method and call the base class implementation via ``super()``.
+
+- Restore class access to instance methods decorated with
+  ``@cachedmethod``.
+
+- Improve ``TTLCache`` robustness when calculating expiration time
+  fails.
+
+- Various unit test improvements.
+
+
 v7.2.1 (2026-10-05)
 ===================
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.2.1
+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.1 → 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.1 → cachetools-7.2.3}/src/cachetools/__init__.py

@@ -12,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "7.2.1"
+__version__ = "7.2.3"
 
 import collections
 import collections.abc
@@ -495,6 +495,7 @@ class TTLCache(_TimedCache):
 
     def __setitem__(self, key, value, cache_setitem=Cache.__setitem__):
         with self.timer as time:
+            expires = time + self.__ttl
             self.expire(time)
             cache_setitem(self, key, value)
         try:
@@ -503,7 +504,7 @@ class TTLCache(_TimedCache):
             self.__links[key] = link = TTLCache._Link(key)
         else:
             link.unlink()
-        link.expires = time + self.__ttl
+        link.expires = expires
         link.next = root = self.__root
         link.prev = prev = root.prev
         prev.next = root.prev = link

{cachetools-7.2.1 → 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
@@ -191,16 +224,34 @@ def cached(
     info: Literal[True],
 ) -> Callable[[Callable[_P, _R]], _cached_wrapper_info[_P, _R]]: ...
 
+@type_check_only
+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: ...
+    # deprecated @classmethod use
+    @overload
+    def __call__(self, /, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
+
 @type_check_only
 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] = ...
     cache_lock: AbstractContextManager[Any] | None = None
     cache_condition: _AbstractCondition | None = None
     def __set_name__(self, owner: type, name: str) -> None: ...
+    @overload
+    def __get__(
+        self, obj: None, objtype: type | None = None
+    ) -> _cachedmethod_unbound[_P, _R]: ...
+    @overload
     def __get__(
         self, obj: Any, objtype: type | None = None
     ) -> _cachedmethod_wrapper[_P, _R]: ...
@@ -209,6 +260,11 @@ class _cachedmethod_wrapper(Generic[_P, _R]):
 
 @type_check_only
 class _cachedmethod_wrapper_info(_cachedmethod_wrapper[_P, _R]):
+    @overload
+    def __get__(
+        self, obj: None, objtype: type | None = None
+    ) -> _cachedmethod_unbound[_P, _R]: ...
+    @overload
     def __get__(
         self, obj: Any, objtype: type | None = None
     ) -> _cachedmethod_wrapper_info[_P, _R]: ...

{cachetools-7.2.1 → 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.1 → cachetools-7.2.3}/src/cachetools/_cachedmethod.py

@@ -5,24 +5,9 @@
 __all__ = ()
 
 import functools
-import warnings
 import weakref
 
-
-def _warn_classmethod(stacklevel):
-    warnings.warn(
-        "decorating class methods with @cachedmethod is deprecated",
-        DeprecationWarning,
-        stacklevel=stacklevel,
-    )
-
-
-def _warn_instance_dict(msg, stacklevel):
-    warnings.warn(
-        msg,
-        DeprecationWarning,
-        stacklevel=stacklevel,
-    )
+from ._descriptor import _ClassMethodDescriptor, _MethodDescriptor, _warn_classmethod
 
 
 def _none(_):
@@ -65,82 +50,6 @@ class _WrapperBase:
         return self.__cond(self._obj)
 
 
-class _DescriptorBase:
-    """Descriptor base class implementing the basic descriptor protocol."""
-
-    def __init__(self, deprecated=False):
-        self.__attrname = None
-        self.__deprecated = deprecated
-
-    def __set_name__(self, owner, name):
-        if self.__attrname is None:
-            self.__attrname = name
-        elif name != self.__attrname:
-            raise TypeError(
-                "Cannot assign the same @cachedmethod to two different names "
-                f"({self.__attrname!r} and {name!r})."
-            )
-
-    def __get__(self, obj, objtype=None):
-        wrapper = self.Wrapper(obj)  # type: ignore
-        if obj is None:
-            # Return the wrapper itself without modification when accessed
-            # through the class to support class-level introspection, such
-            # as for mocking with autospec=True in unittest.mock.
-            pass
-        elif self.__attrname is not None:
-            # replace descriptor instance with wrapper in instance dict
-            try:
-                # In case of a race condition where another thread already replaced
-                # the descriptor, prefer the initial wrapper.
-                wrapper = obj.__dict__.setdefault(self.__attrname, wrapper)
-            except AttributeError:
-                # not all objects have __dict__ (e.g. class defines slots)
-                msg = (
-                    f"No '__dict__' attribute on {type(obj).__name__!r} "
-                    f"instance to cache {self.__attrname!r} property."
-                )
-                if self.__deprecated:
-                    _warn_instance_dict(msg, 3)
-                else:
-                    raise TypeError(msg) from None
-            except TypeError:
-                msg = (
-                    f"The '__dict__' attribute on {type(obj).__name__!r} "
-                    f"instance does not support item assignment for "
-                    f"caching {self.__attrname!r} property."
-                )
-                if self.__deprecated:
-                    _warn_instance_dict(msg, 3)
-                else:
-                    raise TypeError(msg) from None
-        elif self.__deprecated:
-            pass  # deprecated @classmethod, warning already raised elsewhere
-        else:
-            msg = "Cannot use @cachedmethod instance without calling __set_name__ on it"
-            raise TypeError(msg) from None
-        return wrapper
-
-
-class _DeprecatedDescriptorBase(_DescriptorBase):
-    """Descriptor base class supporting deprecated @classmethod use."""
-
-    def __init__(self, wrapper, cache_clear):
-        super().__init__(deprecated=True)
-        self.__wrapper = wrapper
-        self.__cache_clear = cache_clear
-
-    # called for @classmethod with Python >= 3.13
-    def __call__(self, *args, **kwargs):
-        _warn_classmethod(stacklevel=3)
-        return self.__wrapper(*args, **kwargs)
-
-    # backward-compatible @classmethod handling with Python >= 3.13
-    def cache_clear(self, objtype):
-        _warn_classmethod(stacklevel=3)
-        return self.__cache_clear(objtype)
-
-
 # At least for now, the implementation prefers clarity and performance
 # over ease of maintenance, thus providing separate descriptors for
 # all valid combinations of decorator parameters lock, condition and
@@ -148,7 +57,7 @@ class _DeprecatedDescriptorBase(_DescriptorBase):
 
 
 def _condition_info(method, cache, key, lock, cond, info):
-    class Descriptor(_DescriptorBase):
+    class Descriptor(_MethodDescriptor):
         class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key, lock, cond)
@@ -196,7 +105,7 @@ def _condition_info(method, cache, key, lock, cond, info):
 
 
 def _locked_info(method, cache, key, lock, info):
-    class Descriptor(_DescriptorBase):
+    class Descriptor(_MethodDescriptor):
         class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key, lock)
@@ -236,7 +145,7 @@ def _locked_info(method, cache, key, lock, info):
 
 
 def _unlocked_info(method, cache, key, info):
-    class Descriptor(_DescriptorBase):
+    class Descriptor(_MethodDescriptor):
         class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key)
@@ -303,7 +212,7 @@ def _condition(method, cache, key, lock, cond):
         p = pending.setdefault(self, set())
         return wrapper(self, p, *args, **kwargs)
 
-    class Descriptor(_DeprecatedDescriptorBase):
+    class Descriptor(_ClassMethodDescriptor):
         class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key, lock, cond)
@@ -343,7 +252,7 @@ def _locked(method, cache, key, lock):
         with lock(self):
             c.clear()
 
-    class Descriptor(_DeprecatedDescriptorBase):
+    class Descriptor(_ClassMethodDescriptor):
         class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key, lock)
@@ -377,7 +286,7 @@ def _unlocked(method, cache, key):
         c = cache(self)
         c.clear()
 
-    class Descriptor(_DeprecatedDescriptorBase):
+    class Descriptor(_ClassMethodDescriptor):
         class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key)

cachetools-7.2.3/src/cachetools/_descriptor.py

@@ -0,0 +1,126 @@
+"""Descriptor helpers."""
+
+__all__ = ()
+
+import functools
+import warnings
+
+
+def _warn_classmethod(stacklevel):
+    warnings.warn(
+        "decorating class methods with @cachedmethod is deprecated",
+        DeprecationWarning,
+        stacklevel=stacklevel,
+    )
+
+
+def _warn_instance_dict(msg, stacklevel):
+    warnings.warn(
+        msg,
+        DeprecationWarning,
+        stacklevel=stacklevel,
+    )
+
+
+class _MethodDescriptor:
+    """Descriptor class implementing the basic descriptor protocol."""
+
+    def __init__(self, deprecated=False):
+        self.__attrname = None
+        self.__deprecated = deprecated
+        self.__unbound = None
+
+    def __set_name__(self, owner, name):
+        if self.__attrname is None:
+            self.__attrname = name
+        elif name != self.__attrname:
+            raise TypeError(
+                "Cannot assign the same @cachedmethod to two different names "
+                f"({self.__attrname!r} and {name!r})."
+            )
+
+    def __get__(self, obj, objtype=None):
+        if obj is None:
+            # objtype is not used for instance lookups, so it need not be bound here
+            return self.__get_unbound()
+        elif self.__attrname is not None:
+            # replace descriptor instance with wrapper in instance dict
+            wrapper = self.Wrapper(obj)  # type: ignore
+            try:
+                descriptor = next(
+                    (
+                        cls.__dict__[self.__attrname]
+                        for cls in type(obj).__mro__
+                        if self.__attrname in cls.__dict__
+                    ),
+                    None,
+                )
+                if descriptor is self:
+                    # In case of a race condition where another thread already replaced
+                    # the descriptor, prefer the initial wrapper.
+                    wrapper = obj.__dict__.setdefault(self.__attrname, wrapper)
+                else:
+                    # A super() lookup must neither reuse the override's wrapper
+                    # nor replace it, so preserve state separately for each descriptor.
+                    wrappers = obj.__dict__.setdefault("__cachetools_cachedmethods", {})
+                    wrapper = wrappers.setdefault(self, wrapper)
+            except AttributeError:
+                # not all objects have __dict__ (e.g. class defines slots)
+                msg = (
+                    f"No '__dict__' attribute on {type(obj).__name__!r} "
+                    f"instance to cache {self.__attrname!r} property."
+                )
+                if self.__deprecated:
+                    _warn_instance_dict(msg, 3)
+                else:
+                    raise TypeError(msg) from None
+            except TypeError:
+                msg = (
+                    f"The '__dict__' attribute on {type(obj).__name__!r} "
+                    f"instance does not support item assignment for "
+                    f"caching {self.__attrname!r} property."
+                )
+                if self.__deprecated:
+                    _warn_instance_dict(msg, 3)
+                else:
+                    raise TypeError(msg) from None
+        elif self.__deprecated:
+            # deprecated @classmethod, warning already raised elsewhere
+            wrapper = self.Wrapper(obj)  # type: ignore
+        else:
+            msg = "Cannot use @cachedmethod instance without calling __set_name__ on it"
+            raise TypeError(msg) from None
+        return wrapper
+
+    def __get_unbound(self):
+        # Created once and shared by all class accesses; objtype is not
+        # used for instance lookups, so it need not be bound here.
+        if self.__unbound is None:
+            descriptor = self
+
+            # As in the previous function wrapper, the receiver is named self.
+            @functools.wraps(self.__wrapped__)  # type: ignore
+            def unbound(self, *args, **kwargs):
+                return descriptor.__get__(self)(*args, **kwargs)
+
+            self.__unbound = unbound  # type: ignore
+        return self.__unbound
+
+
+class _ClassMethodDescriptor(_MethodDescriptor):
+    """Descriptor base class supporting deprecated @classmethod use."""
+
+    def __init__(self, wrapper, cache_clear):
+        super().__init__(deprecated=True)
+        self.__wrapper = wrapper
+        self.__cache_clear = cache_clear
+
+    # called for @classmethod with Python >= 3.13
+    def __call__(self, *args, **kwargs):
+        _warn_classmethod(stacklevel=3)
+        return self.__wrapper(*args, **kwargs)
+
+    # backward-compatible @classmethod handling with Python >= 3.13
+    def cache_clear(self, objtype):
+        _warn_classmethod(stacklevel=3)
+        return self.__cache_clear(objtype)

{cachetools-7.2.1 → 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.1 → cachetools-7.2.3/src/cachetools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.2.1
+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.1 → cachetools-7.2.3}/src/cachetools.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/cachetools/__init__.py
 src/cachetools/__init__.pyi
 src/cachetools/_cached.py
 src/cachetools/_cachedmethod.py
+src/cachetools/_descriptor.py
 src/cachetools/func.py
 src/cachetools/func.pyi
 src/cachetools/keys.py

{cachetools-7.2.1 → cachetools-7.2.3}/tests/__init__.py

@@ -5,7 +5,7 @@ from typing import Any, Protocol
 import cachetools
 
 
-class _TestCaseProtocol(Protocol):
+class SimplifiedTestCaseProtocol(Protocol):
     def assertEqual(self, first: Any, second: Any, msg: Any = None) -> None: ...
     def assertNotEqual(self, first: Any, second: Any, msg: Any = None) -> None: ...
     def assertTrue(self, expr: Any, msg: Any = None) -> None: ...
@@ -29,7 +29,7 @@ class _TestCaseProtocol(Protocol):
     ) -> Any: ...
 
 
-class CacheTestMixin(_TestCaseProtocol):
+class CacheTestMixin(SimplifiedTestCaseProtocol):
     Cache: type[cachetools.Cache]
 
     def test_defaults(self):

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

@@ -4,10 +4,10 @@ import warnings
 import cachetools
 import cachetools.keys
 
-from . import CountedCondition, CountedLock, _TestCaseProtocol
+from . import CountedCondition, CountedLock, SimplifiedTestCaseProtocol
 
 
-class DecoratorTestMixin(_TestCaseProtocol):
+class DecoratorTestMixin(SimplifiedTestCaseProtocol):
     def cache(self, minsize):
         raise NotImplementedError
 
@@ -154,6 +154,8 @@ class DecoratorTestMixin(_TestCaseProtocol):
         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)
@@ -380,6 +397,47 @@ class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin):
         self.assertEqual(wrapper.cache_info(), (0, 1, 0, 0))
         self.assertEqual(lock.count, 5)
 
+    def test_decorator_method(self):
+        """Though it is not encouraged, like functools.lru_cache, the
+        @cached decorator may be used on methods, too.
+
+        """
+
+        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_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)
+        self.assertEqual(Cached.get(cached, 1), 1)
+        self.assertEqual(len(cache), 1)
+        cached.get.cache_clear()
+        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):
     def cache(self, minsize):

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

@@ -1,10 +1,9 @@
 import unittest
-import unittest.mock
 import warnings
 
 from cachetools import Cache, cachedmethod, keys
 
-from . import CountedCondition, CountedLock, _TestCaseProtocol
+from . import CountedCondition, CountedLock, SimplifiedTestCaseProtocol
 
 
 class Cached:
@@ -77,7 +76,7 @@ class Unhashable(Cached):
         raise TypeError("unhashable type")
 
 
-class MethodDecoratorTestMixin(_TestCaseProtocol):
+class MethodDecoratorTestMixin(SimplifiedTestCaseProtocol):
     def cache(self, _minsize, **_kwargs):
         raise NotImplementedError
 
@@ -357,6 +356,7 @@ class MethodDecoratorTestMixin(_TestCaseProtocol):
         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)
@@ -632,6 +632,69 @@ class CacheMethodTest(unittest.TestCase, MethodDecoratorTestMixin):
         self.assertEqual(cached.get(2), 2)
         self.assertNotIn(2, cache.values())
 
+    def test_undecorated_override(self):
+        class Child(Cached):
+            def get_info(self, value):  # type: ignore
+                return super().get_info(value) + 1
+
+        cache = self.cache(2)
+        cached = Child(cache)
+        self.assertEqual(cached.get_info(0), 1)
+        self.assertEqual(cached.get_info(0), 1)
+        self.assertEqual(super(Child, cached).get_info(0), 0)
+        self.assertEqual(cached.get_info(1), 2)
+        self.assertEqual(super(Child, cached).get_info(1), 1)
+        self.assertNotIn("get_info", vars(cached))
+        self.assertEqual(super(Child, cached).get_info.cache_info(), (3, 2, 2, 2))
+
+    def test_decorated_override(self):
+        class Child(Cached):
+            def __init__(self, base_cache, child_cache):
+                super().__init__(base_cache)
+                self.child_cache = child_cache
+
+            @cachedmethod(lambda self: self.child_cache, info=True)
+            def get_info(self, value):
+                return super().get_info(value) + 1
+
+        cached = Child(self.cache(2), self.cache(2))
+        self.assertEqual(cached.get_info(0), 1)
+        self.assertEqual(cached.get_info(0), 1)
+        self.assertEqual(super(Child, cached).get_info(0), 0)
+        self.assertEqual(cached.get_info(1), 2)
+        self.assertEqual(super(Child, cached).get_info(1), 1)
+        self.assertIn("get_info", vars(cached))
+        self.assertEqual(cached.get_info.cache_info(), (1, 2, 2, 2))
+        self.assertEqual(super(Child, cached).get_info.cache_info(), (2, 2, 2, 2))
+        cached.get_info.cache_clear()
+        self.assertEqual(cached.get_info.cache_info(), (0, 0, 2, 0))
+        self.assertEqual(super(Child, cached).get_info.cache_info(), (2, 2, 2, 2))
+        self.assertEqual(cached.get_info(0), 1)
+        self.assertEqual(cached.get_info.cache_info(), (0, 1, 2, 1))
+        self.assertEqual(super(Child, cached).get_info.cache_info(), (3, 2, 2, 2))
+        super(Child, cached).get_info.cache_clear()
+        self.assertEqual(cached.get_info.cache_info(), (0, 1, 2, 1))
+        self.assertEqual(super(Child, cached).get_info.cache_info(), (0, 0, 2, 0))
+
+    def test_multilevel_override(self):
+        class Child(Cached):
+            @cachedmethod(lambda self: self.cache, key=keys.typedmethodkey)
+            def get_typed(self, value):
+                return super().get_typed(float(value)) + 1
+
+        class GrandChild(Child):
+            @cachedmethod(lambda self: self.cache, key=keys.typedmethodkey, info=True)
+            def get_typed(self, value):
+                return super().get_typed(int(value)) + 1
+
+        cache = self.cache(5)  # shared cache, but different key types
+        cached = GrandChild(cache)
+        self.assertEqual(cached.get_typed("0"), 2)
+        self.assertEqual(cached.get_typed("0"), 2)
+        self.assertEqual(cached.get_typed.cache_info(), (1, 1, 5, 3))
+        self.assertEqual(super(GrandChild, cached).get_typed(0), 1)
+        self.assertEqual(super(Child, cached).get_typed(0.0), 0)
+
 
 class DictMethodTest(unittest.TestCase, MethodDecoratorTestMixin):
     def cache(self, minsize, **_kwargs):
@@ -683,8 +746,53 @@ class NoneMethodTest(unittest.TestCase):
             wrapper.cache_info()
 
 
-class AutospecTest(unittest.TestCase):
+class UnboundMethodTest(unittest.TestCase):
+    def test_class_call(self):
+        cached = Cached(Cache(2))
+        self.assertEqual(Cached.get(cached, 1), 0)
+        self.assertEqual(cached.get(1), 0)
+        self.assertEqual(Cached.get(cached, 2), 1)
+        self.assertEqual(cached.get(2), 1)
+        self.assertEqual(cached.count, 2)
+        other = Cached(Cache(2), count=10)
+        self.assertEqual(Cached.get(other, 1), 10)
+        self.assertEqual(cached.get(1), 0)
+
+    def test_class_call_info(self):
+        cached = Cached(Cache(2))
+        self.assertEqual(Cached.get_info(cached, 1), 0)
+        self.assertEqual(cached.get_info(1), 0)
+        self.assertEqual(Cached.get_info(cached, 2), 1)
+        self.assertEqual(cached.get_info(2), 1)
+        self.assertEqual(cached.count, 2)
+        self.assertEqual(cached.get_info.cache_info(), (2, 2, 2, 2))
+        other = Cached(Cache(2), count=10)
+        self.assertEqual(Cached.get_info(other, 1), 10)
+        self.assertEqual(cached.get_info(1), 0)
+
+    def test_base_class_call(self):
+        cached = Unhashable(Cache(2))
+        self.assertEqual(Cached.get(cached, 1), 0)
+        self.assertEqual(cached.get(1), 0)
+        self.assertEqual(cached.count, 1)
+
+    def test_class_access_identity(self):
+        self.assertIs(Cached.get, Cached.get)
+        self.assertIs(Cached.get_info, Cached.get_info)
+        self.assertIs(Unhashable.get, Cached.get)
+        self.assertIsNot(Cached.get, Cached.get_info)
+
+    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)
+
     def test_autospec_no_warnings(self):
+        import unittest.mock
 
         with warnings.catch_warnings(record=True) as w:
             warnings.simplefilter("always")

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

@@ -4,10 +4,10 @@ from typing import Any
 
 import cachetools.func
 
-from . import _TestCaseProtocol
+from . import SimplifiedTestCaseProtocol
 
 
-class DecoratorTestMixin(_TestCaseProtocol):
+class DecoratorTestMixin(SimplifiedTestCaseProtocol):
     DECORATOR: Callable[..., Any]
 
     def decorator(self, maxsize, **kwargs):
@@ -109,10 +109,77 @@ class DecoratorTestMixin(_TestCaseProtocol):
         # Then do a call which will cause a deadlock with a non-reentrant lock.
         self.assertEqual(cached(RecursiveEquals(True)), RecursiveEquals(True))
 
+    def test_decorator_method(self):
+        """Though it is not encouraged, like functools.lru_cache, the
+        cachetools.func decorators may be used on methods, too.
+
+        """
+
+        decorator = self.decorator(maxsize=2)
+
+        class Cached:
+            @decorator
+            def get(self, n):
+                return n
+
+        cached = Cached()
+        self.assertEqual(cached.get(1), 1)
+        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))
+        cached.get.cache_clear()
+        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)

cachetools-7.2.3/tests/test_threading.py

@@ -0,0 +1,103 @@
+import unittest
+from threading import Barrier, Condition, Lock, Thread
+
+from cachetools import LRUCache, cached, cachedmethod
+
+
+class ThreadingTest(unittest.TestCase):
+    NTHREADS = 10
+
+    TIMEOUT = 10
+
+    def test_cached_lock(self):
+        for info in (False, True):
+            with self.subTest(info=info):
+                barrier = Barrier(self.NTHREADS, timeout=self.TIMEOUT)
+                cache = LRUCache(1)
+
+                @cached(cache, lock=Lock(), info=info)
+                def func(barrier=barrier):
+                    result = object()
+                    barrier.wait()
+                    return result
+
+                self.run_lock_test(func, cache, info)
+
+    def test_cachedmethod_lock(self):
+        for info in (False, True):
+            with self.subTest(info=info):
+                barrier = Barrier(self.NTHREADS, timeout=self.TIMEOUT)
+                cache = LRUCache(1)
+                lock = Lock()
+
+                class Cached:
+                    @cachedmethod(lambda _: cache, lock=lambda _: lock, info=info)
+                    def method(self, barrier=barrier):
+                        result = object()
+                        barrier.wait()
+                        return result
+
+                self.run_lock_test(Cached().method, cache, info)
+
+    def test_cached_cond(self):
+        for info in (False, True):
+            with self.subTest(info=info):
+                cache = LRUCache(1)
+
+                @cached(cache, condition=Condition(), info=info)
+                def func():
+                    result = object()
+                    return result
+
+                self.run_cond_test(func, cache, info)
+
+    def test_cachedmethod_cond(self):
+        for info in (False, True):
+            with self.subTest(info=info):
+                cache = LRUCache(1)
+                cond = Condition()
+
+                class Cached:
+                    @cachedmethod(lambda _: cache, condition=lambda _: cond, info=info)
+                    def method(self):
+                        result = object()
+                        return result
+
+                self.run_cond_test(Cached().method, cache, info)
+
+    def run_lock_test(self, func, cache, info):
+        self.run_threading_test(func, cache)
+
+        if info:
+            cache_info = func.cache_info()
+            self.assertEqual(cache_info.hits + cache_info.misses, self.NTHREADS)
+            self.assertGreaterEqual(cache_info.misses, 1)
+
+    def run_cond_test(self, func, cache, info):
+        self.run_threading_test(func, cache)
+
+        if info:
+            cache_info = func.cache_info()
+            self.assertEqual(cache_info.hits, self.NTHREADS - 1)
+            self.assertEqual(cache_info.misses, 1)
+
+    def run_threading_test(self, func, cache):
+        results = [None] * self.NTHREADS
+
+        def run(index):
+            results[index] = func()
+
+        threads = [Thread(target=run, args=[i]) for i in range(self.NTHREADS)]
+        for thread in threads:
+            thread.start()
+        for thread in threads:
+            thread.join(timeout=self.TIMEOUT)
+            self.assertFalse(thread.is_alive())
+        self.assertEqual(len(cache), 1)
+
+        # multiple threads may compute the value, but the first one
+        # should always win and all concurrent invocations should
+        # return the same result
+        cached_result = next(iter(cache.values()))
+        for result in results:
+            self.assertIs(result, cached_result)

{cachetools-7.2.1 → cachetools-7.2.3}/tests/test_ttl.py

@@ -218,6 +218,22 @@ class TTLCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertEqual([(1, 1)], list(items))
         self.assertEqual(0, len(cache))
 
+    def test_ttl_datetime_overflow(self):
+        from datetime import datetime, timedelta
+
+        cache = TTLCache[str, int, datetime](
+            maxsize=1, ttl=timedelta(days=1), timer=lambda: datetime.max
+        )
+
+        with self.assertRaises(OverflowError):
+            cache["overflow"] = 1
+
+        self.assertNotIn("overflow", cache)
+        self.assertEqual(0, len(cache))
+        self.assertEqual(0, cache.currsize)
+        self.assertEqual([], list(cache))
+        self.assertEqual([], cache.expire())
+
     def test_ttl_clear(self):
         cache = TTLCache[int, int, int](maxsize=2, ttl=2, timer=Timer())
 

cachetools-7.2.1/tests/test_threading.py

@@ -1,122 +0,0 @@
-import threading
-import time
-import unittest
-from typing import Any
-
-from cachetools import LRUCache, cached, cachedmethod
-
-count = 0
-
-
-@cached(cache=LRUCache(1), condition=threading.Condition(), info=True)
-def func():
-    global count
-    time.sleep(1.0)
-    count += 1
-    return count
-
-
-@cached(cache=LRUCache(1), lock=threading.Lock(), info=True)
-def locked_func():
-    global count
-    time.sleep(1.0)
-    count += 1
-    return 42
-
-
-class ThreadingTest(unittest.TestCase):
-    NTHREADS = 10
-
-    TIMEOUT = 10
-
-    cache: LRUCache[Any, int] = LRUCache(1)
-
-    cond = threading.Condition()
-
-    lock = threading.Lock()
-
-    count = 0
-
-    @cachedmethod(
-        cache=lambda self: self.cache, condition=lambda self: self.cond, info=True
-    )
-    def method(self):
-        time.sleep(1.0)
-        self.count += 1
-        return 42
-
-    @cachedmethod(cache=lambda self: self.cache, lock=lambda self: self.lock, info=True)
-    def locked_method(self):
-        time.sleep(1.0)
-        self.count += 1
-        return 42
-
-    def test_cached_stampede(self):
-        global count
-        count = 0
-        threads = [threading.Thread(target=func) for i in range(self.NTHREADS)]
-        for t in threads:
-            t.start()
-        for t in threads:
-            t.join(timeout=self.TIMEOUT)
-            self.assertFalse(t.is_alive())
-
-        self.assertEqual(count, 1)
-
-        info = func.cache_info()
-        self.assertEqual(info.hits, self.NTHREADS - 1)
-        self.assertEqual(info.misses, 1)
-
-    def test_cachedmethod_stampede(self):
-        self.cache = LRUCache(1)
-        self.count = 0
-        threads = [threading.Thread(target=self.method) for i in range(self.NTHREADS)]
-        for t in threads:
-            t.start()
-        for t in threads:
-            t.join(timeout=self.TIMEOUT)
-            self.assertFalse(t.is_alive())
-
-        self.assertEqual(self.count, 1)
-
-        info = self.method.cache_info()
-        self.assertEqual(info.hits, self.NTHREADS - 1)
-        self.assertEqual(info.misses, 1)
-
-    def test_cached_locked(self):
-        global count
-        count = 0
-        threads = [threading.Thread(target=locked_func) for i in range(self.NTHREADS)]
-        for t in threads:
-            t.start()
-        for t in threads:
-            t.join(timeout=self.TIMEOUT)
-            self.assertFalse(t.is_alive())
-
-        # Without condition/stampede prevention, func is called by multiple
-        # threads, but all return the same cached value (42).
-        self.assertGreaterEqual(count, 1)
-
-        info = locked_func.cache_info()
-        self.assertEqual(info.hits + info.misses, self.NTHREADS)
-        self.assertGreaterEqual(info.misses, 1)
-
-    def test_cachedmethod_locked(self):
-        self.cache = LRUCache(1)
-        self.count = 0
-        threads = [
-            threading.Thread(target=self.locked_method) for i in range(self.NTHREADS)
-        ]
-        for t in threads:
-            t.start()
-        for t in threads:
-            t.join(timeout=self.TIMEOUT)
-            self.assertFalse(t.is_alive())
-
-        # Multiple threads may compute the value, but setdefault ensures
-        # the first cached result wins and all return 42.
-        self.assertGreaterEqual(self.count, 1)
-
-        info = self.locked_method.cache_info()
-        self.assertEqual(info.hits + info.misses, self.NTHREADS)
-        self.assertGreaterEqual(info.misses, 1)