cachetools 5.5.1__tar.gz → 5.5.2__tar.gz

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

@@ -1,3 +1,13 @@
+v5.5.2 (2025-02-20)
+===================
+
+- Reduce number of ``@cached`` lock/unlock operations.
+
+- Improve documentation.
+
+- Update CI environment.
+
+
 v5.5.1 (2025-01-21)
 ===================
 

{cachetools-5.5.1 → cachetools-5.5.2}/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014-2024 Thomas Kemmer
+Copyright (c) 2014-2025 Thomas Kemmer
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cachetools
-Version: 5.5.1
+Version: 5.5.2
 Summary: Extensible memoizing collections and decorators
 Home-page: https://github.com/tkem/cachetools/
 Author: Thomas Kemmer
@@ -126,7 +126,7 @@ Related Projects
 License
 ------------------------------------------------------------------------
 
-Copyright (c) 2014-2024 Thomas Kemmer.
+Copyright (c) 2014-2025 Thomas Kemmer.
 
 Licensed under the `MIT License`_.
 

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

@@ -100,7 +100,7 @@ Related Projects
 License
 ------------------------------------------------------------------------
 
-Copyright (c) 2014-2024 Thomas Kemmer.
+Copyright (c) 2014-2025 Thomas Kemmer.
 
 Licensed under the `MIT License`_.
 

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

@@ -19,7 +19,7 @@ def get_version():
 
 
 project = "cachetools"
-copyright = "2014-2024 Thomas Kemmer"
+copyright = "2014-2025 Thomas Kemmer"
 release, version = get_version()
 
 extensions = [

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

@@ -41,6 +41,12 @@ 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::
+
+   Please be aware that `maxsize` must be a positive number.  If you
+   really want your cache to grow without bounds, use
+   :const:`math.inf` or something similar.
+
 In general, a cache's size is the total size of its item's values.
 Therefore, :class:`Cache` provides a :meth:`getsizeof` method, which
 returns the size of a given `value`.  The default implementation of
@@ -50,12 +56,12 @@ making the cache's size equal to the number of its items, or
 named constructor parameter `getsizeof`, which may specify a function
 of one argument used to retrieve the size of an item's value.
 
-Note that 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 care that cached values are not accidentally
-modified.  This is especially important when using a custom
-`getsizeof` function, since the size of an item's value will only be
-computed when the item is inserted into the cache.
+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
+care that cached values are not accidentally modified.  This is
+especially important when using a custom `getsizeof` function, since
+the size of an item's value will only be computed when the item is
+inserted into the cache.
 
 .. note::
 

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

@@ -13,7 +13,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "5.5.1"
+__version__ = "5.5.2"
 
 import collections
 import collections.abc
@@ -23,6 +23,7 @@ import random
 import time
 
 from . import keys
+from ._decorators import _cached_wrapper
 
 
 class _DefaultSize:
@@ -643,150 +644,28 @@ def cached(cache, key=keys.hashkey, lock=None, info=False):
 
     def decorator(func):
         if info:
-            hits = misses = 0
-
             if isinstance(cache, Cache):
 
-                def getinfo():
-                    nonlocal hits, misses
+                def make_info(hits, misses):
                     return _CacheInfo(hits, misses, cache.maxsize, cache.currsize)
 
             elif isinstance(cache, collections.abc.Mapping):
 
-                def getinfo():
-                    nonlocal hits, misses
+                def make_info(hits, misses):
                     return _CacheInfo(hits, misses, None, len(cache))
 
             else:
 
-                def getinfo():
-                    nonlocal hits, misses
+                def make_info(hits, misses):
                     return _CacheInfo(hits, misses, 0, 0)
 
-            if cache is None:
-
-                def wrapper(*args, **kwargs):
-                    nonlocal misses
-                    misses += 1
-                    return func(*args, **kwargs)
-
-                def cache_clear():
-                    nonlocal hits, misses
-                    hits = misses = 0
-
-                cache_info = getinfo
-
-            elif lock is None:
-
-                def wrapper(*args, **kwargs):
-                    nonlocal hits, misses
-                    k = key(*args, **kwargs)
-                    try:
-                        result = cache[k]
-                        hits += 1
-                        return result
-                    except KeyError:
-                        misses += 1
-                    v = func(*args, **kwargs)
-                    try:
-                        cache[k] = v
-                    except ValueError:
-                        pass  # value too large
-                    return v
-
-                def cache_clear():
-                    nonlocal hits, misses
-                    cache.clear()
-                    hits = misses = 0
-
-                cache_info = getinfo
-
-            else:
-
-                def wrapper(*args, **kwargs):
-                    nonlocal hits, misses
-                    k = key(*args, **kwargs)
-                    try:
-                        with lock:
-                            result = cache[k]
-                            hits += 1
-                            return result
-                    except KeyError:
-                        with lock:
-                            misses += 1
-                    v = func(*args, **kwargs)
-                    # in case of a race, prefer the item already in the cache
-                    try:
-                        with lock:
-                            return cache.setdefault(k, v)
-                    except ValueError:
-                        return v  # value too large
-
-                def cache_clear():
-                    nonlocal hits, misses
-                    with lock:
-                        cache.clear()
-                        hits = misses = 0
-
-                def cache_info():
-                    with lock:
-                        return getinfo()
-
+            wrapper = _cached_wrapper(func, cache, key, lock, make_info)
         else:
-            if cache is None:
-
-                def wrapper(*args, **kwargs):
-                    return func(*args, **kwargs)
-
-                def cache_clear():
-                    pass
-
-            elif lock is None:
-
-                def wrapper(*args, **kwargs):
-                    k = key(*args, **kwargs)
-                    try:
-                        return cache[k]
-                    except KeyError:
-                        pass  # key not found
-                    v = func(*args, **kwargs)
-                    try:
-                        cache[k] = v
-                    except ValueError:
-                        pass  # value too large
-                    return v
-
-                def cache_clear():
-                    cache.clear()
-
-            else:
-
-                def wrapper(*args, **kwargs):
-                    k = key(*args, **kwargs)
-                    try:
-                        with lock:
-                            return cache[k]
-                    except KeyError:
-                        pass  # key not found
-                    v = func(*args, **kwargs)
-                    # in case of a race, prefer the item already in the cache
-                    try:
-                        with lock:
-                            return cache.setdefault(k, v)
-                    except ValueError:
-                        return v  # value too large
-
-                def cache_clear():
-                    with lock:
-                        cache.clear()
-
-            cache_info = None
+            wrapper = _cached_wrapper(func, cache, key, lock, None)
 
         wrapper.cache = cache
         wrapper.cache_key = key
         wrapper.cache_lock = lock
-        wrapper.cache_clear = cache_clear
-        wrapper.cache_info = cache_info
 
         return functools.update_wrapper(wrapper, func)
 

cachetools-5.5.2/src/cachetools/_decorators.py

@@ -0,0 +1,152 @@
+"""Extensible memoizing decorator helpers."""
+
+
+def _cached_locked_info(func, cache, key, lock, info):
+    hits = misses = 0
+
+    def wrapper(*args, **kwargs):
+        nonlocal hits, misses
+        k = key(*args, **kwargs)
+        with lock:
+            try:
+                result = cache[k]
+                hits += 1
+                return result
+            except KeyError:
+                misses += 1
+        v = func(*args, **kwargs)
+        with lock:
+            try:
+                # in case of a race, prefer the item already in the cache
+                return cache.setdefault(k, v)
+            except ValueError:
+                return v  # value too large
+
+    def cache_clear():
+        nonlocal hits, misses
+        with lock:
+            cache.clear()
+            hits = misses = 0
+
+    def cache_info():
+        with lock:
+            return info(hits, misses)
+
+    wrapper.cache_clear = cache_clear
+    wrapper.cache_info = cache_info
+    return wrapper
+
+
+def _cached_unlocked_info(func, cache, key, info):
+    hits = misses = 0
+
+    def wrapper(*args, **kwargs):
+        nonlocal hits, misses
+        k = key(*args, **kwargs)
+        try:
+            result = cache[k]
+            hits += 1
+            return result
+        except KeyError:
+            misses += 1
+        v = func(*args, **kwargs)
+        try:
+            cache[k] = v
+        except ValueError:
+            pass  # value too large
+        return v
+
+    def cache_clear():
+        nonlocal hits, misses
+        cache.clear()
+        hits = misses = 0
+
+    wrapper.cache_clear = cache_clear
+    wrapper.cache_info = lambda: info(hits, misses)
+    return wrapper
+
+
+def _uncached_info(func, info):
+    misses = 0
+
+    def wrapper(*args, **kwargs):
+        nonlocal misses
+        misses += 1
+        return func(*args, **kwargs)
+
+    def cache_clear():
+        nonlocal misses
+        misses = 0
+
+    wrapper.cache_clear = cache_clear
+    wrapper.cache_info = lambda: info(0, misses)
+    return wrapper
+
+
+def _cached_locked(func, cache, key, lock):
+    def wrapper(*args, **kwargs):
+        k = key(*args, **kwargs)
+        with lock:
+            try:
+                return cache[k]
+            except KeyError:
+                pass  # key not found
+        v = func(*args, **kwargs)
+        with lock:
+            try:
+                # in case of a race, prefer the item already in the cache
+                return cache.setdefault(k, v)
+            except ValueError:
+                return v  # value too large
+
+    def cache_clear():
+        with lock:
+            cache.clear()
+
+    wrapper.cache_clear = cache_clear
+    return wrapper
+
+
+def _cached_unlocked(func, cache, key):
+    def wrapper(*args, **kwargs):
+        k = key(*args, **kwargs)
+        try:
+            return cache[k]
+        except KeyError:
+            pass  # key not found
+        v = func(*args, **kwargs)
+        try:
+            cache[k] = v
+        except ValueError:
+            pass  # value too large
+        return v
+
+    wrapper.cache_clear = lambda: cache.clear()
+    return wrapper
+
+
+def _uncached(func):
+    def wrapper(*args, **kwargs):
+        return func(*args, **kwargs)
+
+    wrapper.cache_clear = lambda: None
+    return wrapper
+
+
+def _cached_wrapper(func, cache, key, lock, info):
+    if info is not None:
+        if cache is None:
+            wrapper = _uncached_info(func, info)
+        elif lock is None:
+            wrapper = _cached_unlocked_info(func, cache, key, info)
+        else:
+            wrapper = _cached_locked_info(func, cache, key, lock, info)
+    else:
+        if cache is None:
+            wrapper = _uncached(func)
+        elif lock is None:
+            wrapper = _cached_unlocked(func, cache, key)
+        else:
+            wrapper = _cached_locked(func, cache, key, lock)
+        wrapper.cache_info = None
+    return wrapper

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: cachetools
-Version: 5.5.1
+Version: 5.5.2
 Summary: Extensible memoizing collections and decorators
 Home-page: https://github.com/tkem/cachetools/
 Author: Thomas Kemmer
@@ -126,7 +126,7 @@ Related Projects
 License
 ------------------------------------------------------------------------
 
-Copyright (c) 2014-2024 Thomas Kemmer.
+Copyright (c) 2014-2025 Thomas Kemmer.
 
 Licensed under the `MIT License`_.
 

{cachetools-5.5.1 → cachetools-5.5.2}/src/cachetools.egg-info/SOURCES.txt

@@ -9,6 +9,7 @@ tox.ini
 docs/conf.py
 docs/index.rst
 src/cachetools/__init__.py
+src/cachetools/_decorators.py
 src/cachetools/func.py
 src/cachetools/keys.py
 src/cachetools.egg-info/PKG-INFO

{cachetools-5.5.1 → cachetools-5.5.2}/tests/test_cached.py

@@ -164,6 +164,30 @@ class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin):
         self.assertEqual(len(cache), 0)
         self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0))
 
+    def test_decorator_lock_info(self):
+        cache = self.cache(2)
+        lock = CountedLock()
+        wrapper = cachetools.cached(cache, lock=lock, info=True)(self.func)
+        self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0))
+        self.assertEqual(lock.count, 1)
+        self.assertEqual(wrapper(0), 0)
+        self.assertEqual(lock.count, 3)
+        self.assertEqual(wrapper.cache_info(), (0, 1, 2, 1))
+        self.assertEqual(lock.count, 4)
+        self.assertEqual(wrapper(1), 1)
+        self.assertEqual(lock.count, 6)
+        self.assertEqual(wrapper.cache_info(), (0, 2, 2, 2))
+        self.assertEqual(lock.count, 7)
+        self.assertEqual(wrapper(0), 0)
+        self.assertEqual(lock.count, 8)
+        self.assertEqual(wrapper.cache_info(), (1, 2, 2, 2))
+        self.assertEqual(lock.count, 9)
+        wrapper.cache_clear()
+        self.assertEqual(lock.count, 10)
+        self.assertEqual(len(cache), 0)
+        self.assertEqual(wrapper.cache_info(), (0, 0, 2, 0))
+        self.assertEqual(lock.count, 11)
+
     def test_zero_size_cache_decorator(self):
         cache = self.cache(0)
         wrapper = cachetools.cached(cache)(self.func)

{cachetools-5.5.1 → cachetools-5.5.2}/tox.ini

@@ -6,7 +6,7 @@ deps =
     pytest
     pytest-cov
 commands =
-    py.test --basetemp={envtmpdir} --cov=cachetools {posargs}
+    py.test --basetemp={envtmpdir} --cov=cachetools --cov-report term-missing {posargs}
 
 [testenv:check-manifest]
 deps =