cachetools 6.2.0__tar.gz → 6.2.2__tar.gz

{cachetools-6.2.0 → cachetools-6.2.2}/CHANGELOG.rst

@@ -1,3 +1,21 @@
+v6.2.2 (2025-11-13)
+===================
+
+- Minor improvements from GitHub Copilot code review.
+
+- Improve documentation.
+
+
+v6.2.1 (2025-10-12)
+===================
+
+- Add support for Python 3.14.
+
+- Improve documentation.
+
+- Update CI environment.
+
+
 v6.2.0 (2025-08-25)
 ===================
 

{cachetools-6.2.0/src/cachetools.egg-info → cachetools-6.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 6.2.0
+Version: 6.2.2
 Summary: Extensible memoizing collections and decorators
 Home-page: https://github.com/tkem/cachetools/
 Author: Thomas Kemmer
@@ -18,6 +18,7 @@ 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
 License-File: LICENSE
@@ -116,6 +117,7 @@ Related Projects
 ------------------------------------------------------------------------
 
 - asyncache_: Helpers to use cachetools_ with asyncio.
+- cachetools-async_: 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_.
@@ -145,6 +147,7 @@ Licensed under the `MIT License`_.
 .. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE
 
 .. _asyncache: https://pypi.org/project/asyncache/
+.. _cachetools-async: https://pypi.org/project/cachetools-async/
 .. _cacheing: https://pypi.org/project/cacheing/
 .. _CacheToolsUtils: https://pypi.org/project/CacheToolsUtils/
 .. _shelved-cache: https://pypi.org/project/shelved-cache/

{cachetools-6.2.0 → cachetools-6.2.2}/README.rst

@@ -91,6 +91,7 @@ Related Projects
 ------------------------------------------------------------------------
 
 - asyncache_: Helpers to use cachetools_ with asyncio.
+- cachetools-async_: 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_.
@@ -120,6 +121,7 @@ Licensed under the `MIT License`_.
 .. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE
 
 .. _asyncache: https://pypi.org/project/asyncache/
+.. _cachetools-async: https://pypi.org/project/cachetools-async/
 .. _cacheing: https://pypi.org/project/cacheing/
 .. _CacheToolsUtils: https://pypi.org/project/CacheToolsUtils/
 .. _shelved-cache: https://pypi.org/project/shelved-cache/

{cachetools-6.2.0 → cachetools-6.2.2}/docs/index.rst

@@ -232,7 +232,7 @@ 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
+pairs.  By overriding :meth:`expire`, a subclass will be able to track
 expired items:
 
 .. doctest::
@@ -350,7 +350,7 @@ often called with the same arguments:
       `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.
@@ -451,7 +451,7 @@ often called with the same arguments:
       [..., (('fib', 42), 267914296), ..., (('luc', 42), 599074578)]
 
 
-   Function invocations are _not_ cached if any exception are raised.
+   Function invocations are *not* cached if any exceptions are raised.
    To cache some (or all) calls raising exceptions, additional
    function wrappers may be introduced which wrap exceptions as
    regular function results for caching purposes:
@@ -488,6 +488,49 @@ often called with the same arguments:
           print(e, "-", _get_pep_wrapped.cache_info())
 
 
+   Curiously, default function arguments are not quite handled as one
+   might expect, and also the use of positional vs. keyword arguments
+   may lead to surprising results.  In the example below, `foo()`,
+   `foo(1)` and `foo(a=1)` are treated as different function
+   invocations, with separately cached results:
+
+   .. doctest::
+      :pyversion: >= 3
+
+      >>> @cached(LRUCache(maxsize=100))
+      ... def foo(a=1):
+      ...     print(f"foo({a}) called")
+      ...
+      >>> foo()
+      foo(1) called
+      >>> foo()
+      >>> foo(1)
+      foo(1) called
+      >>> foo(1)
+      >>> foo(a=1)
+      foo(1) called
+      >>> foo(a=1)
+
+   If consistent behavior is required, a private helper function may
+   be introduced to avoid ambiguities, e.g.:
+
+   .. doctest::
+      :pyversion: >= 3
+
+      >>> def foo(a=1):
+      ...     _foo(a)
+      ...
+      >>> @cached(LRUCache(maxsize=100))
+      ... def _foo(a):
+      ...     print(f"_foo({a}) called")
+      ...
+      >>> foo()
+      _foo(1) called
+      >>> foo()
+      >>> foo(1)
+      >>> foo(a=1)
+
+
 .. decorator:: cachedmethod(cache, key=cachetools.keys.methodkey, lock=None, condition=None)
 
    Decorator to wrap a class or instance method with a memoizing
@@ -731,8 +774,9 @@ all the decorators in this module are thread-safe by default.
 
    Decorator to wrap a function with a memoizing callable that saves
    up to `maxsize` results based on a Least Recently Used (LRU)
-   algorithm with a per-item time-to-live (TTL) value.
-
+   algorithm with a per-item time-to-live (TTL) value.  By default,
+   the time-to-live is set to 600 seconds and :func:`time.monotonic`
+   is used to retrieve the current time.
 
 .. _@lru_cache: https://docs.python.org/3/library/functools.html#functools.lru_cache
 .. _cache algorithm: https://en.wikipedia.org/wiki/Cache_algorithms

{cachetools-6.2.0 → cachetools-6.2.2}/setup.cfg

@@ -21,6 +21,7 @@ classifiers =
 	Programming Language :: Python :: 3.11
 	Programming Language :: Python :: 3.12
 	Programming Language :: Python :: 3.13
+	Programming Language :: Python :: 3.14
 	Topic :: Software Development :: Libraries :: Python Modules
 
 [options]

{cachetools-6.2.0 → cachetools-6.2.2}/src/cachetools/__init__.py

@@ -12,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "6.2.0"
+__version__ = "6.2.2"
 
 import collections
 import collections.abc
@@ -27,13 +27,13 @@ from . import keys
 class _DefaultSize:
     __slots__ = ()
 
-    def __getitem__(self, _):
+    def __getitem__(self, _key):
         return 1
 
-    def __setitem__(self, _, value):
-        assert value == 1
+    def __setitem__(self, _key, _value):
+        pass
 
-    def pop(self, _):
+    def pop(self, _key):
         return 1
 
 
@@ -55,7 +55,7 @@ class Cache(collections.abc.MutableMapping):
 
     def __repr__(self):
         return "%s(%s, maxsize=%r, currsize=%r)" % (
-            self.__class__.__name__,
+            type(self).__name__,
             repr(self.__data),
             self.__maxsize,
             self.__currsize,
@@ -100,6 +100,12 @@ class Cache(collections.abc.MutableMapping):
     def __len__(self):
         return len(self.__data)
 
+    # Note that we cannot simply inherit get(), pop() and setdefault()
+    # from MutableMapping, since these rely on __getitem__ throwing a
+    # KeyError on cache miss.  This is not the case if __missing__ is
+    # implemented for a Cache subclass, so we have to roll our own,
+    # somewhat less elegant versions.
+
     def get(self, key, default=None):
         if key in self:
             return self[key]
@@ -642,7 +648,7 @@ class TLRUCache(_TimedCache):
             try:
                 key = next(iter(self.__items))
             except StopIteration:
-                raise KeyError("%s is empty" % self.__class__.__name__) from None
+                raise KeyError("%s is empty" % type(self).__name__) from None
             else:
                 return (key, self.pop(key))
 

{cachetools-6.2.0 → cachetools-6.2.2}/src/cachetools/_cached.py

@@ -63,7 +63,9 @@ def _locked_info(func, cache, key, lock, info):
         v = func(*args, **kwargs)
         with lock:
             try:
-                # in case of a race, prefer the item already in the cache
+                # 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
@@ -173,7 +175,7 @@ def _locked(func, cache, key, lock):
         v = func(*args, **kwargs)
         with lock:
             try:
-                # in case of a race, prefer the item already in the cache
+                # possible race condition: see above
                 return cache.setdefault(k, v)
             except ValueError:
                 return v  # value too large

{cachetools-6.2.0 → cachetools-6.2.2}/src/cachetools/func.py

@@ -92,6 +92,7 @@ def ttl_cache(maxsize=128, ttl=600, timer=time.monotonic, typed=False):
     """Decorator to wrap a function with a memoizing callable that saves
     up to `maxsize` results based on a Least Recently Used (LRU)
     algorithm with a per-item time-to-live (TTL) value.
+
     """
     if maxsize is None:
         return _cache(_UnboundTTLCache(ttl, timer), None, typed)

{cachetools-6.2.0 → cachetools-6.2.2}/src/cachetools/keys.py

@@ -29,8 +29,8 @@ class _HashedTuple(tuple):
         return {}
 
 
-# used for separating keyword arguments; we do not use an object
-# instance here so identity is preserved when pickling/unpickling
+# A sentinel for separating args from kwargs.  Using the class itself
+# ensures uniqueness and preserves identity when pickling/unpickling.
 _kwmark = (_HashedTuple,)
 
 

{cachetools-6.2.0 → cachetools-6.2.2/src/cachetools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 6.2.0
+Version: 6.2.2
 Summary: Extensible memoizing collections and decorators
 Home-page: https://github.com/tkem/cachetools/
 Author: Thomas Kemmer
@@ -18,6 +18,7 @@ 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
 License-File: LICENSE
@@ -116,6 +117,7 @@ Related Projects
 ------------------------------------------------------------------------
 
 - asyncache_: Helpers to use cachetools_ with asyncio.
+- cachetools-async_: 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_.
@@ -145,6 +147,7 @@ Licensed under the `MIT License`_.
 .. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE
 
 .. _asyncache: https://pypi.org/project/asyncache/
+.. _cachetools-async: https://pypi.org/project/cachetools-async/
 .. _cacheing: https://pypi.org/project/cacheing/
 .. _CacheToolsUtils: https://pypi.org/project/CacheToolsUtils/
 .. _shelved-cache: https://pypi.org/project/shelved-cache/