cachetools 6.2.5__tar.gz → 7.0.0__tar.gz

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

@@ -1,3 +1,41 @@
+v7.0.0 (2026-02-01)
+===================
+
+- Require Python 3.10 or later (breaking change).
+
+- Drop support for passing ``info`` as fourth positional parameter to
+  ``@cached`` (breaking change).
+
+- Drop support for ``cache(self)`` returning ``None`` with
+  ``@cachedmethod`` (breaking change).
+
+- Convert the ``@cachedmethod`` wrappers to descriptors, deprecating
+  its use with class methods and instances that do not provide a
+  mutable ``__dict__`` attribute (potentially breaking change).
+
+- Convert the previously undocumented ``@cachedmethod`` attributes
+  (``cache``, ``cache_lock``, etc.) to properties for instance
+  methods, providing official support and documentation (potentially
+  breaking change).
+
+- Add an optional ``info`` parameter to the ``@cachedmethod``
+  decorator for reporting per-instance cache statistics.  Note that
+  this requires the instance's ``__dict__`` attribute to be a mutable
+  mapping.
+
+
+v6.2.6 (2026-01-27)
+===================
+
+- Improve typedkey performance.
+
+- Minor documentation improvements.
+
+- Minor testing improvements.
+
+- Minor code readability improvements.
+
+
 v6.2.5 (2026-01-25)
 ===================
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 6.2.5
+Version: 7.0.0
 Summary: Extensible memoizing collections and decorators
 Author-email: Thomas Kemmer <tkemmer@computer.org>
 Maintainer-email: Thomas Kemmer <tkemmer@computer.org>
@@ -11,14 +11,13 @@ Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-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: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Dynamic: license-file

{cachetools-6.2.5 → cachetools-7.0.0}/docs/index.rst

@@ -26,6 +26,7 @@ method calls.
    from unittest import mock
    urllib = mock.MagicMock()
 
+   import threading
    import time
 
 
@@ -35,11 +36,11 @@ Cache implementations
 This module provides several classes implementing caches using
 different cache algorithms.  All these classes derive from class
 :class:`Cache`, which in turn derives from
-:class:`collections.MutableMapping`, and provide :attr:`maxsize` and
-:attr:`currsize` properties to retrieve the maximum and current size
-of the cache.  When a cache is full, :meth:`Cache.__setitem__()` calls
-:meth:`self.popitem()` repeatedly until there is enough room for the
-item to be added.
+:class:`collections.abc.MutableMapping`, and provide :attr:`maxsize`
+and :attr:`currsize` properties to retrieve the maximum and current
+size of the cache.  When a cache is full, :meth:`Cache.__setitem__()`
+calls :meth:`self.popitem()` repeatedly until there is enough room for
+the item to be added.
 
 .. note::
 
@@ -53,8 +54,9 @@ 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
-named constructor parameter `getsizeof`, which may specify a function
-of one argument used to retrieve the size of an item's value.
+named constructor parameter `getsizeof`, which may specify a callable
+``getsizeof(value) -> int`` used to retrieve the size of an item's
+value.
 
 The values of a :class:`Cache` are mutable by default, as are e.g. the
 values of a :class:`dict`.  It is the user's responsibility to take
@@ -214,7 +216,6 @@ all cache implementations call :meth:`popitem` to evict items from the
 cache, this can be achieved by overriding this method in a subclass:
 
 .. doctest::
-   :pyversion: >= 3
 
    >>> class MyCache(LRUCache):
    ...     def popitem(self):
@@ -236,7 +237,6 @@ pairs.  By overriding :meth:`expire`, a subclass will be able to track
 expired items:
 
 .. doctest::
-   :pyversion: >= 3
 
    >>> class ExpCache(TTLCache):
    ...     def expire(self, time=None):
@@ -259,7 +259,6 @@ method which is called by :meth:`Cache.__getitem__` if the requested
 key is not found:
 
 .. doctest::
-   :pyversion: >= 3
 
    >>> class PepStore(LRUCache):
    ...     def __missing__(self, key):
@@ -363,10 +362,8 @@ often called with the same arguments:
 
    .. testcode::
 
-      from threading import Lock
-
       # 640K should be enough for anyone...
-      @cached(cache=LRUCache(maxsize=640*1024, getsizeof=len), lock=Lock())
+      @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
@@ -401,7 +398,6 @@ often called with the same arguments:
       to be enabled explicitly.
 
    .. doctest::
-      :pyversion: >= 3
 
       >>> @cached(cache=LRUCache(maxsize=32), info=True)
       ... def get_pep(num):
@@ -495,7 +491,6 @@ often called with the same arguments:
    invocations, with separately cached results:
 
    .. doctest::
-      :pyversion: >= 3
 
       >>> @cached(LRUCache(maxsize=100))
       ... def foo(a=1):
@@ -515,7 +510,6 @@ often called with the same arguments:
    be introduced to avoid ambiguities, e.g.:
 
    .. doctest::
-      :pyversion: >= 3
 
       >>> def foo(a=1):
       ...     _foo(a)
@@ -531,17 +525,16 @@ often called with the same arguments:
       >>> foo(a=1)
 
 
-.. decorator:: cachedmethod(cache, key=cachetools.keys.methodkey, lock=None, condition=None)
+.. decorator:: cachedmethod(cache, key=cachetools.keys.methodkey, lock=None, condition=None, info=False)
 
-   Decorator to wrap a class or instance method with a memoizing
-   callable that saves results in a (possibly shared) cache.
+   Decorator to wrap an instance method with a memoizing callable that
+   saves results in a cache.
 
    The main difference between this and the :func:`cached` function
    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.
+   objects, but functions.  Those will be called with :const:`self` as
+   their sole argument to retrieve a valid cache, lock, or condition
+   object for the respective instance.
 
    .. note::
 
@@ -550,55 +543,63 @@ often called with the same arguments:
       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)`
-   to retrieve a suitable cache key.  Note that the default `key`
-   function, :func:`cachetools.keys.methodkey`, ignores its first
-   argument, i.e. :const:`self`.  This has mostly historical reasons,
-   but also ensures that :const:`self` does not have to be hashable.
+   Similarly to the :func:`cached` function decorator, the `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 wrapped instance method.
+   A :func:`cache_clear()` function will also be provided, as well as
+   an optional :func:`cache_info()` function reporting per-instance
+   cache statistics.
 
-   .. note::
-
-      Using :func:`cachedmethod` with a `condition` currently *does*
-      require :const:`self` be hashable, though.
-
-   You may provide a different `key` function,
-   e.g. :func:`cachetools.keys.hashkey`, if you need :const:`self` to
-   be part of the cache key.
+   Also, mostly for efficiency, this decorator requires that the
+   :attr:`__dict__` attribute on each instance be a mutable mapping.
+   This means it will not work with some types, such as metaclasses,
+   and those that specify :attr:`__slots__` without including
+   :attr:`__dict__` as one of the defined slots.
 
    One advantage of :func:`cachedmethod` over the :func:`cached`
    function decorator is that cache properties such as `maxsize` can
    be set at runtime:
 
-   .. testcode::
+   .. doctest::
 
-      from cachetools.keys import hashkey
-      from threading import Lock
+      >>> class CachedPEPs:
+      ...     def __init__(self, cachesize):
+      ...         self.cache = LRUCache(maxsize=cachesize)
+      ...         self.lock = threading.Lock()
+      ...
+      ...     @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
+      ...         with urllib.request.urlopen(url) as s:
+      ...             return s.read()
+
+      >>> peps = CachedPEPs(cachesize=32)
+      >>> for n in 8, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991:
+      ...     pep = peps.get(n)
 
-      class CachedPEPs:
+      >>> peps.get.cache_info()
+      CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)
 
-          def __init__(self, cachesize):
-              self.cache = LRUCache(maxsize=cachesize)
-              self.lock = Lock()
+      >>> peps.get.cache_clear()
 
-          @cachedmethod(lambda self: self.cache, lock=lambda self: self.lock)
-          def get(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()
-
-      peps = CachedPEPs(cachesize=10)
-      print("PEP #1: %s" % peps.get(1))
+      >>> peps.get.cache_info()
+      CacheInfo(hits=0, misses=0, maxsize=32, currsize=0)
 
-   .. testoutput::
-      :hide:
-      :options: +ELLIPSIS
+   The `key` function will be called as `key(self, *args, **kwargs)`
+   to retrieve a suitable cache key.  Note that the default `key`
+   function, :func:`cachetools.keys.methodkey`, ignores its first
+   argument, i.e. :const:`self`.  This has mostly historical reasons,
+   but also ensures that :const:`self` does not have to be hashable.
 
-      PEP #1: ...
+   You may provide a different `key` function,
+   e.g. :func:`cachetools.keys.hashkey`, if you need :const:`self` to
+   be part of the cache key.
 
    When using a shared cache for multiple methods, be aware that
    different cache keys must be created for each method even when
-   function arguments are the same, just as with the `@cached`
+   function arguments are the same, just as with the :func:`cached`
    decorator:
 
    .. testcode::
@@ -641,11 +642,33 @@ often called with the same arguments:
    to create distinct cache keys, to avoid issues with
    :func:`methodkey` skipping its initial `self` argument.
 
-   .. deprecated:: 6.0
+   .. versionchanged:: 7.0
+
+   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.
+
+   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.
+
+   .. 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.
 
-   Support for `cache(self)` returning :const:`None` to suppress any
-   caching has been deprecated.  `cache(self)` should always return a
-   valid cache object.
+   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.
 
 
 *****************************************************************

{cachetools-6.2.5 → cachetools-7.0.0}/pyproject.toml

@@ -15,14 +15,13 @@ maintainers = [
 readme = "README.rst"
 license = "MIT"
 license-files = ["LICENSE"]
-requires-python = ">= 3.9"
+requires-python = ">= 3.10"
 classifiers = [
     "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",

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

@@ -12,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "6.2.5"
+__version__ = "7.0.0"
 
 import collections
 import collections.abc
@@ -23,8 +23,13 @@ import time
 
 from . import keys
 
+# Typing stubs for this package are provided by typeshed:
+# https://github.com/python/typeshed/tree/main/stubs/cachetools
+
 
 class _DefaultSize:
+    """A minimal "fake" dict that returns a constant size 1 for any key."""
+
     __slots__ = ()
 
     def __getitem__(self, _key):
@@ -540,6 +545,8 @@ class TTLCache(_TimedCache):
 class TLRUCache(_TimedCache):
     """Time aware Least Recently Used (TLRU) cache implementation."""
 
+    __HEAP_CLEANUP_FACTOR = 2  # clean up the heap if size > N * len(items)
+
     @functools.total_ordering
     class _Item:
         __slots__ = ("key", "expires", "removed")
@@ -625,7 +632,7 @@ class TLRUCache(_TimedCache):
         items = self.__items
         order = self.__order
         # clean up the heap if too many items are marked as removed
-        if len(order) > len(items) * 2:
+        if len(order) > len(items) * self.__HEAP_CLEANUP_FACTOR:
             self.__order = order = [item for item in order if not item.removed]
             heapq.heapify(order)
         expired = []
@@ -671,17 +678,6 @@ def cached(cache, key=keys.hashkey, lock=None, condition=None, info=False):
     """
     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:
             if isinstance(cache, Cache):
@@ -706,7 +702,7 @@ def cached(cache, key=keys.hashkey, lock=None, condition=None, info=False):
     return decorator
 
 
-def cachedmethod(cache, key=keys.methodkey, lock=None, condition=None):
+def cachedmethod(cache, key=keys.methodkey, lock=None, condition=None, info=False):
     """Decorator to wrap a class or instance method with a memoizing
     callable that saves results in a cache.
 
@@ -714,6 +710,18 @@ def cachedmethod(cache, key=keys.methodkey, lock=None, condition=None):
     from ._cachedmethod import _wrapper
 
     def decorator(method):
-        return _wrapper(method, cache, key, lock, condition)
+        if info:
+
+            def make_info(cache, hits, misses):
+                if isinstance(cache, Cache):
+                    return _CacheInfo(hits, misses, cache.maxsize, cache.currsize)
+                elif isinstance(cache, collections.abc.Mapping):
+                    return _CacheInfo(hits, misses, None, len(cache))
+                else:
+                    raise TypeError("cache(self) must return a mutable mapping")
+
+            return _wrapper(method, cache, key, lock, condition, info=make_info)
+        else:
+            return _wrapper(method, cache, key, lock, condition)
 
     return decorator

{cachetools-6.2.5 → cachetools-7.0.0}/src/cachetools/_cached.py

@@ -1,7 +1,14 @@
 """Function decorator helpers."""
 
+__all__ = ()
+
 import functools
 
+# At least for now, the implementation prefers clarity and performance
+# over ease of maintenance, thus providing separate wrappers for
+# all valid combinations of decorator parameters lock, condition and
+# info.
+
 
 def _condition_info(func, cache, key, lock, cond, info):
     hits = misses = 0
@@ -178,7 +185,9 @@ def _locked(func, cache, key, lock):
         v = func(*args, **kwargs)
         with lock:
             try:
-                # possible race condition: see above
+                # In case of a race condition, i.e. if another thread
+                # stored a value for this key while we were calling
+                # func(), prefer the cached value.
                 return cache.setdefault(k, v)
             except ValueError:
                 return v  # value too large