cachetools 5.5.2__tar.gz → 6.0.0__tar.gz

{cachetools-5.5.2 → cachetools-6.0.0}/CHANGELOG.rst

@@ -1,3 +1,32 @@
+v6.0.0 (2025-05-23)
+===================
+
+- Require Python 3.9 or later (breaking change).
+
+- Remove ``MRUCache`` and the ``@func.mru_cache`` decorator (breaking
+  change).
+
+- Add an optional ``condition`` parameter to the ``@cached`` and
+  ``@cachedmethod`` decorators, which, when used with a
+  ``threading.Condition`` instance, should improve `cache stampede
+  <https://en.wikipedia.org/wiki/Cache_stampede>`_ issues in massively
+  parallel environments.  Note that this will inflict some performance
+  penalty, and therefore has to be enabled explicitly.
+
+- Convert the ``cachetools.func`` decorators to use a
+  ``threading.Condition`` instance to deal with `cache stampede
+  <https://en.wikipedia.org/wiki/Cache_stampede>`_ issues.  Note that
+  this *may* result in a noticable performance degradation, depending
+  on your actual use case.
+
+- Deprecate support for ``cache(self)`` returning ``None`` to suppress
+  caching with the ``@cachedmethod`` decorator.
+
+- Improve documentation.
+
+- Update CI environment.
+
+
 v5.5.2 (2025-02-20)
 ===================
 

{cachetools-5.5.2/src/cachetools.egg-info → cachetools-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: cachetools
-Version: 5.5.2
+Version: 6.0.0
 Summary: Extensible memoizing collections and decorators
 Home-page: https://github.com/tkem/cachetools/
 Author: Thomas Kemmer
@@ -13,16 +13,15 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.7
+Requires-Python: >=3.9
 License-File: LICENSE
+Dynamic: license-file
 
 cachetools
 ========================================================================
@@ -116,11 +115,12 @@ Project Resources
 Related Projects
 ------------------------------------------------------------------------
 
-- asyncache_: Helpers to use cachetools with async functions
-- cacheing_: Pure Python Cacheing Library
-- CacheToolsUtils_: Cachetools Utilities
-- kids.cache_: Kids caching library
-- shelved-cache_: Persistent cache for Python cachetools
+- asyncache_: Helpers to use cachetools_ with asyncio.
+- cacheing_: Pure Python Cacheing Library.
+- CacheToolsUtils_: Stackable cache classes for sharing, encryption,
+  statistics *and more* on top of cachetools_, redis_ and memcached_.
+- shelved-cache_: Persistent cache implementation for Python
+  cachetools_.
 
 
 License
@@ -145,7 +145,9 @@ Licensed under the `MIT License`_.
 .. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE
 
 .. _asyncache: https://pypi.org/project/asyncache/
-.. _cacheing: https://github.com/breid48/cacheing
+.. _cacheing: https://pypi.org/project/cacheing/
 .. _CacheToolsUtils: https://pypi.org/project/CacheToolsUtils/
-.. _kids.cache: https://pypi.org/project/kids.cache/
 .. _shelved-cache: https://pypi.org/project/shelved-cache/
+.. _cachetools: https://pypi.org/project/cachetools/
+.. _redis: https://redis.io/
+.. _memcached: https://memcached.org/

{cachetools-5.5.2 → cachetools-6.0.0}/README.rst

@@ -90,11 +90,12 @@ Project Resources
 Related Projects
 ------------------------------------------------------------------------
 
-- asyncache_: Helpers to use cachetools with async functions
-- cacheing_: Pure Python Cacheing Library
-- CacheToolsUtils_: Cachetools Utilities
-- kids.cache_: Kids caching library
-- shelved-cache_: Persistent cache for Python cachetools
+- asyncache_: Helpers to use cachetools_ with asyncio.
+- cacheing_: Pure Python Cacheing Library.
+- CacheToolsUtils_: Stackable cache classes for sharing, encryption,
+  statistics *and more* on top of cachetools_, redis_ and memcached_.
+- shelved-cache_: Persistent cache implementation for Python
+  cachetools_.
 
 
 License
@@ -119,7 +120,9 @@ Licensed under the `MIT License`_.
 .. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE
 
 .. _asyncache: https://pypi.org/project/asyncache/
-.. _cacheing: https://github.com/breid48/cacheing
+.. _cacheing: https://pypi.org/project/cacheing/
 .. _CacheToolsUtils: https://pypi.org/project/CacheToolsUtils/
-.. _kids.cache: https://pypi.org/project/kids.cache/
 .. _shelved-cache: https://pypi.org/project/shelved-cache/
+.. _cachetools: https://pypi.org/project/cachetools/
+.. _redis: https://redis.io/
+.. _memcached: https://memcached.org/

{cachetools-5.5.2 → cachetools-6.0.0}/docs/conf.py

@@ -26,8 +26,10 @@ extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
     "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
 ]
 exclude_patterns = ["_build"]
 master_doc = "index"
 html_theme = "classic"
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

{cachetools-5.5.2 → cachetools-6.0.0}/docs/index.rst

@@ -52,7 +52,7 @@ Therefore, :class:`Cache` provides a :meth:`getsizeof` method, which
 returns the size of a given `value`.  The default implementation of
 :meth:`getsizeof` returns :const:`1` irrespective of its argument,
 making the cache's size equal to the number of its items, or
-``len(cache)``.  For convenience, all cache classes accept an optional
+`len(cache)`.  For convenience, all cache classes accept an optional
 named constructor parameter `getsizeof`, which may specify a function
 of one argument used to retrieve the size of an item's value.
 
@@ -98,18 +98,6 @@ inserted into the cache.
    This class discards the least recently used items first to make
    space when necessary.
 
-.. autoclass:: MRUCache(maxsize, getsizeof=None)
-   :members: popitem
-
-   This class discards the most recently used items first to make
-   space when necessary.
-
-   .. deprecated:: 5.4
-
-   `MRUCache` has been deprecated due to lack of use, to reduce
-   maintenance.  Please choose another cache implementation that suits
-   your needs.
-
 .. autoclass:: RRCache(maxsize, choice=random.choice, getsizeof=None)
    :members: choice, popitem
 
@@ -174,7 +162,7 @@ inserted into the cache.
    value of `timer()`.
 
    .. testcode::
-   
+
       def my_ttu(_key, value, now):
           # assume value.ttu contains the item's time-to-use in seconds
           # note that the _key argument is ignored in this example
@@ -311,7 +299,7 @@ often called with the same arguments:
    >>> fib(42)
    267914296
 
-.. decorator:: cached(cache, key=cachetools.keys.hashkey, lock=None, info=False)
+.. decorator:: cached(cache, key=cachetools.keys.hashkey, lock=None, condition=None, info=False)
 
    Decorator to wrap a function with a memoizing callable that saves
    results in a cache.
@@ -333,19 +321,45 @@ often called with the same arguments:
    implementing the `context manager`_ protocol.  Any access to the
    cache will then be nested in a ``with lock:`` statement.  This can
    be used for synchronizing thread access to the cache by providing a
-   :class:`threading.Lock` instance, for example.
+   :class:`threading.Lock` or :class:`threading.RLock` instance, for
+   example.
 
    .. note::
 
       The `lock` context manager is used only to guard access to the
       cache object.  The underlying wrapped function will be called
-      outside the `with` statement, and must be thread-safe by itself.
+      outside the `with` statement to allow concurrent execution, and
+      therefore must be `thread-safe`_ by itself.
+
+   If `condition` is not :const:`None`, it must specify a `condition
+   variable`_, i.e. an object providing :func:`wait()`,
+   :func:`wait_for()`, :func:`notify()` and :func:`notify_all()`
+   methods as defined by :class:`threading.Condition`.  Using a
+   `condition` variable will prevent concurrent execution of the
+   wrapped function with *identical* parameters, or cache keys.
+   Instead, a calling thread will check if an identical function call
+   is already executing, and will then :func:`wait()` for the pending
+   call to finish.  The executing thread will :func:`notify()` any
+   waiting threads as soon as the function completes, which will then
+   return the cached function result.
+
+   .. note::
+
+      Although providing a `lock` alone is generally sufficient to
+      make :func:`cached` `thread-safe`_, it may still be subject to
+      `cache stampede`_ issues under high load, depending on your
+      actual use case.  Providing a `condition` variable will mitigate
+      these situations, but will inflict some performance penalty.
+   
+   If no separate `lock` parameter is provided, `condition` must also
+   implement the `context manager`_ protocol, and will also be used to
+   guard access to the cache.
 
-   The decorator's `cache`, `key` and `lock` parameters are also
-   available as :attr:`cache`, :attr:`cache_key` and
-   :attr:`cache_lock` attributes of the memoizing wrapper function.
-   These can be used for clearing the cache or invalidating individual
-   cache items, for example.
+   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
+   memoizing wrapper function.  These can be used for clearing the
+   cache or invalidating individual cache items, for example.
 
    .. testcode::
 
@@ -383,8 +397,8 @@ often called with the same arguments:
 
    .. note::
 
-      Note that this will inflict a - probably minor - performance
-      penalty, so it has to be explicitly enabled.
+      Note that this will inflict some performance penalty, so it has
+      to be enabled explicitly.
 
    .. doctest::
       :pyversion: >= 3
@@ -474,22 +488,23 @@ often called with the same arguments:
           print(e, "-", _get_pep_wrapped.cache_info())
 
 
-.. decorator:: cachedmethod(cache, key=cachetools.keys.methodkey, lock=None)
+.. decorator:: cachedmethod(cache, key=cachetools.keys.methodkey, lock=None, condition=None)
 
    Decorator to wrap a class or instance method with a memoizing
    callable that saves results in a (possibly shared) cache.
 
    The main difference between this and the :func:`cached` function
-   decorator is that `cache` and `lock` are not passed objects, but
-   functions.  Both will be called with :const:`self` (or :const:`cls`
-   for class methods) as their sole argument to retrieve the cache or
-   lock object for the method's respective instance or class.
+   decorator is that `cache`, `lock` and `condition` are not passed
+   objects, but functions.  Those will be called with :const:`self`
+   (or :const:`cls` for class methods) as their sole argument to
+   retrieve the cache, lock, or condition object for the method's
+   respective instance or class.
 
    .. note::
 
       As with :func:`cached`, the context manager obtained by calling
-      ``lock(self)`` will only guard access to the cache itself.  It
-      is the user's responsibility to handle concurrent calls to the
+      `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.
 
    The `key` function will be called as `key(self, *args, **kwargs)`
@@ -507,6 +522,9 @@ often called with the same arguments:
 
    .. testcode::
 
+      from cachetools.keys import hashkey
+      from functools import partial
+
       class CachedPEPs:
 
           def __init__(self, cachesize):
@@ -535,19 +553,22 @@ often called with the same arguments:
 
    .. testcode::
 
+      from cachetools.keys import methodkey
+      from functools import partial
+
       class CachedReferences:
 
           def __init__(self, cachesize):
               self.cache = LRUCache(maxsize=cachesize)
 
-          @cachedmethod(lambda self: self.cache, key=partial(hashkey, 'pep'))
+          @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
               with urllib.request.urlopen(url) as s:
                   return s.read()
 
-          @cachedmethod(lambda self: self.cache, key=partial(hashkey, 'rfc'))
+          @cachedmethod(lambda self: self.cache, key=partial(methodkey, method='rfc'))
           def get_rfc(self, num):
               """Retrieve text of an IETF Request for Comments"""
               url = 'https://tools.ietf.org/rfc/rfc%d.txt' % num
@@ -555,15 +576,26 @@ often called with the same arguments:
                   return s.read()
 
       docs = CachedReferences(cachesize=100)
-      print("PEP #1: %s" % docs.get_pep(1))
-      print("RFC #1: %s" % docs.get_rfc(1))
+      print("PEP #20: %s" % docs.get_pep(20))
+      print("RFC #20: %s" % docs.get_rfc(20))
+      assert len(docs.cache) == 2
 
    .. testoutput::
       :hide:
       :options: +ELLIPSIS
 
-      PEP #1: ...
-      RFC #1: ...
+      PEP #20: ...
+      RFC #20: ...
+
+   Note how keyword arguments are used with :func:`functools.partial`
+   to create distinct cache keys, to avoid issues with
+   :func:`methodkey` skipping its initial `self` argument.
+
+   .. deprecated:: 6.0
+
+   Support for `cache(self)` returning :const:`None` to suppress any
+   caching has been deprecated.  `cache(self)` should always return a
+   valid cache object.
 
 
 *****************************************************************
@@ -590,8 +622,7 @@ functions with the :func:`cached` and :func:`cachedmethod` decorators:
 
    This function is similar to :func:`hashkey`, but arguments of
    different types will yield distinct cache keys.  For example,
-   ``typedkey(3)`` and ``typedkey(3.0)`` will return different
-   results.
+   `typedkey(3)` and `typedkey(3.0)` will return different results.
 
 .. autofunction:: typedmethodkey
 
@@ -643,8 +674,8 @@ without bound.
 
 If the optional argument `typed` is set to :const:`True`, function
 arguments of different types will be cached separately.  For example,
-``f(3)`` and ``f(3.0)`` will be treated as distinct calls with
-distinct results.
+`f(3)` and `f(3.0)` will be treated as distinct calls with distinct
+results.
 
 If a `user_function` is specified instead, it must be a callable.
 This allows the decorator to be applied directly to a user function,
@@ -688,18 +719,6 @@ all the decorators in this module are thread-safe by default.
    saves up to `maxsize` results based on a Least Recently Used (LRU)
    algorithm.
 
-.. decorator:: mru_cache(user_function)
-               mru_cache(maxsize=128, typed=False)
-
-   Decorator that wraps a function with a memoizing callable that
-   saves up to `maxsize` results based on a Most Recently Used (MRU)
-   algorithm.
-
-   .. deprecated:: 5.4
-
-   The `mru_cache` decorator has been deprecated due to lack of use.
-   Please choose a decorator based on some other algorithm.
-
 .. decorator:: rr_cache(user_function)
                rr_cache(maxsize=128, choice=random.choice, typed=False)
 
@@ -715,8 +734,11 @@ all the decorators in this module are thread-safe by default.
    algorithm with a per-item time-to-live (TTL) value.
 
 
-.. _@lru_cache: http://docs.python.org/3/library/functools.html#functools.lru_cache
-.. _cache algorithm: http://en.wikipedia.org/wiki/Cache_algorithms
-.. _context manager: http://docs.python.org/dev/glossary.html#term-context-manager
-.. _mapping: http://docs.python.org/dev/glossary.html#term-mapping
-.. _mutable: http://docs.python.org/dev/glossary.html#term-mutable
+.. _@lru_cache: https://docs.python.org/3/library/functools.html#functools.lru_cache
+.. _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
+.. _thread-safe: https://en.wikipedia.org/wiki/Thread_safety

{cachetools-5.5.2 → cachetools-6.0.0}/setup.cfg

@@ -16,8 +16,6 @@ classifiers =
 	Operating System :: OS Independent
 	Programming Language :: Python
 	Programming Language :: Python :: 3
-	Programming Language :: Python :: 3.7
-	Programming Language :: Python :: 3.8
 	Programming Language :: Python :: 3.9
 	Programming Language :: Python :: 3.10
 	Programming Language :: Python :: 3.11
@@ -29,7 +27,7 @@ classifiers =
 package_dir = 
 	= src
 packages = find:
-python_requires = >= 3.7
+python_requires = >= 3.9
 
 [options.packages.find]
 where = src

{cachetools-5.5.2 → cachetools-6.0.0}/src/cachetools/__init__.py

@@ -5,7 +5,6 @@ __all__ = (
     "FIFOCache",
     "LFUCache",
     "LRUCache",
-    "MRUCache",
     "RRCache",
     "TLRUCache",
     "TTLCache",
@@ -13,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "5.5.2"
+__version__ = "6.0.0"
 
 import collections
 import collections.abc
@@ -23,7 +22,6 @@ import random
 import time
 
 from . import keys
-from ._decorators import _cached_wrapper
 
 
 class _DefaultSize:
@@ -210,12 +208,12 @@ class LRUCache(Cache):
     def __getitem__(self, key, cache_getitem=Cache.__getitem__):
         value = cache_getitem(self, key)
         if key in self:  # __missing__ may not store item
-            self.__update(key)
+            self.__touch(key)
         return value
 
     def __setitem__(self, key, value, cache_setitem=Cache.__setitem__):
         cache_setitem(self, key, value)
-        self.__update(key)
+        self.__touch(key)
 
     def __delitem__(self, key, cache_delitem=Cache.__delitem__):
         cache_delitem(self, key)
@@ -230,54 +228,14 @@ class LRUCache(Cache):
         else:
             return (key, self.pop(key))
 
-    def __update(self, key):
+    def __touch(self, key):
+        """Mark as recently used"""
         try:
             self.__order.move_to_end(key)
         except KeyError:
             self.__order[key] = None
 
 
-class MRUCache(Cache):
-    """Most Recently Used (MRU) cache implementation."""
-
-    def __init__(self, maxsize, getsizeof=None):
-        from warnings import warn
-
-        warn("MRUCache is deprecated", DeprecationWarning, stacklevel=2)
-
-        Cache.__init__(self, maxsize, getsizeof)
-        self.__order = collections.OrderedDict()
-
-    def __getitem__(self, key, cache_getitem=Cache.__getitem__):
-        value = cache_getitem(self, key)
-        if key in self:  # __missing__ may not store item
-            self.__update(key)
-        return value
-
-    def __setitem__(self, key, value, cache_setitem=Cache.__setitem__):
-        cache_setitem(self, key, value)
-        self.__update(key)
-
-    def __delitem__(self, key, cache_delitem=Cache.__delitem__):
-        cache_delitem(self, key)
-        del self.__order[key]
-
-    def popitem(self):
-        """Remove and return the `(key, value)` pair most recently used."""
-        try:
-            key = next(iter(self.__order))
-        except StopIteration:
-            raise KeyError("%s is empty" % type(self).__name__) from None
-        else:
-            return (key, self.pop(key))
-
-    def __update(self, key):
-        try:
-            self.__order.move_to_end(key, last=False)
-        except KeyError:
-            self.__order[key] = None
-
-
 class RRCache(Cache):
     """Random Replacement (RR) cache implementation."""
 
@@ -636,11 +594,23 @@ _CacheInfo = collections.namedtuple(
 )
 
 
-def cached(cache, key=keys.hashkey, lock=None, info=False):
+def cached(cache, key=keys.hashkey, lock=None, condition=None, info=False):
     """Decorator to wrap a function with a memoizing callable that saves
     results in a cache.
 
     """
+    from ._cached import _wrapper
+
+    if isinstance(condition, bool):
+        from warnings import warn
+
+        warn(
+            "passing `info` as positional parameter is deprecated",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        info = condition
+        condition = None
 
     def decorator(func):
         if info:
@@ -659,80 +629,21 @@ def cached(cache, key=keys.hashkey, lock=None, info=False):
                 def make_info(hits, misses):
                     return _CacheInfo(hits, misses, 0, 0)
 
-            wrapper = _cached_wrapper(func, cache, key, lock, make_info)
+            return _wrapper(func, cache, key, lock, condition, info=make_info)
         else:
-            wrapper = _cached_wrapper(func, cache, key, lock, None)
-
-        wrapper.cache = cache
-        wrapper.cache_key = key
-        wrapper.cache_lock = lock
-
-        return functools.update_wrapper(wrapper, func)
+            return _wrapper(func, cache, key, lock, condition)
 
     return decorator
 
 
-def cachedmethod(cache, key=keys.methodkey, lock=None):
+def cachedmethod(cache, key=keys.methodkey, lock=None, condition=None):
     """Decorator to wrap a class or instance method with a memoizing
     callable that saves results in a cache.
 
     """
+    from ._cachedmethod import _wrapper
 
     def decorator(method):
-        if lock is None:
-
-            def wrapper(self, *args, **kwargs):
-                c = cache(self)
-                if c is None:
-                    return method(self, *args, **kwargs)
-                k = key(self, *args, **kwargs)
-                try:
-                    return c[k]
-                except KeyError:
-                    pass  # key not found
-                v = method(self, *args, **kwargs)
-                try:
-                    c[k] = v
-                except ValueError:
-                    pass  # value too large
-                return v
-
-            def clear(self):
-                c = cache(self)
-                if c is not None:
-                    c.clear()
-
-        else:
-
-            def wrapper(self, *args, **kwargs):
-                c = cache(self)
-                if c is None:
-                    return method(self, *args, **kwargs)
-                k = key(self, *args, **kwargs)
-                try:
-                    with lock(self):
-                        return c[k]
-                except KeyError:
-                    pass  # key not found
-                v = method(self, *args, **kwargs)
-                # in case of a race, prefer the item already in the cache
-                try:
-                    with lock(self):
-                        return c.setdefault(k, v)
-                except ValueError:
-                    return v  # value too large
-
-            def clear(self):
-                c = cache(self)
-                if c is not None:
-                    with lock(self):
-                        c.clear()
-
-        wrapper.cache = cache
-        wrapper.cache_key = key
-        wrapper.cache_lock = lock
-        wrapper.cache_clear = clear
-
-        return functools.update_wrapper(wrapper, method)
+        return _wrapper(method, cache, key, lock, condition)
 
     return decorator