Fix #218: Fix and properly document @cachedmethod.cache_key handling.

tkem · tkem · commit 18e5930ced2c · 2026-03-08T22:29:04.000+01:00
diff --git a/docs/index.rst b/docs/index.rst
@@ -370,13 +370,10 @@ often called with the same arguments:
           with urllib.request.urlopen(url) as s:
               return s.read()
 
-      # make sure access to cache is synchronized
+      # remove (pop) an individual cached PEP from the cache
+      key = get_pep.cache_key(42)
       with get_pep.cache_lock:
-          get_pep.cache.clear()
-
-      # always use the key function for accessing cache items
-      with get_pep.cache_lock:
-          get_pep.cache.pop(get_pep.cache_key(42), None)
+          get_pep.cache.pop(key, None)
 
    For the common use case of clearing or invalidating the cache, the
    decorator also provides a :func:`cache_clear()` function which
@@ -582,6 +579,15 @@ often called with the same arguments:
       >>> peps.get.cache_info()
       CacheInfo(hits=3, misses=8, maxsize=32, currsize=8)
 
+      >>> # remove an individual cached PEP from the cache
+      >>> key = peps.get.cache_key(320)
+      >>> with peps.get.cache_lock:
+      ...    del peps.get.cache[key]
+
+      >>> peps.get.cache_info()
+      CacheInfo(hits=3, misses=8, maxsize=32, currsize=7)
+
+      >>> # remove all cached PEPs and clear cache info
       >>> peps.get.cache_clear()
 
       >>> peps.get.cache_info()
@@ -590,8 +596,9 @@ often called with the same arguments:
    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.
+   implicit argument, i.e. :const:`self`.  This has mostly historical
+   reasons, but also ensures that :const:`self` does not have to be
+   hashable.
 
    You may provide a different `key` function,
    e.g. :func:`cachetools.keys.hashkey`, if you need :const:`self` to
diff --git a/src/cachetools/_cachedmethod.py b/src/cachetools/_cachedmethod.py
@@ -48,7 +48,7 @@ def cache(self):
 
     @property
     def cache_key(self):
-        return self.__key
+        return functools.partial(self.__key, self._obj)
 
     @property
     def cache_lock(self):
@@ -153,7 +153,7 @@ def __call__(self, *args, **kwargs):
                 cache = self.cache
                 lock = self.cache_lock
                 cond = self.cache_condition
-                key = self.cache_key(self._obj, *args, **kwargs)
+                key = self.cache_key(*args, **kwargs)
 
                 with lock:
                     cond.wait_for(lambda: key not in self.__pending)
@@ -199,7 +199,7 @@ def __init__(self, obj):
             def __call__(self, *args, **kwargs):
                 cache = self.cache
                 lock = self.cache_lock
-                key = self.cache_key(self._obj, *args, **kwargs)
+                key = self.cache_key(*args, **kwargs)
                 with lock:
                     try:
                         result = cache[key]
@@ -238,7 +238,7 @@ def __init__(self, obj):
 
             def __call__(self, *args, **kwargs):
                 cache = self.cache
-                key = self.cache_key(self._obj, *args, **kwargs)
+                key = self.cache_key(*args, **kwargs)
                 try:
                     result = cache[key]
                     self.__hits += 1
diff --git a/tests/test_cachedmethod.py b/tests/test_cachedmethod.py
@@ -370,24 +370,26 @@ def test_decorator_attributes(self):
         cached = Cached(cache)
 
         self.assertIs(cached.get.cache, cache)
-        self.assertIs(cached.get.cache_key, keys.methodkey)
         self.assertIs(cached.get.cache_lock, None)
         self.assertIs(cached.get.cache_condition, None)
+        self.assertEqual(cached.get.cache_key(42), keys.methodkey(cached, 42))
 
         self.assertIs(cached.get_lock.cache, cache)
-        self.assertIs(cached.get_lock.cache_key, keys.methodkey)
         self.assertIs(cached.get_lock.cache_lock, cached.lock)
         self.assertIs(cached.get_lock.cache_condition, None)
+        self.assertEqual(cached.get_lock.cache_key(42), keys.methodkey(cached, 42))
 
         self.assertIs(cached.get_cond.cache, cache)
-        self.assertIs(cached.get_cond.cache_key, keys.methodkey)
         self.assertIs(cached.get_cond.cache_lock, cached.cond)
         self.assertIs(cached.get_cond.cache_condition, cached.cond)
+        self.assertEqual(cached.get_cond.cache_key(42), keys.methodkey(cached, 42))
 
         self.assertIs(cached.get_lock_cond_info.cache, cache)
-        self.assertIs(cached.get_lock_cond_info.cache_key, keys.methodkey)
         self.assertIs(cached.get_lock_cond_info.cache_lock, cached.lock)
         self.assertIs(cached.get_lock_cond_info.cache_condition, cached.cond)
+        self.assertEqual(
+            cached.get_lock_cond_info.cache_key(42), keys.methodkey(cached, 42)
+        )
 
     def test_decorator_clear(self):
         cache = self.cache(2)
@@ -603,15 +605,25 @@ def test_shared_cache(self):
         self.assertEqual(cached1.get_info.cache_info(), (0, 0, 2, 0))
         self.assertEqual(cached2.get_info.cache_info(), (0, 0, 2, 0))
 
+        # hits/misses are counted by instance
         self.assertEqual(cached1.get_info(0), 0)
-
         self.assertEqual(cached1.get_info.cache_info(), (0, 1, 2, 1))
         self.assertEqual(cached2.get_info.cache_info(), (0, 0, 2, 1))
 
+        # default methodkey discards "self", so results will be shared
+        # across instances
         self.assertEqual(cached2.get_info(0), 0)
-
         self.assertEqual(cached1.get_info.cache_info(), (0, 1, 2, 1))
         self.assertEqual(cached2.get_info.cache_info(), (1, 0, 2, 1))
+        self.assertEqual(cached1.get_info(0), 0)
+        self.assertEqual(cached1.get_info.cache_info(), (1, 1, 2, 1))
+        self.assertEqual(cached2.get_info.cache_info(), (1, 0, 2, 1))
+        self.assertEqual(cached1.get_info(1), 1)
+        self.assertEqual(cached1.get_info.cache_info(), (1, 2, 2, 2))
+        self.assertEqual(cached2.get_info.cache_info(), (1, 0, 2, 2))
+        self.assertEqual(cached2.get_info(1), 1)
+        self.assertEqual(cached1.get_info.cache_info(), (1, 2, 2, 2))
+        self.assertEqual(cached2.get_info.cache_info(), (2, 0, 2, 2))
 
     def test_value_too_large(self):
         cache = self.cache(1, getsizeof=lambda x: x)
