General improvements.

Author: tkem

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 wrapper(*args, **kwargs):
         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

src/cachetools/_cachedmethod.py

@@ -1,30 +1,34 @@
 """Method decorator helpers."""
 
+__all__ = ()
+
 import functools
 import warnings
 import weakref
 
 
-def warn_classmethod(stacklevel):
+def _warn_classmethod(stacklevel):
     warnings.warn(
         "decorating class methods with @cachedmethod is deprecated",
         DeprecationWarning,
         stacklevel=stacklevel,
     )
 
 
-def warn_instance_dict(msg, stacklevel):
+def _warn_instance_dict(msg, stacklevel):
     warnings.warn(
         msg,
         DeprecationWarning,
         stacklevel=stacklevel,
     )
 
 
-class WrapperBase:
+class _WrapperBase:
+    """Wrapper base class providing default implementations for properties."""
+
     def __init__(self, obj, method, cache, key, lock=None, cond=None):
         if isinstance(obj, type):
-            warn_classmethod(stacklevel=5)
+            _warn_classmethod(stacklevel=5)
         functools.update_wrapper(self, method)
         self._obj = obj  # protected
         self.__cache = cache
@@ -55,10 +59,12 @@ def cache_condition(self):
         return None if self.__cond is None else self.__cond(self._obj)
 
 
-class DescriptorBase:
-    def __init__(self, warndict=False):
+class _DescriptorBase:
+    """Descriptor base class implementing the basic descriptor protocol."""
+
+    def __init__(self, deprecated=False):
         self.__attrname = None
-        self.__warndict = warndict
+        self.__deprecated = deprecated
 
     def __set_name__(self, owner, name):
         if self.__attrname is None:
@@ -72,16 +78,19 @@ def __set_name__(self, owner, name):
     def __get__(self, obj, objtype=None):
         wrapper = self.Wrapper(obj)
         if self.__attrname is not None:
+            # replace descriptor instance with wrapper in instance dict
             try:
+                # In case of a race condition where another thread already replaced
+                # the descriptor, prefer the initial wrapper.
                 wrapper = obj.__dict__.setdefault(self.__attrname, wrapper)
             except AttributeError:
                 # not all objects have __dict__ (e.g. class defines slots)
                 msg = (
                     f"No '__dict__' attribute on {type(obj).__name__!r} "
                     f"instance to cache {self.__attrname!r} property."
                 )
-                if self.__warndict:
-                    warn_instance_dict(msg, 3)
+                if self.__deprecated:
+                    _warn_instance_dict(msg, 3)
                 else:
                     raise TypeError(msg) from None
             except TypeError:  # pragma: no cover
@@ -90,39 +99,46 @@ def __get__(self, obj, objtype=None):
                     f"instance does not support item assignment for "
                     f"caching {self.__attrname!r} property."
                 )
-                if self.__warndict:
-                    warn_instance_dict(msg, 3)
+                if self.__deprecated:
+                    _warn_instance_dict(msg, 3)
                 else:
                     raise TypeError(msg) from None
-        elif not self.__warndict:  # pragma: no cover
-            msg = (
-                "Cannot use @cachedmethod instance without "
-                "calling __set_name__ on it"
-            )
+        elif self.__deprecated:
+            pass  # deprecated @classmethod, warning already raised elsewhere
+        else:  # pragma: no cover
+            msg = "Cannot use @cachedmethod instance without calling __set_name__ on it"
             raise TypeError(msg) from None
         return wrapper
 
 
-class DeprecatedDescriptorBase(DescriptorBase):
+class _DeprecatedDescriptorBase(_DescriptorBase):
+    """Descriptor base class supporting deprecated @classmethod use."""
+
     def __init__(self, wrapper, cache_clear):
-        super().__init__(True)
+        super().__init__(deprecated=True)
         self.__wrapper = wrapper
         self.__cache_clear = cache_clear
 
     # called for @classmethod with Python >= 3.13
     def __call__(self, *args, **kwargs):
-        warn_classmethod(stacklevel=3)
+        _warn_classmethod(stacklevel=3)
         return self.__wrapper(*args, **kwargs)
 
     # backward-compatible @classmethod handling with Python >= 3.13
     def cache_clear(self, objtype):
-        warn_classmethod(stacklevel=3)
+        _warn_classmethod(stacklevel=3)
         return self.__cache_clear(objtype)
 
 
+# At least for now, the implementation prefers clarity and performance
+# over ease of maintenance, thus providing separate descriptors for
+# all valid combinations of decorator parameters lock, condition and
+# info.
+
+
 def _condition_info(method, cache, key, lock, cond, info):
-    class Descriptor(DescriptorBase):
-        class Wrapper(WrapperBase):
+    class Descriptor(_DescriptorBase):
+        class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key, lock, cond)
                 self.__hits = self.__misses = 0
@@ -169,8 +185,8 @@ def cache_info(self):
 
 
 def _locked_info(method, cache, key, lock, info):
-    class Descriptor(DescriptorBase):
-        class Wrapper(WrapperBase):
+    class Descriptor(_DescriptorBase):
+        class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key, lock)
                 self.__hits = self.__misses = 0
@@ -209,8 +225,8 @@ def cache_info(self):
 
 
 def _unlocked_info(method, cache, key, info):
-    class Descriptor(DescriptorBase):
-        class Wrapper(WrapperBase):
+    class Descriptor(_DescriptorBase):
+        class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key)
                 self.__hits = self.__misses = 0
@@ -276,8 +292,8 @@ def classmethod_wrapper(self, *args, **kwargs):
         p = pending.setdefault(self, set())
         return wrapper(self, p, *args, **kwargs)
 
-    class Descriptor(DeprecatedDescriptorBase):
-        class Wrapper(WrapperBase):
+    class Descriptor(_DeprecatedDescriptorBase):
+        class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key, lock, cond)
                 self.__pending = set()
@@ -304,7 +320,9 @@ def wrapper(self, *args, **kwargs):
         v = method(self, *args, **kwargs)
         with lock(self):
             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
+                # method(), prefer the cached value.
                 return c.setdefault(k, v)
             except ValueError:
                 return v  # value too large
@@ -314,8 +332,8 @@ def cache_clear(self):
         with lock(self):
             c.clear()
 
-    class Descriptor(DeprecatedDescriptorBase):
-        class Wrapper(WrapperBase):
+    class Descriptor(_DeprecatedDescriptorBase):
+        class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key, lock)
 
@@ -348,8 +366,8 @@ def cache_clear(self):
         c = cache(self)
         c.clear()
 
-    class Descriptor(DeprecatedDescriptorBase):
-        class Wrapper(WrapperBase):
+    class Descriptor(_DeprecatedDescriptorBase):
+        class Wrapper(_WrapperBase):
             def __init__(self, obj):
                 super().__init__(obj, method, cache, key)
 

src/cachetools/keys.py

@@ -11,7 +11,7 @@ class _HashedTuple(tuple):
 
     """
 
-    __hashvalue = None
+    __hashvalue = None  # default value, set in instance on first use
 
     def __hash__(self, hash=tuple.__hash__):
         hashvalue = self.__hashvalue