cachetools 7.1.8__tar.gz → 7.2.1__tar.gz

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

@@ -1,3 +1,27 @@
+v7.2.1 (2026-10-05)
+===================
+
+- Improve error handling for ``RRCache.popitem()`` when the cache is
+  empty.
+
+- Minor style and documentation improvements.
+
+- Update CI environment.
+
+
+v7.2.0 (2026-09-16)
+===================
+
+- Deprecate use of ``cache=None`` to suppress caching with the
+  ``@cached`` decorator.
+
+- Add support for Python 3.15.
+
+- Minor test improvements.
+
+- Minor documentation updates.
+
+
 v7.1.8 (2026-08-31)
 ===================
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.1.8
+Version: 7.2.1
 Summary: Extensible memoizing collections and decorators
 Author-email: Thomas Kemmer <tkemmer@computer.org>
 Maintainer-email: Thomas Kemmer <tkemmer@computer.org>
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst

{cachetools-7.1.8 → cachetools-7.2.1}/docs/index.rst

@@ -261,7 +261,7 @@ key is not found:
    >>> class PepStore(LRUCache):
    ...     def __missing__(self, key):
    ...         """Retrieve text of a Python Enhancement Proposal"""
-   ...         url = 'http://www.python.org/dev/peps/pep-%04d/' % key
+   ...         url = 'https://peps.python.org/pep-%04d/' % key
    ...         with urllib.request.urlopen(url) as s:
    ...             pep = s.read()
    ...             self[key] = pep  # store text in cache
@@ -364,7 +364,7 @@ often called with the same arguments:
       @cached(cache=LRUCache(maxsize=640*1024, getsizeof=len), lock=threading.Lock())
       def get_pep(num):
           'Retrieve text of a Python Enhancement Proposal'
-          url = 'http://www.python.org/dev/peps/pep-%04d/' % num
+          url = 'https://peps.python.org/pep-%04d/' % num
           with urllib.request.urlopen(url) as s:
               return s.read()
 
@@ -396,7 +396,7 @@ often called with the same arguments:
 
       >>> @cached(cache=LRUCache(maxsize=32), info=True)
       ... def get_pep(num):
-      ...     url = 'http://www.python.org/dev/peps/pep-%04d/' % num
+      ...     url = 'https://peps.python.org/pep-%04d/' % num
       ...     with urllib.request.urlopen(url) as s:
       ...         return s.read()
 
@@ -451,7 +451,7 @@ often called with the same arguments:
 
       @cached(cache=LRUCache(maxsize=10), info=True)
       def _get_pep_wrapped(num):
-          url = "http://www.python.org/dev/peps/pep-%04d/" % num
+          url = "https://peps.python.org/pep-%04d/" % num
           try:
               with urllib.request.urlopen(url) as s:
                   return s.read()
@@ -519,6 +519,13 @@ often called with the same arguments:
       >>> foo(1)
       >>> foo(a=1)
 
+   .. deprecated:: 7.2
+
+      Passing :const:`None` as `cache` parameter is deprecated, and
+      support will be removed in the next major version.  This is
+      mainly for consistency with :func:`cachedmethod`, which no
+      longer supports returning :const:`None` from `cache(self)`.
+
 
 .. decorator:: cachedmethod(cache, key=cachetools.keys.methodkey, lock=None, condition=None, info=False)
 
@@ -566,7 +573,7 @@ often called with the same arguments:
       ...     @cachedmethod(lambda self: self.cache, lock=lambda self: self.lock, info=True)
       ...     def get(self, num):
       ...         """Retrieve text of a Python Enhancement Proposal"""
-      ...         url = 'http://www.python.org/dev/peps/pep-%04d/' % num
+      ...         url = 'https://peps.python.org/pep-%04d/' % num
       ...         with urllib.request.urlopen(url) as s:
       ...             return s.read()
 
@@ -620,7 +627,7 @@ often called with the same arguments:
           @cachedmethod(lambda self: self.cache, key=partial(methodkey, method='pep'))
           def get_pep(self, num):
               """Retrieve text of a Python Enhancement Proposal"""
-              url = 'http://www.python.org/dev/peps/pep-%04d/' % num
+              url = 'https://peps.python.org/pep-%04d/' % num
               with urllib.request.urlopen(url) as s:
                   return s.read()
 
@@ -649,31 +656,33 @@ often called with the same arguments:
 
    .. versionchanged:: 7.0
 
-   Added the `info` option for reporting per-instance cache
-   statistics.
+      Added the `info` option for reporting per-instance cache
+      statistics.
 
-   :func:`cachedmethod` attributes (:attr:`cache`, :attr:`cache_lock`,
-   etc.) are now implemented as properties for instance methods, and
-   are finally officially supported.
+      :func:`cachedmethod` attributes (:attr:`cache`,
+      :attr:`cache_lock`, etc.) are now implemented as properties for
+      instance methods, and are finally officially supported.
 
-   Require :attr:`__dict__` to be a mutable mapping to support
-   per-instance :func:`cache_info()`.
+      Require :attr:`__dict__` to be a mutable mapping to support
+      per-instance :func:`cache_info()`.
 
-   Returning :const:`None` from `cache(self)` is no longer supported.
+      Returning :const:`None` from `cache(self)` is no longer supported.
 
    .. deprecated:: 7.0
 
-   Using :func:`cachedmethod` with :func:`classmethod` is deprecated,
-   and support will be removed in the next major version.  This is
-   mostly due to the fact that chaining descriptors, i.e. using
-   descriptors with :func:`classmethod`, was deprecated in Python 3.11
-   and removed in Python 3.13.  When using :func:`cache_info()`, an
-   instance method is already required.
+      Using :func:`cachedmethod` with :func:`classmethod` is
+      deprecated, and support will be removed in the next major
+      version.  This is mostly due to the fact that chaining
+      descriptors, i.e. using descriptors with :func:`classmethod`,
+      was deprecated in Python 3.11 and removed in Python 3.13.  When
+      using :func:`cache_info()`, an instance method is already
+      required.
 
-   Using :func:`cachedmethod` with an instance that does not provide a
-   mutable :attr:`__dict__` attribute is deprecated, and may inflict a
-   noticeable performance penalty.  When using :func:`cache_info()`,
-   :attr:`__dict__` already has to be a mutable mapping.
+      Using :func:`cachedmethod` with an instance that does not
+      provide a mutable :attr:`__dict__` attribute is deprecated, and
+      may inflict a noticeable performance penalty.  When using
+      :func:`cache_info()`, :attr:`__dict__` already has to be a
+      mutable mapping.
 
 
 *****************************************************************
@@ -747,8 +756,9 @@ this module provides several memoizing function decorators with a
 similar API.  All these decorators wrap a function with a memoizing
 callable that saves up to the `maxsize` most recent calls, using
 different caching strategies.  If `maxsize` is set to :const:`None`,
-the caching strategy is effectively disabled and the cache can grow
-without bound.
+the size limit is disabled and the cache can grow without bound.
+For :func:`ttl_cache`, the time-to-live still applies, so cached
+results expire after `ttl` even without a size limit.
 
 If the optional argument `typed` is set to :const:`True`, function
 arguments of different types will be cached separately.  For example,
@@ -817,7 +827,7 @@ all the decorators in this module are thread-safe by default.
 .. _cache algorithm: https://en.wikipedia.org/wiki/Cache_algorithms
 .. _cache stampede: https://en.wikipedia.org/wiki/Cache_stampede
 .. _condition variable: https://docs.python.org/3/library/threading.html#condition-objects
-.. _context manager: https://docs.python.org/dev/glossary.html#term-context-manager
-.. _mapping: https://docs.python.org/dev/glossary.html#term-mapping
-.. _mutable: https://docs.python.org/dev/glossary.html#term-mutable
+.. _context manager: https://docs.python.org/3/glossary.html#term-context-manager
+.. _mapping: https://docs.python.org/3/glossary.html#term-mapping
+.. _mutable: https://docs.python.org/3/glossary.html#term-mutable
 .. _thread-safe: https://en.wikipedia.org/wiki/Thread_safety

{cachetools-7.1.8 → cachetools-7.2.1}/pyproject.toml

@@ -27,6 +27,7 @@ classifiers = [
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
     "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.15",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 
@@ -49,9 +50,6 @@ version = {attr = "cachetools.__version__"}
 
 [tool.pyright]
 typeCheckingMode = "standard"
-reportFunctionMemberAccess = "information"
-reportOptionalContextManager = "warning"
-reportOptionalMemberAccess = "warning"
 
 [tool.ruff.lint]
 ignore = ["DTZ005", "UP031"]

{cachetools-7.1.8 → cachetools-7.2.1}/src/cachetools/__init__.py

@@ -12,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "7.1.8"
+__version__ = "7.2.1"
 
 import collections
 import collections.abc
@@ -52,7 +52,7 @@ class Cache(collections.abc.MutableMapping):
     def __init__(self, maxsize, getsizeof=None):
         if maxsize < 0:
             raise ValueError("maxsize must be non-negative")
-        if getsizeof:
+        if getsizeof is not None:
             self.getsizeof = getsizeof
         if self.getsizeof is not Cache.getsizeof:
             self.__size = {}
@@ -357,12 +357,11 @@ class RRCache(Cache):
 
     def popitem(self):
         """Remove and return a random `(key, value)` pair."""
-        try:
-            key = self.__choice(self.__keys)
-        except IndexError:
+        keys = self.__keys
+        if not keys:
             raise KeyError("%s is empty" % type(self).__name__) from None
-        else:
-            return (key, self.pop(key))
+        key = self.__choice(keys)
+        return (key, self.pop(key))
 
     def clear(self):
         Cache.clear(self)

{cachetools-7.1.8 → cachetools-7.2.1}/src/cachetools/_cached.py

@@ -1,8 +1,11 @@
 """Function decorator helpers."""
 
+# pyright: reportFunctionMemberAccess=false
+
 __all__ = ()
 
 import functools
+import warnings
 
 # At least for now, the implementation prefers clarity and performance
 # over ease of maintenance, thus providing separate wrappers for
@@ -227,6 +230,13 @@ def _uncached(func):
 
 
 def _wrapper(func, cache, key, lock=None, cond=None, info=None):
+    if cache is None:
+        warnings.warn(
+            "@cachetools.cached(cache=None) is deprecated",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+
     if info is not None:
         if cache is None:
             wrapper = _uncached_info(func, info)

{cachetools-7.1.8 → cachetools-7.2.1}/src/cachetools/_cachedmethod.py

@@ -1,5 +1,7 @@
 """Method decorator helpers."""
 
+# pyright: reportOptionalContextManager=false, reportOptionalMemberAccess=false
+
 __all__ = ()
 
 import functools

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.1.8
+Version: 7.2.1
 Summary: Extensible memoizing collections and decorators
 Author-email: Thomas Kemmer <tkemmer@computer.org>
 Maintainer-email: Thomas Kemmer <tkemmer@computer.org>
@@ -21,6 +21,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.10
 Description-Content-Type: text/x-rst

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

@@ -1,4 +1,5 @@
 import unittest
+import warnings
 
 import cachetools
 import cachetools.keys
@@ -17,6 +18,9 @@ class DecoratorTestMixin(_TestCaseProtocol):
             self.count = 0
         return self.count
 
+    def error_func(self, *args, **kwargs):
+        raise ValueError("test error")
+
     def test_decorator(self):
         cache = self.cache(2)
         wrapper = cachetools.cached(cache)(self.func)
@@ -86,7 +90,7 @@ class DecoratorTestMixin(_TestCaseProtocol):
         self.assertEqual(wrapper(1), 1)
         self.assertEqual(lock.count, 5)
 
-    def test_decorator_condition(self):
+    def test_decorator_cond(self):
         cache = self.cache(2)
         lock = cond = CountedCondition()
         wrapper = cachetools.cached(cache, condition=cond)(self.func)
@@ -105,7 +109,7 @@ class DecoratorTestMixin(_TestCaseProtocol):
         self.assertEqual(cond.wait_count, 3)
         self.assertEqual(cond.notify_count, 2)
 
-    def test_decorator_lock_condition(self):
+    def test_decorator_lock_cond(self):
         cache = self.cache(2)
         lock = CountedLock()
         cond = CountedCondition()
@@ -125,6 +129,26 @@ class DecoratorTestMixin(_TestCaseProtocol):
         self.assertEqual(cond.wait_count, 3)
         self.assertEqual(cond.notify_count, 2)
 
+    def test_decorator_cond_error(self):
+        cache = self.cache(2)
+        lock = cond = CountedCondition()
+        wrapper = cachetools.cached(cache, condition=cond)(self.error_func)
+
+        with self.assertRaises(ValueError):
+            wrapper(0)
+        self.assertEqual(len(cache), 0)
+        self.assertEqual(lock.count, 2)
+        self.assertEqual(cond.wait_count, 1)
+        self.assertEqual(cond.notify_count, 1)
+
+        # verify pending set is cleaned up, otherwise this might deadlock
+        with self.assertRaises(ValueError):
+            wrapper(0)
+        self.assertEqual(len(cache), 0)
+        self.assertEqual(lock.count, 4)
+        self.assertEqual(cond.wait_count, 2)
+        self.assertEqual(cond.notify_count, 2)
+
     def test_decorator_wrapped(self):
         cache = self.cache(2)
         wrapper = cachetools.cached(cache)(self.func)
@@ -158,7 +182,7 @@ class DecoratorTestMixin(_TestCaseProtocol):
         self.assertIs(wrapper.cache_lock, lock)
         self.assertIs(wrapper.cache_condition, None)
 
-    def test_decorator_attributes_condition(self):
+    def test_decorator_attributes_cond(self):
         cache = self.cache(2)
         lock = cond = CountedCondition()
         wrapper = cachetools.cached(cache, condition=cond)(self.func)
@@ -187,7 +211,7 @@ class DecoratorTestMixin(_TestCaseProtocol):
         self.assertEqual(len(cache), 0)
         self.assertEqual(lock.count, 3)
 
-    def test_decorator_clear_condition(self):
+    def test_decorator_clear_cond(self):
         cache = self.cache(2)
         lock = cond = CountedCondition()
         wrapper = cachetools.cached(cache, condition=cond)(self.func)
@@ -241,7 +265,7 @@ class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin):
         self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0))
         self.assertEqual(lock.count, 11)
 
-    def test_decorator_condition_info(self):
+    def test_decorator_cond_info(self):
         cache = self.cache(2)
         lock = cond = CountedCondition()
         wrapper = cachetools.cached(cache, condition=cond, info=True)(self.func)
@@ -265,7 +289,7 @@ class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin):
         self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0))
         self.assertEqual(lock.count, 13)
 
-    def test_decorator_lock_condition_info(self):
+    def test_decorator_lock_cond_info(self):
         cache = self.cache(2)
         lock = CountedLock()
         cond = CountedCondition()
@@ -310,7 +334,7 @@ class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin):
         self.assertEqual(len(cache), 0)
         self.assertEqual(lock.count, 2)
 
-    def test_zero_size_cache_decorator_condition(self):
+    def test_zero_size_cache_decorator_cond(self):
         cache = self.cache(0)
         lock = cond = CountedCondition()
         wrapper = cachetools.cached(cache, condition=cond)(self.func)
@@ -342,6 +366,20 @@ class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin):
         self.assertEqual(wrapper.cache_info(), (0, 1, 0, 0))
         self.assertEqual(lock.count, 4)
 
+    def test_zero_size_cache_decorator_cond_info(self):
+        cache = self.cache(0)
+        lock = cond = CountedCondition()
+        wrapper = cachetools.cached(cache, condition=cond, info=True)(self.func)
+
+        self.assertEqual(len(cache), 0)
+        self.assertEqual(wrapper.cache_info(), (0, 0, 0, 0))
+        self.assertEqual(lock.count, 1)
+        self.assertEqual(wrapper(0), 0)
+        self.assertEqual(len(cache), 0)
+        self.assertEqual(lock.count, 4)
+        self.assertEqual(wrapper.cache_info(), (0, 1, 0, 0))
+        self.assertEqual(lock.count, 5)
+
 
 class DictWrapperTest(unittest.TestCase, DecoratorTestMixin):
     def cache(self, minsize):
@@ -367,26 +405,34 @@ class NoneWrapperTest(unittest.TestCase):
         return args + tuple(kwargs.items())
 
     def test_decorator(self):
-        wrapper = cachetools.cached(None)(self.func)
+        with warnings.catch_warnings(record=True) as w:
+            wrapper = cachetools.cached(None)(self.func)
+            self.assertIs(w[0].category, DeprecationWarning)
 
         self.assertEqual(wrapper(0), (0,))
         self.assertEqual(wrapper(1), (1,))
         self.assertEqual(wrapper(1, foo="bar"), (1, ("foo", "bar")))
 
     def test_decorator_attributes(self):
-        wrapper = cachetools.cached(None)(self.func)
+        with warnings.catch_warnings(record=True) as w:
+            wrapper = cachetools.cached(None)(self.func)
+            self.assertIs(w[0].category, DeprecationWarning)
 
         self.assertIs(wrapper.cache, None)
         self.assertIs(wrapper.cache_key, cachetools.keys.hashkey)
         self.assertIs(wrapper.cache_lock, None)
 
     def test_decorator_clear(self):
-        wrapper = cachetools.cached(None)(self.func)
+        with warnings.catch_warnings(record=True) as w:
+            wrapper = cachetools.cached(None)(self.func)
+            self.assertIs(w[0].category, DeprecationWarning)
 
         wrapper.cache_clear()  # no-op
 
     def test_decorator_info(self):
-        wrapper = cachetools.cached(None, info=True)(self.func)
+        with warnings.catch_warnings(record=True) as w:
+            wrapper = cachetools.cached(None, info=True)(self.func)
+            self.assertIs(w[0].category, DeprecationWarning)
 
         self.assertEqual(wrapper.cache_info(), (0, 0, 0, 0))
         self.assertEqual(wrapper(0), (0,))

{cachetools-7.1.8 → cachetools-7.2.1}/tests/test_lfu.py

@@ -31,6 +31,27 @@ class LFUCacheTest(unittest.TestCase, CacheTestMixin):
         self.assertEqual(cache[1], 1)
         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
+
+        self.assertEqual(len(cache), 3)
+        self.assertIn(1, 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[5] = 5
+        self.assertEqual(len(cache), 3)
+        self.assertIn(1, cache)
+        self.assertIn(5, cache)
+        self.assertTrue(2 in cache or 3 in cache or 4 in cache)
+
     def test_lfu_getsizeof(self):
         cache = LFUCache[int, int](maxsize=3, getsizeof=lambda x: x)
 

{cachetools-7.1.8 → cachetools-7.2.1}/tests/test_rr.py

@@ -86,3 +86,18 @@ class RRCacheTest(unittest.TestCase, CacheTestMixin):
     def test_rr_default_choice(self):
         cache = RRCache[int, int](maxsize=2)
         self.assertIs(cache.choice, random.choice)
+
+    def test_rr_popitem_empty_custom_choice(self):
+        # a custom `choice` function only has to handle non-empty
+        # sequences, so an empty cache has to be detected beforehand
+        for choice in (min, max, lambda seq: next(iter(seq))):
+            cache = RRCache[int, int](maxsize=2, choice=choice)
+
+            with self.assertRaises(KeyError):
+                cache.popitem()
+
+            cache[1] = 1
+            self.assertEqual((1, 1), cache.popitem())
+
+            with self.assertRaises(KeyError):
+                cache.popitem()