cachetools 7.2.7__tar.gz → 7.3.0__tar.gz

{cachetools-7.2.7 → cachetools-7.3.0}/CHANGELOG.rst

@@ -1,3 +1,24 @@
+v7.3.0 (2026-11-05)
+===================
+
+- Use ``OrderedDict`` for defined and faster ``LFUCache`` eviction.
+
+- Various unit test improvements.
+
+- Minor type stub improvements.
+
+- Minor documentation improvements.
+
+
+v7.2.8 (2026-10-31)
+===================
+
+- Fix type stubs for ``TTLCache`` and ``TLRUCache`` with default
+  ``timer``.
+
+- Minor documentation and unit test improvements.
+
+
 v7.2.7 (2026-10-28)
 ===================
 

{cachetools-7.2.7/src/cachetools.egg-info → cachetools-7.3.0}/PKG-INFO

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

{cachetools-7.2.7 → cachetools-7.3.0}/docs/conf.py

@@ -13,6 +13,5 @@ extensions = [
     "sphinx.ext.todo",
 ]
 exclude_patterns = ["_build"]
-master_doc = "index"
 html_theme = "classic"
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

{cachetools-7.2.7 → cachetools-7.3.0}/docs/index.rst

@@ -92,10 +92,17 @@ inserted into the cache.
    :members: popitem
 
    This class counts how often an item is retrieved, and discards the
-   items used least often to make space when necessary.
+   items used least often to make space when necessary.  In case of a
+   tie, the least recently used of these items is discarded.
 
-   Updating a cache item via :meth:`LFUCache.__setitem__` also counts
-   as a use of the item, i.e. it will increment the item's use count.
+   Inserting or updating a cache item via :meth:`LFUCache.__setitem__`
+   also counts as a use of the item; an update will increment the
+   item's use count.
+
+   .. versionchanged:: 7.3
+
+      Switched to discarding the least recently used item in case of
+      a tie.  Previously, an arbitrary item was discarded.
 
 .. autoclass:: LRUCache(maxsize, getsizeof=None)
    :members: popitem
@@ -356,6 +363,16 @@ often called with the same arguments:
    implement the `context manager`_ protocol, and will also be used to
    guard access to the cache.
 
+   .. note::
+
+      Even though `lock` and `condition` can be passed separately,
+      the condition variable must be associated with the lock that
+      guards the cache.  In practice, when using
+      :class:`threading.Lock` and :class:`threading.Condition`, the
+      condition variable must be created with the corresponding lock,
+      e.g. ``condition=threading.Condition(lock)``; an unrelated
+      :class:`threading.Condition` will raise :exc:`RuntimeError`.
+
    The decorator's `cache`, `key`, `lock` and `condition` parameters
    are also available as :attr:`cache`, :attr:`cache_key`,
    :attr:`cache_lock` and :attr:`cache_condition` attributes of the
@@ -548,6 +565,8 @@ often called with the same arguments:
       `lock(self)` will only guard access to the cache itself.  It is
       the user's responsibility to handle concurrent calls to the
       underlying wrapped method in a multithreaded environment.
+      Likewise, a condition variable returned by `condition(self)`
+      must be associated with a lock returned by `lock(self)`.
 
    Similarly to the :func:`cached` function decorator, the `cache`,
    `key`, `lock` and `condition` parameters are also available as

{cachetools-7.2.7 → cachetools-7.3.0}/src/cachetools/__init__.py

@@ -12,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "7.2.7"
+__version__ = "7.3.0"
 
 import collections
 import collections.abc
@@ -212,7 +212,7 @@ class LFUCache(Cache):
 
         def __init__(self, count):
             self.count = count
-            self.keys = set()
+            self.keys = collections.OrderedDict()
 
         def unlink(self):
             next = self.next
@@ -244,13 +244,13 @@ class LFUCache(Cache):
             link.next = root.next
             root.next = link.next.prev = link
             link.prev = root
-        link.keys.add(key)
+        link.keys[key] = None
         self.__links[key] = link
 
     def __delitem__(self, key, cache_delitem=Cache.__delitem__):
         cache_delitem(self, key)
         link = self.__links.pop(key)
-        link.keys.remove(key)
+        del link.keys[key]
         if not link.keys:
             link.unlink()
 
@@ -260,7 +260,7 @@ class LFUCache(Cache):
         curr = root.next
         if curr is root:
             raise KeyError("%s is empty" % type(self).__name__) from None
-        key = next(iter(curr.keys))  # remove an arbitrary element
+        key = next(iter(curr.keys))  # remove the "oldest" element
         value = Cache.__getitem__(self, key)
         del self[key]
         return (key, value)
@@ -283,8 +283,8 @@ class LFUCache(Cache):
             curr.next = link.next
             link.next = curr.next.prev = curr
             curr.prev = link
-        curr.keys.add(key)
-        link.keys.remove(key)
+        curr.keys[key] = None
+        del link.keys[key]
         if not link.keys:
             link.unlink()
         self.__links[key] = curr

{cachetools-7.2.7 → cachetools-7.3.0}/src/cachetools/__init__.pyi

@@ -36,8 +36,6 @@ _T = TypeVar("_T")
 _KT = TypeVar("_KT")
 _VT = TypeVar("_VT")
 _TT = TypeVar("_TT", default=float)
-_KT2 = TypeVar("_KT2")
-_VT2 = TypeVar("_VT2")
 
 class Cache(MutableMapping[_KT, _VT]):
     def __init__(
@@ -53,7 +51,12 @@ class Cache(MutableMapping[_KT, _VT]):
     def pop(self, key: _KT) -> _VT: ...
     @overload
     def pop(self, key: _KT, default: _VT | _T) -> _VT | _T: ...
-    def setdefault(self, key: _KT, default: _VT | None = None) -> _VT: ...
+    @overload
+    def setdefault(
+        self: Cache[_KT, _T | None], key: _KT, default: None = None
+    ) -> _T | None: ...
+    @overload
+    def setdefault(self, key: _KT, default: _VT) -> _VT: ...
     @property
     def maxsize(self) -> float: ...
     @property
@@ -94,19 +97,19 @@ class _TimedCache(Cache[_KT, _VT], Generic[_KT, _VT, _TT]):
     def timer(self) -> _Timer[_TT]: ...
 
 class TTLCache(_TimedCache[_KT, _VT, _TT]):
-    @overload
+    @overload  # without timer, _TT takes its default
     def __init__(
-        self: TTLCache[_KT2, _VT2, float],
+        self,
         maxsize: float,
         ttl: float,
         *,
-        getsizeof: Callable[[_VT2], float] | None = None,
+        getsizeof: Callable[[_VT], float] | None = None,
     ) -> None: ...
     @overload
     def __init__(
         self,
         maxsize: float,
-        ttl: Any,  # FIXME: must be "addable" to _TT
+        ttl: Any,  # must be "addable" to _TT
         timer: Callable[[], _TT],
         getsizeof: Callable[[_VT], float] | None = None,
     ) -> None: ...
@@ -115,13 +118,13 @@ class TTLCache(_TimedCache[_KT, _VT, _TT]):
     def expire(self, time: _TT | None = None) -> list[tuple[_KT, _VT]]: ...
 
 class TLRUCache(_TimedCache[_KT, _VT, _TT]):
-    @overload
+    @overload  # without timer, _TT takes its default
     def __init__(
-        self: TLRUCache[_KT2, _VT2, float],
+        self,
         maxsize: float,
-        ttu: Callable[[_KT2, _VT2, float], float],
+        ttu: Callable[[_KT, _VT, float], float],
         *,
-        getsizeof: Callable[[_VT2], float] | None = None,
+        getsizeof: Callable[[_VT], float] | None = None,
     ) -> None: ...
     @overload
     def __init__(
@@ -143,8 +146,6 @@ class _CacheInfo(NamedTuple):
 
 @type_check_only
 class _AbstractCondition(AbstractContextManager[Any], Protocol):
-    # implementation and unit tests currently do not use plain wait()
-    # and notify(); these are reserved for future use
     def wait(self, timeout: float | None = None) -> bool: ...
     def wait_for(
         self, predicate: Callable[[], _T], timeout: float | None = None

{cachetools-7.2.7 → cachetools-7.3.0}/src/cachetools/_cachedmethod.py

@@ -35,7 +35,7 @@ class _WrapperBase:
         # wrappers
         return (self.__descriptor.__get__, (self._obj,))
 
-    def __call__(self, *args, **kwargs):
+    def __call__(self, /, *args, **kwargs):
         raise NotImplementedError()  # pragma: no cover
 
     def cache_clear(self):
@@ -72,7 +72,7 @@ def _condition_info(method, cache, key, lock, cond, info):
                 self.__hits = self.__misses = 0
                 self.__pending = set()
 
-            def __call__(self, *args, **kwargs):
+            def __call__(self, /, *args, **kwargs):
                 cache = self.cache
                 lock = self.cache_lock
                 cond = self.cache_condition
@@ -121,7 +121,7 @@ def _locked_info(method, cache, key, lock, info):
                 super().__init__(obj, descriptor, method, cache, key, lock)
                 self.__hits = self.__misses = 0
 
-            def __call__(self, *args, **kwargs):
+            def __call__(self, /, *args, **kwargs):
                 cache = self.cache
                 lock = self.cache_lock
                 key = self.cache_key(*args, **kwargs)
@@ -161,7 +161,7 @@ def _unlocked_info(method, cache, key, info):
                 super().__init__(obj, descriptor, method, cache, key)
                 self.__hits = self.__misses = 0
 
-            def __call__(self, *args, **kwargs):
+            def __call__(self, /, *args, **kwargs):
                 cache = self.cache
                 key = self.cache_key(*args, **kwargs)
                 try:
@@ -220,7 +220,7 @@ def _condition(method, cache, key, lock, cond):
         with lock(self):
             c.clear()
 
-    def classmethod_wrapper(self, *args, **kwargs):
+    def classmethod_wrapper(self, /, *args, **kwargs):
         p = pending.setdefault(self, set())
         return wrapper(self, p, *args, **kwargs)
 
@@ -230,7 +230,7 @@ def _condition(method, cache, key, lock, cond):
                 super().__init__(obj, descriptor, method, cache, key, lock, cond)
                 self.__pending = set()
 
-            def __call__(self, *args, **kwargs):
+            def __call__(self, /, *args, **kwargs):
                 return wrapper(self._obj, self.__pending, *args, **kwargs)
 
             # objtype: backward-compatible @classmethod handling with Python < 3.13
@@ -241,7 +241,7 @@ def _condition(method, cache, key, lock, cond):
 
 
 def _locked(method, cache, key, lock):
-    def wrapper(self, *args, **kwargs):
+    def wrapper(self, /, *args, **kwargs):
         c = cache(self)
         k = key(self, *args, **kwargs)
         with lock(self):
@@ -269,7 +269,7 @@ def _locked(method, cache, key, lock):
             def __init__(self, obj, descriptor):
                 super().__init__(obj, descriptor, method, cache, key, lock)
 
-            def __call__(self, *args, **kwargs):
+            def __call__(self, /, *args, **kwargs):
                 return wrapper(self._obj, *args, **kwargs)
 
             # objtype: backward-compatible @classmethod handling with Python < 3.13
@@ -280,7 +280,7 @@ def _locked(method, cache, key, lock):
 
 
 def _unlocked(method, cache, key):
-    def wrapper(self, *args, **kwargs):
+    def wrapper(self, /, *args, **kwargs):
         c = cache(self)
         k = key(self, *args, **kwargs)
         try:
@@ -303,7 +303,7 @@ def _unlocked(method, cache, key):
             def __init__(self, obj, descriptor):
                 super().__init__(obj, descriptor, method, cache, key)
 
-            def __call__(self, *args, **kwargs):
+            def __call__(self, /, *args, **kwargs):
                 return wrapper(self._obj, *args, **kwargs)
 
             # objtype: backward-compatible @classmethod handling with Python < 3.13

{cachetools-7.2.7 → cachetools-7.3.0}/src/cachetools/_descriptor.py

@@ -178,7 +178,7 @@ class _ClassMethodDescriptor(_MethodDescriptor):
         self.__cache_clear = cache_clear
 
     # called for @classmethod with Python >= 3.13
-    def __call__(self, *args, **kwargs):
+    def __call__(self, /, *args, **kwargs):
         _warn_classmethod(stacklevel=3)
         return self.__wrapper(*args, **kwargs)
 

{cachetools-7.2.7 → cachetools-7.3.0}/src/cachetools/keys.py

@@ -54,7 +54,7 @@ def hashkey(*args, **kwargs):
         return _HashedTuple(args)
 
 
-def methodkey(self, *args, **kwargs):
+def methodkey(self, /, *args, **kwargs):
     """Return a cache key for use with cached methods."""
     return hashkey(*args, **kwargs)
 
@@ -72,6 +72,6 @@ def typedkey(*args, **kwargs):
     return key
 
 
-def typedmethodkey(self, *args, **kwargs):
+def typedmethodkey(self, /, *args, **kwargs):
     """Return a typed cache key for use with cached methods."""
     return typedkey(*args, **kwargs)

{cachetools-7.2.7 → cachetools-7.3.0/src/cachetools.egg-info}/PKG-INFO

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

{cachetools-7.2.7 → cachetools-7.3.0}/tests/test_cached.py

@@ -438,6 +438,21 @@ class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin):
         self.assertEqual(cached.get_static(1), 1)
         self.assertEqual(Cached.get_static(1), 1)
 
+    def test_autospec(self):
+        import unittest.mock
+
+        class Cached:
+            @cachetools.cached(self.cache(2))
+            def get(self, value):
+                return value
+
+        mock = unittest.mock.create_autospec(Cached, instance=True)
+        mock.get.return_value = 42
+        self.assertEqual(mock.get(1), 42)
+        mock.get.assert_called_with(1)
+        self.assertEqual(mock.get(value=1), 42)
+        mock.get.assert_called_with(value=1)
+
 
 class DictWrapperTest(unittest.TestCase, DecoratorTestMixin):
     def cache(self, minsize):

{cachetools-7.2.7 → cachetools-7.3.0}/tests/test_cachedmethod.py

@@ -982,6 +982,10 @@ class NoneMethodTest(unittest.TestCase):
 
 class UnboundMethodTest(unittest.TestCase):
     def test_class_call(self):
+        for attr in ("cache", "cache_key", "cache_lock", "cache_condition"):
+            self.assertFalse(hasattr(Cached.get, attr))
+        for attr in ("cache_clear", "cache_info"):
+            self.assertFalse(hasattr(Cached.get, attr))
         cached = Cached(Cache(2))
         self.assertEqual(Cached.get(cached, 1), 0)
         self.assertEqual(cached.get(1), 0)
@@ -993,6 +997,10 @@ class UnboundMethodTest(unittest.TestCase):
         self.assertEqual(cached.get(1), 0)
 
     def test_class_call_info(self):
+        for attr in ("cache", "cache_key", "cache_lock", "cache_condition"):
+            self.assertFalse(hasattr(Cached.get_info, attr))
+        for attr in ("cache_clear", "cache_info"):
+            self.assertFalse(hasattr(Cached.get_info, attr))
         cached = Cached(Cache(2))
         self.assertEqual(Cached.get_info(cached, 1), 0)
         self.assertEqual(cached.get_info(1), 0)

{cachetools-7.2.7 → cachetools-7.3.0}/tests/test_classmethod.py

@@ -42,6 +42,12 @@ class Cached:
         cls.count += 1
         return cls.count
 
+    @classmethod
+    @cachedmethod(lambda cls: cls.cache)
+    def get_self(cls, self):
+        cls.count += 1
+        return cls.count
+
 
 class CachedClassMethodTest(unittest.TestCase):
     def test(self):
@@ -192,3 +198,15 @@ class CachedClassMethodTest(unittest.TestCase):
             self.assertEqual(len(Cached.cache), 1)
             Cached.get_condition.cache_clear(cached)  # type: ignore
             self.assertEqual(len(Cached.cache), 0)
+
+    def test_self_keyword(self):
+        # https://github.com/tkem/cachetools/issues/451
+        Cached.cache = LRUCache(2)
+        Cached.count = 0
+        cached = Cached()
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            self.assertEqual(Cached.get_self(self=0), 1)
+            self.assertEqual(cached.get_self(self=0), 1)
+            self.assertEqual(Cached.get_self(self=1), 2)

{cachetools-7.2.7 → cachetools-7.3.0}/tests/test_func.py

@@ -192,10 +192,75 @@ class LRUDecoratorTest(unittest.TestCase, DecoratorTestMixin):
 class RRDecoratorTest(unittest.TestCase, DecoratorTestMixin):
     DECORATOR = staticmethod(cachetools.func.rr_cache)
 
+    def test_rr_choice(self):
+        cached = cachetools.func.rr_cache(maxsize=2, choice=min)(lambda n: n)
+        self.assertEqual(cached.cache_parameters(), {"maxsize": 2, "typed": False})
+        self.assertEqual(cached(1), 1)
+        self.assertEqual(cached(2), 2)
+        self.assertEqual(cached.cache_info(), (0, 2, 2, 2))
+        # the smallest key, (1,), is evicted
+        self.assertEqual(cached(3), 3)
+        self.assertEqual(cached.cache_info(), (0, 3, 2, 2))
+        self.assertEqual(cached(2), 2)
+        self.assertEqual(cached(3), 3)
+        self.assertEqual(cached.cache_info(), (2, 3, 2, 2))
+        # now (2,) is the smallest key
+        self.assertEqual(cached(1), 1)
+        self.assertEqual(cached.cache_info(), (2, 4, 2, 2))
+        self.assertEqual(cached(3), 3)
+        self.assertEqual(cached.cache_info(), (3, 4, 2, 2))
+        self.assertEqual(cached(2), 2)
+        self.assertEqual(cached.cache_info(), (3, 5, 2, 2))
+
 
 class TTLDecoratorTest(unittest.TestCase, DecoratorTestMixin):
     DECORATOR = staticmethod(cachetools.func.ttl_cache)
 
+    class Timer:
+        def __init__(self):
+            self.time = 0
+
+        def __call__(self):
+            return self.time
+
+        def tick(self):
+            self.time += 1
+
+    def test_ttl_expire(self):
+        timer = self.Timer()
+        cached = cachetools.func.ttl_cache(maxsize=2, ttl=1, timer=timer)(lambda n: n)
+        self.assertEqual(cached.cache_parameters(), {"maxsize": 2, "typed": False})
+        self.assertEqual(cached(1), 1)
+        self.assertEqual(cached.cache_info(), (0, 1, 2, 1))
+        self.assertEqual(cached(1), 1)
+        self.assertEqual(cached.cache_info(), (1, 1, 2, 1))
+        timer.tick()
+        self.assertEqual(cached.cache_info(), (1, 1, 2, 0))
+        self.assertEqual(cached(1), 1)
+        self.assertEqual(cached.cache_info(), (1, 2, 2, 1))
+        self.assertEqual(cached(2), 2)
+        self.assertEqual(cached.cache_info(), (1, 3, 2, 2))
+        timer.tick()
+        self.assertEqual(cached(1), 1)
+        self.assertEqual(cached.cache_info(), (1, 4, 2, 1))
+
+    def test_ttl_expire_unbound(self):
+        timer = self.Timer()
+        cached = cachetools.func.ttl_cache(maxsize=None, ttl=1, timer=timer)(
+            lambda n: n
+        )
+        self.assertEqual(cached.cache_parameters(), {"maxsize": None, "typed": False})
+        self.assertEqual(cached.cache_info(), (0, 0, None, 0))
+        for n in range(256):
+            self.assertEqual(cached(n), n)
+        self.assertEqual(cached.cache_info(), (0, 256, None, 256))
+        self.assertEqual(cached(0), 0)
+        self.assertEqual(cached.cache_info(), (1, 256, None, 256))
+        timer.tick()
+        self.assertEqual(cached.cache_info(), (1, 256, None, 0))
+        self.assertEqual(cached(0), 0)
+        self.assertEqual(cached.cache_info(), (1, 257, None, 1))
+
     def test_ttl_datetime(self):
         from datetime import datetime, timedelta
 

{cachetools-7.2.7 → cachetools-7.3.0}/tests/test_keys.py

@@ -38,6 +38,9 @@ class CacheKeysTest(unittest.TestCase):
         # untyped keys compare equal
         self.assertEqual(key("x", 1, 2, 3), key("y", 1.0, 2.0, 3.0))
         self.assertEqual(hash(key("x", 1, 2, 3)), hash(key("y", 1.0, 2.0, 3.0)))
+        # "self" is positional-only, so it may also be a keyword argument
+        self.assertEqual(key("x", self=1), key("y", self=1))
+        self.assertNotEqual(key("x", self=1), key("x"))
 
     def test_typedkey(self, key=cachetools.keys.typedkey):
         self.assertEqual(key(), key())
@@ -54,6 +57,8 @@ class CacheKeysTest(unittest.TestCase):
             hash(key({}))
         # typed keys compare unequal
         self.assertNotEqual(key(1, 2, 3), key(1.0, 2.0, 3.0))
+        self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=0.0))
+        self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=False))
 
     def test_typedmethodkey(self, key=cachetools.keys.typedmethodkey):
         # similar to typedkey(), but ignores its first positional argument
@@ -71,6 +76,11 @@ class CacheKeysTest(unittest.TestCase):
             hash(key("x", {}))
         # typed keys compare unequal
         self.assertNotEqual(key("x", 1, 2, 3), key("x", 1.0, 2.0, 3.0))
+        self.assertNotEqual(key("x", 1, 2, 3, x=0), key("x", 1, 2, 3, x=0.0))
+        self.assertNotEqual(key("x", 1, 2, 3, x=0), key("x", 1, 2, 3, x=False))
+        # "self" is positional-only, so it may also be a keyword argument
+        self.assertEqual(key("x", self=1), key("y", self=1))
+        self.assertNotEqual(key("x", self=1), key("x", self=1.0))
 
     def test_addkeys(self, key=cachetools.keys.hashkey):
         self.assertIsInstance(key(), tuple)

{cachetools-7.2.7 → cachetools-7.3.0}/tests/test_lfu.py

@@ -18,39 +18,67 @@ class LFUCacheTest(unittest.TestCase, CacheTestMixin):
 
         self.assertEqual(len(cache), 2)
         self.assertEqual(cache[1], 1)
-        self.assertTrue(2 in cache or 3 in cache)
-        self.assertTrue(2 not in cache or 3 not in cache)
+        self.assertNotIn(2, cache)
+        self.assertEqual(cache[3], 3)
 
+        cache[3]
         cache[4] = 4
         self.assertEqual(len(cache), 2)
-        self.assertEqual(cache[4], 4)
-        self.assertEqual(cache[1], 1)
-
-        cache[1]
-        self.assertEqual(len(cache), 2)
-        self.assertEqual(cache[1], 1)
+        self.assertNotIn(1, cache)
+        self.assertEqual(cache[3], 3)
         self.assertEqual(cache[4], 4)
 
     def test_lfu_tie(self):
         cache = LFUCache[int, int](maxsize=3)
 
         cache[1] = 1
-        cache[1]
         cache[2] = 2
         cache[3] = 3
-        cache[4] = 4
 
+        cache[3]
+        cache[2]
+        cache[1]
+
+        # do not use self.assertEqual(cache[1], 1) here, since that
+        # would mess up usage counts
         self.assertEqual(len(cache), 3)
         self.assertIn(1, cache)
+        self.assertIn(2, cache)
+        self.assertIn(3, cache)
+
+        cache[4] = 4
+        self.assertEqual(len(cache), 3)
+        self.assertIn(1, cache)
+        self.assertIn(2, cache)
+        self.assertNotIn(3, cache)
         self.assertIn(4, cache)
-        self.assertTrue(2 in cache or 3 in cache)
-        self.assertTrue(2 not in cache or 3 not in cache)
 
+        cache[4]
         cache[5] = 5
         self.assertEqual(len(cache), 3)
         self.assertIn(1, cache)
+        self.assertNotIn(2, cache)
+        self.assertNotIn(3, cache)
+        self.assertIn(4, cache)
         self.assertIn(5, cache)
-        self.assertTrue(2 in cache or 3 in cache or 4 in cache)
+
+    def test_lfu_tie_insert_only(self):
+        cache = LFUCache[int, int](maxsize=3)
+
+        cache[1] = 1
+        cache[2] = 2
+        cache[3] = 3
+
+        # items never retrieved are tied at use count 1, so they are
+        # evicted in insertion order; the set-based implementation
+        # used up to v7.2 only fails this from key 17 on
+        for key in range(4, 20):
+            cache[key] = key
+            self.assertEqual(len(cache), 3)
+            self.assertNotIn(key - 3, cache)
+            self.assertIn(key - 2, cache)
+            self.assertIn(key - 1, cache)
+            self.assertIn(key, cache)
 
     def test_lfu_getsizeof(self):
         cache = LFUCache[int, int](maxsize=3, getsizeof=lambda x: x)

{cachetools-7.2.7 → cachetools-7.3.0}/tests/test_threading.py

@@ -5,8 +5,8 @@ from cachetools import LRUCache, cached, cachedmethod
 
 
 class WaitCondition(Condition):
-    def __init__(self):
-        super().__init__()
+    def __init__(self, lock=None):
+        super().__init__(lock)
         self.waiting = Event()
 
     def wait(self, timeout=None):
@@ -93,6 +93,90 @@ class ThreadingTest(unittest.TestCase):
                 func = Cached().method
                 self.run_cond_wait_test(func, cond, started, release, calls)
 
+    def test_cached_lock_cond(self):
+        for info in (False, True):
+            with self.subTest(info=info):
+                cache = LRUCache(1)
+                lock = Lock()
+                cond = WaitCondition(lock)
+                started = Event()
+                release = Event()
+                calls = []
+
+                @cached(cache, lock=lock, condition=cond, info=info)
+                def func(calls=calls, started=started, release=release):
+                    calls.append(None)
+                    started.set()
+                    release.wait(self.TIMEOUT)
+                    return object()
+
+                self.run_cond_wait_test(func, cond, started, release, calls)
+
+    def test_cachedmethod_lock_cond(self):
+        for info in (False, True):
+            with self.subTest(info=info):
+                cache = LRUCache(1)
+                lock = Lock()
+                cond = WaitCondition(lock)
+                started = Event()
+                release = Event()
+                calls = []
+
+                class Cached:
+                    @cachedmethod(
+                        lambda _: cache,
+                        lock=lambda _: lock,
+                        condition=lambda _: cond,
+                        info=info,
+                    )
+                    def method(
+                        self,
+                        calls=calls,
+                        started=started,
+                        release=release,
+                        timeout=self.TIMEOUT,
+                    ):
+                        calls.append(None)
+                        started.set()
+                        release.wait(timeout)
+                        return object()
+
+                func = Cached().method
+                self.run_cond_wait_test(func, cond, started, release, calls)
+
+    def test_cached_unrelated_lock_cond(self):
+        # a condition variable not created with the lock fails on
+        # the first cache miss, even without concurrent calls
+        for info in (False, True):
+            with self.subTest(info=info):
+
+                @cached(LRUCache(1), lock=Lock(), condition=Condition(), info=info)
+                def func():
+                    return object()
+
+                with self.assertRaises(RuntimeError):
+                    func()
+
+    def test_cachedmethod_unrelated_lock_cond(self):
+        for info in (False, True):
+            with self.subTest(info=info):
+                cache = LRUCache(1)
+                lock = Lock()
+                cond = Condition()
+
+                class Cached:
+                    @cachedmethod(
+                        lambda _: cache,
+                        lock=lambda _: lock,
+                        condition=lambda _: cond,
+                        info=info,
+                    )
+                    def method(self):
+                        return object()
+
+                with self.assertRaises(RuntimeError):
+                    Cached().method()
+
     def run_cond_wait_test(self, func, cond, started, release, calls):
         results = [None] * 2
 
@@ -122,14 +206,6 @@ class ThreadingTest(unittest.TestCase):
             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
 

{cachetools-7.2.7 → cachetools-7.3.0}/tests/test_tlru.py

@@ -248,7 +248,7 @@ class TLRUCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertEqual(1, len(cache))
 
     def test_ttu_atomic(self):
-        cache = TLRUCache[int, int, int](
+        cache = TLRUCache[int, int | None, int](
             maxsize=1, ttu=lambda k, v, t: t + 2, timer=Timer(auto=True)
         )
         cache[1] = 1
@@ -258,7 +258,7 @@ class TLRUCacheTest(unittest.TestCase, CacheTestMixin):
         cache[1] = 1
         self.assertEqual(1, cache.pop(1))
         cache[1] = 1
-        self.assertEqual(1, cache.setdefault(1))
+        self.assertEqual(1, cache.setdefault(1))  # implicit default=None
         cache[1] = 1
         cache.clear()
         self.assertEqual(0, len(cache))
@@ -400,3 +400,23 @@ class TLRUCacheTest(unittest.TestCase, CacheTestMixin):
         cache.timer.tick()
         cache.timer.tick()  # past TTL
         self.assertNotIn(42, cache)
+
+    def test_tlru_default_timer_stubs(self):
+        # type stubs must infer key and value types with the default timer
+        def ttu(_key: str, value: int, now: float) -> float:
+            return now + value
+
+        cache: TLRUCache[str, int] = TLRUCache(maxsize=2, ttu=ttu)
+
+        cache["a"] = 3600
+        self.assertEqual(3600, cache["a"])
+        self.assertEqual(1, len(cache))
+        self.assertIn("a", cache)
+
+        sized: TLRUCache[str, str] = TLRUCache(
+            maxsize=10, ttu=lambda _k, _v, now: now + 3600, getsizeof=len
+        )
+
+        sized["abc"] = "abc"
+        self.assertEqual("abc", sized["abc"])
+        self.assertEqual(3, sized.currsize)

{cachetools-7.2.7 → cachetools-7.3.0}/tests/test_ttl.py

@@ -189,7 +189,7 @@ class TTLCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertEqual([2], [key for key in cache])
 
     def test_ttl_atomic(self):
-        cache = TTLCache[int, int, int](maxsize=1, ttl=2, timer=Timer(auto=True))
+        cache = TTLCache[int, int | None, int](maxsize=1, ttl=2, timer=Timer(auto=True))
         cache[1] = 1
         self.assertEqual(1, cache[1])
         cache[1] = 1
@@ -197,7 +197,7 @@ class TTLCacheTest(unittest.TestCase, CacheTestMixin):
         cache[1] = 1
         self.assertEqual(1, cache.pop(1))
         cache[1] = 1
-        self.assertEqual(1, cache.setdefault(1))
+        self.assertEqual(1, cache.setdefault(1))  # implicit default=None
         cache[1] = 1
         cache.clear()
         self.assertEqual(0, len(cache))
@@ -272,3 +272,18 @@ class TTLCacheTest(unittest.TestCase, CacheTestMixin):
         cache.timer.tick()
         cache.timer.tick()  # past TTL
         self.assertNotIn(42, cache)
+
+    def test_ttl_default_timer_stubs(self):
+        # type stubs must infer key and value types with the default timer
+        cache: TTLCache[str, int] = TTLCache(maxsize=2, ttl=math.inf)
+
+        cache["a"] = 1
+        self.assertEqual(1, cache["a"])
+        self.assertEqual(1, len(cache))
+        self.assertIn("a", cache)
+
+        sized: TTLCache[str, str] = TTLCache(maxsize=10, ttl=math.inf, getsizeof=len)
+
+        sized["abc"] = "abc"
+        self.assertEqual("abc", sized["abc"])
+        self.assertEqual(3, sized.currsize)