cachetools 5.4.0__tar.gz → 5.5.0__tar.gz

{cachetools-5.4.0 → cachetools-5.5.0}/CHANGELOG.rst

@@ -1,3 +1,17 @@
+v5.5.0 (2024-08-18)
+===================
+
+- ``TTLCache.expire()`` returns iterable of expired ``(key, value)``
+  pairs.
+
+- ``TLRUCache.expire()`` returns iterable of expired ``(key, value)``
+  pairs.
+
+- Documentation improvements.
+
+- Update CI environment.
+
+
 v5.4.0 (2024-07-15)
 ===================
 

{cachetools-5.4.0/src/cachetools.egg-info → cachetools-5.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cachetools
-Version: 5.4.0
+Version: 5.5.0
 Summary: Extensible memoizing collections and decorators
 Home-page: https://github.com/tkem/cachetools/
 Author: Thomas Kemmer

{cachetools-5.4.0 → cachetools-5.5.0}/docs/index.rst

@@ -26,6 +26,8 @@ method calls.
    from unittest import mock
    urllib = mock.MagicMock()
 
+   import time
+
 
 Cache implementations
 =====================
@@ -153,6 +155,8 @@ computed when the item is inserted into the cache.
       items that have expired by the current value returned by
       :attr:`timer`.
 
+      :returns: An iterable of expired `(key, value)` pairs.
+
 .. autoclass:: TLRUCache(maxsize, ttu, timer=time.monotonic, getsizeof=None)
    :members: popitem, timer, ttu
 
@@ -164,18 +168,29 @@ computed when the item is inserted into the cache.
    value of `timer()`.
 
    .. testcode::
-
-      from datetime import datetime, timedelta
-
+   
       def my_ttu(_key, value, now):
-          # assume value.ttl contains the item's time-to-live in hours
-          return now + timedelta(hours=value.ttl)
+          # assume value.ttu contains the item's time-to-use in seconds
+          # note that the _key argument is ignored in this example
+          return now + value.ttu
 
-      cache = TLRUCache(maxsize=10, ttu=my_ttu, timer=datetime.now)
+      cache = TLRUCache(maxsize=10, ttu=my_ttu)
 
    The expression `ttu(key, value, timer())` defines the expiration
    time of a cache item, and must be comparable against later results
-   of `timer()`.
+   of `timer()`.  As with :class:`TTLCache`, a custom `timer` function
+   can be supplied, which does not have to return a numeric value.
+
+   .. testcode::
+
+      from datetime import datetime, timedelta
+
+      def datetime_ttu(_key, value, now):
+          # assume now to be of type datetime.datetime, and
+          # value.hours to contain the item's time-to-use in hours
+          return now + timedelta(hours=value.hours)
+
+      cache = TLRUCache(maxsize=10, ttu=datetime_ttu, timer=datetime.now)
 
    Items that expire because they have exceeded their time-to-use will
    be no longer accessible, and will be removed eventually.  If no
@@ -193,6 +208,8 @@ computed when the item is inserted into the cache.
       items that have expired by the current value returned by
       :attr:`timer`.
 
+      :returns: An iterable of expired `(key, value)` pairs.
+
 
 Extending cache classes
 =======================
@@ -217,6 +234,31 @@ cache, this can be achieved by overriding this method in a subclass:
    >>> c['c'] = 3
    Key "a" evicted with value "1"
 
+With :class:`TTLCache` and :class:`TLRUCache`, items may also be
+removed after they expire.  In this case, :meth:`popitem` will *not*
+be called, but :meth:`expire` will be called from the next mutating
+operation and will return an iterable of the expired `(key, value)`
+pairs.  By overrding :meth:`expire`, a subclass will be able to track
+expired items:
+
+.. doctest::
+   :pyversion: >= 3
+
+   >>> class ExpCache(TTLCache):
+   ...     def expire(self, time=None):
+   ...         items = super().expire(time)
+   ...         print(f"Expired items: {items}")
+   ...         return items
+
+   >>> c = ExpCache(maxsize=10, ttl=1.0)
+   >>> c['a'] = 1
+   Expired items: []
+   >>> c['b'] = 2
+   Expired items: []
+   >>> time.sleep(1.5)
+   >>> c['c'] = 3
+   Expired items: [('a', 1), ('b', 2)]
+
 Similar to the standard library's :class:`collections.defaultdict`,
 subclasses of :class:`Cache` may implement a :meth:`__missing__`
 method which is called by :meth:`Cache.__getitem__` if the requested

{cachetools-5.4.0 → cachetools-5.5.0}/src/cachetools/__init__.py

@@ -13,7 +13,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "5.4.0"
+__version__ = "5.5.0"
 
 import collections
 import collections.abc
@@ -26,7 +26,6 @@ from . import keys
 
 
 class _DefaultSize:
-
     __slots__ = ()
 
     def __getitem__(self, _):
@@ -378,7 +377,6 @@ class TTLCache(_TimedCache):
     """LRU Cache implementation with per-item time-to-live (TTL) value."""
 
     class _Link:
-
         __slots__ = ("key", "expires", "next", "prev")
 
         def __init__(self, key=None, expires=None):
@@ -469,19 +467,26 @@ class TTLCache(_TimedCache):
         return self.__ttl
 
     def expire(self, time=None):
-        """Remove expired items from the cache."""
+        """Remove expired items from the cache and return an iterable of the
+        expired `(key, value)` pairs.
+
+        """
         if time is None:
             time = self.timer()
         root = self.__root
         curr = root.next
         links = self.__links
+        expired = []
         cache_delitem = Cache.__delitem__
+        cache_getitem = Cache.__getitem__
         while curr is not root and not (time < curr.expires):
+            expired.append((curr.key, cache_getitem(self, curr.key)))
             cache_delitem(self, curr.key)
             del links[curr.key]
             next = curr.next
             curr.unlink()
             curr = next
+        return expired
 
     def popitem(self):
         """Remove and return the `(key, value)` pair least recently used that
@@ -508,7 +513,6 @@ class TLRUCache(_TimedCache):
 
     @functools.total_ordering
     class _Item:
-
         __slots__ = ("key", "expires", "removed")
 
         def __init__(self, key=None, expires=None):
@@ -583,7 +587,10 @@ class TLRUCache(_TimedCache):
         return self.__ttu
 
     def expire(self, time=None):
-        """Remove expired items from the cache."""
+        """Remove expired items from the cache and return an iterable of the
+        expired `(key, value)` pairs.
+
+        """
         if time is None:
             time = self.timer()
         items = self.__items
@@ -592,12 +599,16 @@ class TLRUCache(_TimedCache):
         if len(order) > len(items) * 2:
             self.__order = order = [item for item in order if not item.removed]
             heapq.heapify(order)
+        expired = []
         cache_delitem = Cache.__delitem__
+        cache_getitem = Cache.__getitem__
         while order and (order[0].removed or not (time < order[0].expires)):
             item = heapq.heappop(order)
             if not item.removed:
+                expired.append((item.key, cache_getitem(self, item.key)))
                 cache_delitem(self, item.key)
                 del items[item.key]
+        return expired
 
     def popitem(self):
         """Remove and return the `(key, value)` pair least recently used that

{cachetools-5.4.0 → cachetools-5.5.0/src/cachetools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cachetools
-Version: 5.4.0
+Version: 5.5.0
 Summary: Extensible memoizing collections and decorators
 Home-page: https://github.com/tkem/cachetools/
 Author: Thomas Kemmer

{cachetools-5.4.0 → cachetools-5.5.0}/tests/__init__.py

@@ -2,7 +2,6 @@ import unittest
 
 
 class CacheTestMixin:
-
     Cache = None
 
     def test_defaults(self):

{cachetools-5.4.0 → cachetools-5.5.0}/tests/test_cache.py

@@ -6,5 +6,4 @@ from . import CacheTestMixin
 
 
 class CacheTest(unittest.TestCase, CacheTestMixin):
-
     Cache = cachetools.Cache

{cachetools-5.4.0 → cachetools-5.5.0}/tests/test_fifo.py

@@ -6,7 +6,6 @@ from . import CacheTestMixin
 
 
 class LRUCacheTest(unittest.TestCase, CacheTestMixin):
-
     Cache = FIFOCache
 
     def test_fifo(self):

{cachetools-5.4.0 → cachetools-5.5.0}/tests/test_keys.py

@@ -21,6 +21,24 @@ class CacheKeysTest(unittest.TestCase):
         self.assertEqual(key(1, 2, 3), key(1.0, 2.0, 3.0))
         self.assertEqual(hash(key(1, 2, 3)), hash(key(1.0, 2.0, 3.0)))
 
+    def methodkey(self, key=cachetools.keys.methodkey):
+        # similar to hashkey(), but ignores its first positional argument
+        self.assertEqual(key("x"), key("y"))
+        self.assertEqual(hash(key("x")), hash(key("y")))
+        self.assertEqual(key("x", 1, 2, 3), key("y", 1, 2, 3))
+        self.assertEqual(hash(key("x", 1, 2, 3)), hash(key("y", 1, 2, 3)))
+        self.assertEqual(key("x", 1, 2, 3, x=0), key("y", 1, 2, 3, x=0))
+        self.assertEqual(hash(key("x", 1, 2, 3, x=0)), hash(key("y", 1, 2, 3, x=0)))
+        self.assertNotEqual(key("x", 1, 2, 3), key("x", 3, 2, 1))
+        self.assertNotEqual(key("x", 1, 2, 3), key("x", 1, 2, 3, x=None))
+        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({}))
+        # 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)))
+
     def test_typedkey(self, key=cachetools.keys.typedkey):
         self.assertEqual(key(), key())
         self.assertEqual(hash(key()), hash(key()))
@@ -37,6 +55,23 @@ class CacheKeysTest(unittest.TestCase):
         # typed keys compare unequal
         self.assertNotEqual(key(1, 2, 3), key(1.0, 2.0, 3.0))
 
+    def test_typedmethodkey(self, key=cachetools.keys.typedmethodkey):
+        # similar to typedkey(), but ignores its first positional argument
+        self.assertEqual(key("x"), key("y"))
+        self.assertEqual(hash(key("x")), hash(key("y")))
+        self.assertEqual(key("x", 1, 2, 3), key("y", 1, 2, 3))
+        self.assertEqual(hash(key("x", 1, 2, 3)), hash(key("y", 1, 2, 3)))
+        self.assertEqual(key("x", 1, 2, 3, x=0), key("y", 1, 2, 3, x=0))
+        self.assertEqual(hash(key("x", 1, 2, 3, x=0)), hash(key("y", 1, 2, 3, x=0)))
+        self.assertNotEqual(key("x", 1, 2, 3), key("x", 3, 2, 1))
+        self.assertNotEqual(key("x", 1, 2, 3), key("x", 1, 2, 3, x=None))
+        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(key("x", {}))
+        # typed keys compare unequal
+        self.assertNotEqual(key("x", 1, 2, 3), key("x", 1.0, 2.0, 3.0))
+
     def test_addkeys(self, key=cachetools.keys.hashkey):
         self.assertIsInstance(key(), tuple)
         self.assertIsInstance(key(1, 2, 3) + key(4, 5, 6), type(key()))

{cachetools-5.4.0 → cachetools-5.5.0}/tests/test_lfu.py

@@ -6,7 +6,6 @@ from . import CacheTestMixin
 
 
 class LFUCacheTest(unittest.TestCase, CacheTestMixin):
-
     Cache = LFUCache
 
     def test_lfu(self):

{cachetools-5.4.0 → cachetools-5.5.0}/tests/test_lru.py

@@ -6,7 +6,6 @@ from . import CacheTestMixin
 
 
 class LRUCacheTest(unittest.TestCase, CacheTestMixin):
-
     Cache = LRUCache
 
     def test_lru(self):

{cachetools-5.4.0 → cachetools-5.5.0}/tests/test_mru.py

@@ -7,12 +7,10 @@ from . import CacheTestMixin
 
 
 class MRUCacheTest(unittest.TestCase, CacheTestMixin):
-
     # TODO: method to create cache that can be overridden
     Cache = MRUCache
 
     def test_evict__writes_only(self):
-
         with warnings.catch_warnings(record=True) as w:
             warnings.simplefilter("always")
             cache = MRUCache(maxsize=2)

{cachetools-5.4.0 → cachetools-5.5.0}/tests/test_rr.py

@@ -6,7 +6,6 @@ from . import CacheTestMixin
 
 
 class RRCacheTest(unittest.TestCase, CacheTestMixin):
-
     Cache = RRCache
 
     def test_rr(self):

{cachetools-5.4.0 → cachetools-5.5.0}/tests/test_tlru.py

@@ -29,7 +29,6 @@ class TLRUTestCache(TLRUCache):
 
 
 class TLRUCacheTest(unittest.TestCase, CacheTestMixin):
-
     Cache = TLRUTestCache
 
     def test_ttu(self):
@@ -157,28 +156,32 @@ class TLRUCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertEqual(2, cache[2])
         self.assertEqual(3, cache[3])
 
-        cache.expire()
+        items = cache.expire()
+        self.assertEqual(set(), set(items))
         self.assertEqual({1, 2, 3}, set(cache))
         self.assertEqual(3, len(cache))
         self.assertEqual(1, cache[1])
         self.assertEqual(2, cache[2])
         self.assertEqual(3, cache[3])
 
-        cache.expire(3)
+        items = cache.expire(3)
+        self.assertEqual({(1, 1)}, set(items))
         self.assertEqual({2, 3}, set(cache))
         self.assertEqual(2, len(cache))
         self.assertNotIn(1, cache)
         self.assertEqual(2, cache[2])
         self.assertEqual(3, cache[3])
 
-        cache.expire(4)
+        items = cache.expire(4)
+        self.assertEqual({(2, 2)}, set(items))
         self.assertEqual({3}, set(cache))
         self.assertEqual(1, len(cache))
         self.assertNotIn(1, cache)
         self.assertNotIn(2, cache)
         self.assertEqual(3, cache[3])
 
-        cache.expire(5)
+        items = cache.expire(5)
+        self.assertEqual({(3, 3)}, set(items))
         self.assertEqual(set(), set(cache))
         self.assertEqual(0, len(cache))
         self.assertNotIn(1, cache)

{cachetools-5.4.0 → cachetools-5.5.0}/tests/test_ttl.py

@@ -26,7 +26,6 @@ class TTLTestCache(TTLCache):
 
 
 class TTLCacheTest(unittest.TestCase, CacheTestMixin):
-
     Cache = TTLTestCache
 
     def test_ttl(self):
@@ -132,28 +131,32 @@ class TTLCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertEqual(2, cache[2])
         self.assertEqual(3, cache[3])
 
-        cache.expire()
+        items = cache.expire()
+        self.assertEqual(set(), set(items))
         self.assertEqual({1, 2, 3}, set(cache))
         self.assertEqual(3, len(cache))
         self.assertEqual(1, cache[1])
         self.assertEqual(2, cache[2])
         self.assertEqual(3, cache[3])
 
-        cache.expire(3)
+        items = cache.expire(3)
+        self.assertEqual({(1, 1)}, set(items))
         self.assertEqual({2, 3}, set(cache))
         self.assertEqual(2, len(cache))
         self.assertNotIn(1, cache)
         self.assertEqual(2, cache[2])
         self.assertEqual(3, cache[3])
 
-        cache.expire(4)
+        items = cache.expire(4)
+        self.assertEqual({(2, 2)}, set(items))
         self.assertEqual({3}, set(cache))
         self.assertEqual(1, len(cache))
         self.assertNotIn(1, cache)
         self.assertNotIn(2, cache)
         self.assertEqual(3, cache[3])
 
-        cache.expire(5)
+        items = cache.expire(5)
+        self.assertEqual({(3, 3)}, set(items))
         self.assertEqual(set(), set(cache))
         self.assertEqual(0, len(cache))
         self.assertNotIn(1, cache)
@@ -192,7 +195,9 @@ class TTLCacheTest(unittest.TestCase, CacheTestMixin):
 
         cache[1] = 1
         self.assertEqual(1, len(cache))
-        cache.expire(datetime.now())
+        items = cache.expire(datetime.now())
+        self.assertEqual([], list(items))
         self.assertEqual(1, len(cache))
-        cache.expire(datetime.now() + timedelta(days=1))
+        items = cache.expire(datetime.now() + timedelta(days=1))
+        self.assertEqual([(1, 1)], list(items))
         self.assertEqual(0, len(cache))