cachetools 7.0.0__tar.gz → 7.0.2__tar.gz

{cachetools-7.0.0 → cachetools-7.0.2}/CHANGELOG.rst

@@ -1,3 +1,18 @@
+v7.0.2 (2026-03-02)
+===================
+
+- Provide more efficient ``clear()`` implementation for all support
+  Cache classes (courtesy Josep Pon Farreny).
+
+
+v7.0.1 (2026-02-10)
+===================
+
+- Various test improvements.
+
+- Update Copilot Instructions.
+
+
 v7.0.0 (2026-02-01)
 ===================
 

{cachetools-7.0.0/src/cachetools.egg-info → cachetools-7.0.2}/PKG-INFO

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

{cachetools-7.0.0 → cachetools-7.0.2}/src/cachetools/__init__.py

@@ -12,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "7.0.0"
+__version__ = "7.0.2"
 
 import collections
 import collections.abc
@@ -41,6 +41,9 @@ class _DefaultSize:
     def pop(self, _key):
         return 1
 
+    def clear(self):
+        pass
+
 
 class Cache(collections.abc.MutableMapping):
     """Mutable mapping to serve as a simple cache or cache base class."""
@@ -134,6 +137,17 @@ class Cache(collections.abc.MutableMapping):
             self[key] = value = default
         return value
 
+    # Although the MutableMapping.clear() default implementation works
+    # perfectly well, it calls popitem() in a loop until the cache is
+    # empty, resulting in O(n) complexity.  For large caches, this
+    # becomes a significant performance bottleneck, so we provide an
+    # optimized version for each Cache subclass.
+
+    def clear(self):
+        self.__data.clear()
+        self.__size.clear()
+        self.__currsize = 0
+
     @property
     def maxsize(self):
         """The maximum size of the cache."""
@@ -177,6 +191,10 @@ class FIFOCache(Cache):
         else:
             return (key, self.pop(key))
 
+    def clear(self):
+        Cache.clear(self)
+        self.__order.clear()
+
 
 class LFUCache(Cache):
     """Least Frequently Used (LFU) cache implementation."""
@@ -237,6 +255,12 @@ class LFUCache(Cache):
         key = next(iter(curr.keys))  # remove an arbitrary element
         return (key, self.pop(key))
 
+    def clear(self):
+        Cache.clear(self)
+        root = self.__root
+        root.prev = root.next = root
+        self.__links.clear()
+
     def __touch(self, key):
         """Increment use count"""
         link = self.__links[key]
@@ -286,6 +310,10 @@ class LRUCache(Cache):
         else:
             return (key, self.pop(key))
 
+    def clear(self):
+        Cache.clear(self)
+        self.__order.clear()
+
     def __touch(self, key):
         """Mark as recently used"""
         try:
@@ -332,6 +360,11 @@ class RRCache(Cache):
         else:
             return (key, self.pop(key))
 
+    def clear(self):
+        Cache.clear(self)
+        self.__index.clear()
+        del self.__keys[:]
+
 
 class _TimedCache(Cache):
     """Base class for time aware cache implementations."""
@@ -389,11 +422,6 @@ class _TimedCache(Cache):
         """The timer function used by the cache."""
         return self.__timer
 
-    def clear(self):
-        with self.__timer as time:
-            self.expire(time)
-            Cache.clear(self)
-
     def get(self, *args, **kwargs):
         with self.__timer:
             return Cache.get(self, *args, **kwargs)
@@ -406,6 +434,12 @@ class _TimedCache(Cache):
         with self.__timer:
             return Cache.setdefault(self, *args, **kwargs)
 
+    def clear(self):
+        # Subclasses must override to also reset their own time-tracking
+        # structures; we do not call expire() here since clear() should
+        # be O(1) regardless of cache contents.
+        Cache.clear(self)
+
 
 class TTLCache(_TimedCache):
     """LRU Cache implementation with per-item time-to-live (TTL) value."""
@@ -536,6 +570,12 @@ class TTLCache(_TimedCache):
             else:
                 return (key, self.pop(key))
 
+    def clear(self):
+        _TimedCache.clear(self)
+        root = self.__root
+        root.prev = root.next = root
+        self.__links.clear()
+
     def __getlink(self, key):
         value = self.__links[key]
         self.__links.move_to_end(key)
@@ -660,6 +700,11 @@ class TLRUCache(_TimedCache):
             else:
                 return (key, self.pop(key))
 
+    def clear(self):
+        _TimedCache.clear(self)
+        self.__items.clear()
+        del self.__order[:]
+
     def __getitem(self, key):
         value = self.__items[key]
         self.__items.move_to_end(key)

{cachetools-7.0.0 → cachetools-7.0.2/src/cachetools.egg-info}/PKG-INFO

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

{cachetools-7.0.0 → cachetools-7.0.2}/tests/__init__.py

@@ -266,6 +266,57 @@ class CacheTestMixin:
 
         self._test_getsizeof(Cache(maxsize=3))
 
+    def test_clear(self):
+        cache = self.Cache(maxsize=2)
+        cache.update({1: 1, 2: 2})
+
+        self.assertEqual(2, len(cache))
+        self.assertEqual(2, cache.currsize)
+
+        cache.clear()
+
+        self.assertEqual(0, len(cache))
+        self.assertEqual(0, cache.currsize)
+        self.assertNotIn(1, cache)
+        self.assertNotIn(2, cache)
+
+        # verify cache can be reused after clear
+        cache[3] = 3
+        cache[4] = 4
+        self.assertEqual(2, len(cache))
+        self.assertEqual(3, cache[3])
+        self.assertEqual(4, cache[4])
+
+        # verify eviction still works after clear
+        cache[5] = 5
+        self.assertEqual(2, len(cache))
+        self.assertIn(5, cache)
+
+    def test_clear_empty(self):
+        cache = self.Cache(maxsize=2)
+        cache.clear()  # should not raise
+        self.assertEqual(0, len(cache))
+        self.assertEqual(0, cache.currsize)
+
+    def test_clear_getsizeof(self):
+        cache = self.Cache(maxsize=10, getsizeof=lambda x: x)
+        cache[1] = 1
+        cache[2] = 2
+        cache[3] = 3
+
+        self.assertEqual(3, len(cache))
+        self.assertEqual(6, cache.currsize)
+
+        cache.clear()
+
+        self.assertEqual(0, len(cache))
+        self.assertEqual(0, cache.currsize)
+
+        # verify cache can be reused with getsizeof after clear
+        cache[4] = 4
+        self.assertEqual(1, len(cache))
+        self.assertEqual(4, cache.currsize)
+
     def test_pickle(self):
         import pickle
 

{cachetools-7.0.0 → cachetools-7.0.2}/tests/test_classmethod.py

@@ -75,7 +75,7 @@ class CachedClassMethodTest(unittest.TestCase):
             self.assertEqual(Cached.get_typed(0), 1)
         self.assertEqual(len(w), 2)
         self.assertIs(w[0].category, DeprecationWarning)
-        self.assertIs(w[0].category, DeprecationWarning)
+        self.assertIs(w[1].category, DeprecationWarning)
 
         with warnings.catch_warnings():
             warnings.simplefilter("ignore")
@@ -99,7 +99,7 @@ class CachedClassMethodTest(unittest.TestCase):
             self.assertEqual(Cached.get_locked(0), 1)
         self.assertEqual(len(w), 2)
         self.assertIs(w[0].category, DeprecationWarning)
-        self.assertIs(w[0].category, DeprecationWarning)
+        self.assertIs(w[1].category, DeprecationWarning)
 
     def test_condition(self):
         Cached.cache = LRUCache(2)
@@ -112,7 +112,7 @@ class CachedClassMethodTest(unittest.TestCase):
             self.assertEqual(Cached.get_condition(0), 1)
         self.assertEqual(len(w), 2)
         self.assertIs(w[0].category, DeprecationWarning)
-        self.assertIs(w[0].category, DeprecationWarning)
+        self.assertIs(w[1].category, DeprecationWarning)
 
     def test_clear(self):
         Cached.cache = LRUCache(2)

{cachetools-7.0.0 → cachetools-7.0.2}/tests/test_keys.py

@@ -34,7 +34,7 @@ class CacheKeysTest(unittest.TestCase):
         self.assertNotEqual(key("x", 1, 2, 3, x=0), key("x", 1, 2, 3, x=None))
         self.assertNotEqual(key("x", 1, 2, 3, x=0), key("x", 1, 2, 3, y=0))
         with self.assertRaises(TypeError):
-            hash("x", key({}))
+            hash(key("x", {}))
         # 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)))

{cachetools-7.0.0 → cachetools-7.0.2}/tests/test_lfu.py

@@ -64,3 +64,27 @@ class LFUCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertEqual(cache[1], "updated")
         self.assertIn(3, cache)
         self.assertNotIn(2, cache)
+
+    def test_lfu_clear(self):
+        cache = LFUCache(maxsize=2)
+
+        cache[1] = 1
+        cache[1]  # increment frequency
+        cache[1]  # increment frequency again
+        cache[2] = 2
+
+        cache.clear()
+
+        self.assertEqual(0, len(cache))
+        self.assertEqual(0, cache.currsize)
+
+        # verify LFU frequency tracking is reset after clear
+        cache[3] = 3
+        cache[4] = 4
+        cache[3]  # access 3 to increment frequency
+        cache[5] = 5  # should evict 4 (least frequently used)
+
+        self.assertEqual(2, len(cache))
+        self.assertIn(3, cache)
+        self.assertIn(5, cache)
+        self.assertNotIn(4, cache)

{cachetools-7.0.0 → cachetools-7.0.2}/tests/test_lru.py

@@ -66,3 +66,24 @@ class LRUCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertEqual(cache[1], "updated")
         self.assertIn(3, cache)
         self.assertNotIn(2, cache)
+
+    def test_lru_clear(self):
+        cache = LRUCache(maxsize=2)
+
+        cache[1] = 1
+        cache[2] = 2
+        cache.clear()
+
+        self.assertEqual(0, len(cache))
+        self.assertEqual(0, cache.currsize)
+
+        # verify LRU order is reset after clear
+        cache[3] = 3
+        cache[4] = 4
+        cache[3]  # access 3 to make it most recently used
+        cache[5] = 5  # should evict 4 (least recently used)
+
+        self.assertEqual(2, len(cache))
+        self.assertIn(3, cache)
+        self.assertIn(5, cache)
+        self.assertNotIn(4, cache)

{cachetools-7.0.0 → cachetools-7.0.2}/tests/test_rr.py

@@ -77,6 +77,11 @@ class RRCacheTest(unittest.TestCase, CacheTestMixin):
         cache[2] = 2
         with self.assertRaises(ValueError):
             cache[3] = 3
+        self.assertEqual(len(cache), 2)
+        self.assertEqual(cache.currsize, 2)
+        self.assertIn(1, cache)
+        self.assertIn(2, cache)
+        self.assertNotIn(3, cache)
 
     def test_rr_default_choice(self):
         cache = RRCache(maxsize=2)

{cachetools-7.0.0 → cachetools-7.0.2}/tests/test_tlru.py

@@ -6,6 +6,10 @@ from cachetools import TLRUCache
 from . import CacheTestMixin
 
 
+def default_ttu(_key, _value, _time):
+    return math.inf
+
+
 class Timer:
     def __init__(self, auto=False):
         self.auto = auto
@@ -21,9 +25,6 @@ class Timer:
 
 
 class TLRUTestCache(TLRUCache):
-    def default_ttu(_key, _value, _time):
-        return math.inf
-
     def __init__(self, maxsize, ttu=default_ttu, **kwargs):
         TLRUCache.__init__(self, maxsize, ttu, timer=Timer(), **kwargs)
 
@@ -269,3 +270,60 @@ class TLRUCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertNotIn(1, cache)
         self.assertNotIn(2, cache)
         self.assertNotIn(3, cache)
+
+    def test_ttu_heap_cleanup(self):
+        cache = TLRUCache(maxsize=4, ttu=lambda k, v, t: t + 1, timer=Timer())
+        self.assertEqual(0, cache.timer())
+
+        cache[1] = 1
+        cache[2] = 2
+
+        # replace items to accumulate removed entries in the internal heap
+        for i in range(5):
+            cache[1] = 10 + i
+            cache[2] = 20 + i
+
+        # this should compact the internal heap
+        expired = cache.expire()
+        self.assertEqual([], expired)
+
+        # verify cache is functional after cleanup
+        self.assertEqual(2, len(cache))
+        self.assertEqual(14, cache[1])
+        self.assertEqual(24, cache[2])
+        cache[3] = 3
+        cache[4] = 4
+        self.assertEqual(4, len(cache))
+
+        cache.timer.tick()
+        expired = cache.expire()
+        self.assertEqual(4, len(expired))
+        self.assertEqual(0, len(cache))
+
+    def test_tlru_clear(self):
+        cache = TLRUCache(maxsize=2, ttu=lambda k, v, t: t + 2, timer=Timer())
+
+        cache[1] = 1
+        cache[2] = 2
+        cache.clear()
+
+        self.assertEqual(0, len(cache))
+        self.assertEqual(0, cache.currsize)
+
+        # verify LRU eviction order is reset after clear
+        cache[3] = 3
+        cache[4] = 4
+        cache[3]  # access 3 to make it most recently used
+        cache[5] = 5  # should evict 4 (least recently used)
+
+        self.assertEqual(2, len(cache))
+        self.assertIn(3, cache)
+        self.assertIn(5, cache)
+        self.assertNotIn(4, cache)
+
+        # verify TLRU expiry still works after clear
+        cache[42] = 42
+        cache.timer.tick()
+        cache.timer.tick()
+        cache.timer.tick()  # past TTL
+        self.assertNotIn(42, cache)

{cachetools-7.0.0 → cachetools-7.0.2}/tests/test_ttl.py

@@ -84,6 +84,20 @@ class TTLCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertEqual(0, len(cache))
         self.assertEqual(set(), set(cache))
 
+    def test_ttl_timer(self):
+        cache = TTLCache(maxsize=2, ttl=2, timer=Timer())
+        self.assertEqual(cache.timer.time, 0)
+        self.assertFalse(cache.timer.auto)
+
+        cache[1] = 1
+        cache.timer.tick()
+        self.assertEqual(cache.timer.time, 1)
+        self.assertEqual(1, cache[1])
+
+        cache.timer.tick()
+        self.assertEqual(cache.timer.time, 2)
+        self.assertNotIn(1, cache)
+
     def test_ttl_lru(self):
         cache = TTLCache(maxsize=2, ttl=1, timer=Timer())
 
@@ -201,3 +215,31 @@ class TTLCacheTest(unittest.TestCase, CacheTestMixin):
         items = cache.expire(datetime.now() + timedelta(days=1))
         self.assertEqual([(1, 1)], list(items))
         self.assertEqual(0, len(cache))
+
+    def test_ttl_clear(self):
+        cache = TTLCache(maxsize=2, ttl=2, timer=Timer())
+
+        cache[1] = 1
+        cache[2] = 2
+        cache.clear()
+
+        self.assertEqual(0, len(cache))
+        self.assertEqual(0, cache.currsize)
+
+        # verify LRU eviction order is reset after clear
+        cache[3] = 3
+        cache[4] = 4
+        cache[3]  # access 3 to make it most recently used
+        cache[5] = 5  # should evict 4 (least recently used)
+
+        self.assertEqual(2, len(cache))
+        self.assertIn(3, cache)
+        self.assertIn(5, cache)
+        self.assertNotIn(4, cache)
+
+        # verify TTL expiry still works after clear
+        cache[42] = 42
+        cache.timer.tick()
+        cache.timer.tick()
+        cache.timer.tick()  # past TTL
+        self.assertNotIn(42, cache)