cachetools 5.3.2__tar.gz → 5.4.0__tar.gz

{cachetools-5.3.2 → cachetools-5.4.0}/CHANGELOG.rst

@@ -1,3 +1,23 @@
+v5.4.0 (2024-07-15)
+===================
+
+- Add the ``keys.typedmethodkey`` decorator.
+
+- Deprecate ``MRUCache`` class.
+
+- Deprecate ``@func.mru_cache`` decorator.
+
+- Update CI environment.
+
+
+v5.3.3 (2024-02-26)
+===================
+
+- Documentation improvements.
+
+- Update CI environment.
+
+
 v5.3.2 (2023-10-24)
 ===================
 

{cachetools-5.3.2 → cachetools-5.4.0}/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014-2022 Thomas Kemmer
+Copyright (c) 2014-2024 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.3.2/src/cachetools.egg-info → cachetools-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cachetools
-Version: 5.3.2
+Version: 5.4.0
 Summary: Extensible memoizing collections and decorators
 Home-page: https://github.com/tkem/cachetools/
 Author: Thomas Kemmer
@@ -116,15 +116,16 @@ Related Projects
 ------------------------------------------------------------------------
 
 - asyncache_: Helpers to use cachetools with async functions
+- cacheing_: Pure Python Cacheing Library
 - CacheToolsUtils_: Cachetools Utilities
-- `kids.cache`_: Kids caching library
+- kids.cache_: Kids caching library
 - shelved-cache_: Persistent cache for Python cachetools
 
 
 License
 ------------------------------------------------------------------------
 
-Copyright (c) 2014-2023 Thomas Kemmer.
+Copyright (c) 2014-2024 Thomas Kemmer.
 
 Licensed under the `MIT License`_.
 
@@ -143,6 +144,7 @@ Licensed under the `MIT License`_.
 .. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE
 
 .. _asyncache: https://pypi.org/project/asyncache/
+.. _cacheing: https://github.com/breid48/cacheing
 .. _CacheToolsUtils: https://pypi.org/project/CacheToolsUtils/
 .. _kids.cache: https://pypi.org/project/kids.cache/
 .. _shelved-cache: https://pypi.org/project/shelved-cache/

{cachetools-5.3.2 → cachetools-5.4.0}/README.rst

@@ -91,15 +91,16 @@ Related Projects
 ------------------------------------------------------------------------
 
 - asyncache_: Helpers to use cachetools with async functions
+- cacheing_: Pure Python Cacheing Library
 - CacheToolsUtils_: Cachetools Utilities
-- `kids.cache`_: Kids caching library
+- kids.cache_: Kids caching library
 - shelved-cache_: Persistent cache for Python cachetools
 
 
 License
 ------------------------------------------------------------------------
 
-Copyright (c) 2014-2023 Thomas Kemmer.
+Copyright (c) 2014-2024 Thomas Kemmer.
 
 Licensed under the `MIT License`_.
 
@@ -118,6 +119,7 @@ Licensed under the `MIT License`_.
 .. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE
 
 .. _asyncache: https://pypi.org/project/asyncache/
+.. _cacheing: https://github.com/breid48/cacheing
 .. _CacheToolsUtils: https://pypi.org/project/CacheToolsUtils/
 .. _kids.cache: https://pypi.org/project/kids.cache/
 .. _shelved-cache: https://pypi.org/project/shelved-cache/

{cachetools-5.3.2 → cachetools-5.4.0}/docs/conf.py

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

{cachetools-5.3.2 → cachetools-5.4.0}/docs/index.rst

@@ -21,7 +21,6 @@ method calls.
 
 .. testsetup:: *
 
-   import operator
    from cachetools import cached, cachedmethod, LRUCache, TLRUCache, TTLCache
 
    from unittest import mock
@@ -97,6 +96,12 @@ computed when the item is inserted into the cache.
    This class discards the most recently used items first to make
    space when necessary.
 
+   .. deprecated:: 5.4
+
+   `MRUCache` has been deprecated due to lack of use, to reduce
+   maintenance.  Please choose another cache implementation that suits
+   your needs.
+
 .. autoclass:: RRCache(maxsize, choice=random.choice, getsizeof=None)
    :members: choice, popitem
 
@@ -417,12 +422,12 @@ often called with the same arguments:
 
    .. testcode::
 
-      class CachedPEPs(object):
+      class CachedPEPs:
 
           def __init__(self, cachesize):
               self.cache = LRUCache(maxsize=cachesize)
 
-          @cachedmethod(operator.attrgetter('cache'))
+          @cachedmethod(lambda self: self.cache)
           def get(self, num):
               """Retrieve text of a Python Enhancement Proposal"""
               url = 'http://www.python.org/dev/peps/pep-%04d/' % num
@@ -445,7 +450,7 @@ often called with the same arguments:
 
    .. testcode::
 
-      class CachedReferences(object):
+      class CachedReferences:
 
           def __init__(self, cachesize):
               self.cache = LRUCache(maxsize=cachesize)
@@ -492,7 +497,7 @@ functions with the :func:`cached` and :func:`cachedmethod` decorators:
 
 .. autofunction:: methodkey
 
-   This function is equivalent to :func:`hashkey`, but ignores its
+   This function is similar to :func:`hashkey`, but ignores its
    first positional argument, i.e. `self` when used with the
    :func:`cachedmethod` decorator.
 
@@ -503,6 +508,12 @@ functions with the :func:`cached` and :func:`cachedmethod` decorators:
    ``typedkey(3)`` and ``typedkey(3.0)`` will return different
    results.
 
+.. autofunction:: typedmethodkey
+
+   This function is similar to :func:`typedkey`, but ignores its
+   first positional argument, i.e. `self` when used with the
+   :func:`cachedmethod` decorator.
+
 These functions can also be helpful when implementing custom key
 functions for handling some non-hashable arguments.  For example,
 calling the following function with a dictionary as its `env` argument
@@ -599,6 +610,11 @@ all the decorators in this module are thread-safe by default.
    saves up to `maxsize` results based on a Most Recently Used (MRU)
    algorithm.
 
+   .. deprecated:: 5.4
+
+   The `mru_cache` decorator has been deprecated due to lack of use.
+   Please choose a decorator based on some other algorithm.
+
 .. decorator:: rr_cache(user_function)
                rr_cache(maxsize=128, choice=random.choice, typed=False)
 

{cachetools-5.3.2 → cachetools-5.4.0}/src/cachetools/__init__.py

@@ -13,7 +13,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "5.3.2"
+__version__ = "5.4.0"
 
 import collections
 import collections.abc
@@ -241,6 +241,10 @@ class MRUCache(Cache):
     """Most Recently Used (MRU) cache implementation."""
 
     def __init__(self, maxsize, getsizeof=None):
+        from warnings import warn
+
+        warn("MRUCache is deprecated", DeprecationWarning, stacklevel=2)
+
         Cache.__init__(self, maxsize, getsizeof)
         self.__order = collections.OrderedDict()
 

{cachetools-5.3.2 → cachetools-5.4.0}/src/cachetools/func.py

@@ -82,6 +82,10 @@ def mru_cache(maxsize=128, typed=False):
     up to `maxsize` results based on a Most Recently Used (MRU)
     algorithm.
     """
+    from warnings import warn
+
+    warn("@mru_cache is deprecated", DeprecationWarning, stacklevel=2)
+
     if maxsize is None:
         return _cache({}, None, typed)
     elif callable(maxsize):

{cachetools-5.3.2 → cachetools-5.4.0}/src/cachetools/keys.py

@@ -1,6 +1,6 @@
 """Key functions for memoizing decorators."""
 
-__all__ = ("hashkey", "methodkey", "typedkey")
+__all__ = ("hashkey", "methodkey", "typedkey", "typedmethodkey")
 
 
 class _HashedTuple(tuple):
@@ -55,3 +55,8 @@ def typedkey(*args, **kwargs):
     key += tuple(type(v) for v in args)
     key += tuple(type(v) for _, v in sorted(kwargs.items()))
     return key
+
+
+def typedmethodkey(self, *args, **kwargs):
+    """Return a typed cache key for use with cached methods."""
+    return typedkey(*args, **kwargs)

{cachetools-5.3.2 → cachetools-5.4.0/src/cachetools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cachetools
-Version: 5.3.2
+Version: 5.4.0
 Summary: Extensible memoizing collections and decorators
 Home-page: https://github.com/tkem/cachetools/
 Author: Thomas Kemmer
@@ -116,15 +116,16 @@ Related Projects
 ------------------------------------------------------------------------
 
 - asyncache_: Helpers to use cachetools with async functions
+- cacheing_: Pure Python Cacheing Library
 - CacheToolsUtils_: Cachetools Utilities
-- `kids.cache`_: Kids caching library
+- kids.cache_: Kids caching library
 - shelved-cache_: Persistent cache for Python cachetools
 
 
 License
 ------------------------------------------------------------------------
 
-Copyright (c) 2014-2023 Thomas Kemmer.
+Copyright (c) 2014-2024 Thomas Kemmer.
 
 Licensed under the `MIT License`_.
 
@@ -143,6 +144,7 @@ Licensed under the `MIT License`_.
 .. _MIT License: https://raw.github.com/tkem/cachetools/master/LICENSE
 
 .. _asyncache: https://pypi.org/project/asyncache/
+.. _cacheing: https://github.com/breid48/cacheing
 .. _CacheToolsUtils: https://pypi.org/project/CacheToolsUtils/
 .. _kids.cache: https://pypi.org/project/kids.cache/
 .. _shelved-cache: https://pypi.org/project/shelved-cache/

{cachetools-5.3.2 → cachetools-5.4.0}/tests/test_cachedmethod.py

@@ -1,4 +1,3 @@
-import operator
 import unittest
 
 from cachetools import LRUCache, cachedmethod, keys
@@ -9,14 +8,14 @@ class Cached:
         self.cache = cache
         self.count = count
 
-    @cachedmethod(operator.attrgetter("cache"))
+    @cachedmethod(lambda self: self.cache)
     def get(self, value):
         count = self.count
         self.count += 1
         return count
 
-    @cachedmethod(operator.attrgetter("cache"), key=keys.typedkey)
-    def get_typed(self, value):
+    @cachedmethod(lambda self: self.cache, key=keys.typedmethodkey)
+    def get_typedmethod(self, value):
         count = self.count
         self.count += 1
         return count
@@ -27,7 +26,7 @@ class Locked:
         self.cache = cache
         self.count = 0
 
-    @cachedmethod(operator.attrgetter("cache"), lock=lambda self: self)
+    @cachedmethod(lambda self: self.cache, lock=lambda self: self)
     def get(self, value):
         return self.count
 
@@ -42,11 +41,11 @@ class Unhashable:
     def __init__(self, cache):
         self.cache = cache
 
-    @cachedmethod(operator.attrgetter("cache"))
+    @cachedmethod(lambda self: self.cache)
     def get_default(self, value):
         return value
 
-    @cachedmethod(operator.attrgetter("cache"), key=keys.hashkey)
+    @cachedmethod(lambda self: self.cache, key=keys.hashkey)
     def get_hashkey(self, value):
         return value
 
@@ -68,16 +67,16 @@ class CachedMethodTest(unittest.TestCase):
         cached.cache.clear()
         self.assertEqual(cached.get(1), 2)
 
-    def test_typed_dict(self):
+    def test_typedmethod_dict(self):
         cached = Cached(LRUCache(maxsize=2))
 
-        self.assertEqual(cached.get_typed(0), 0)
-        self.assertEqual(cached.get_typed(1), 1)
-        self.assertEqual(cached.get_typed(1), 1)
-        self.assertEqual(cached.get_typed(1.0), 2)
-        self.assertEqual(cached.get_typed(1.0), 2)
-        self.assertEqual(cached.get_typed(0.0), 3)
-        self.assertEqual(cached.get_typed(0), 4)
+        self.assertEqual(cached.get_typedmethod(0), 0)
+        self.assertEqual(cached.get_typedmethod(1), 1)
+        self.assertEqual(cached.get_typedmethod(1), 1)
+        self.assertEqual(cached.get_typedmethod(1.0), 2)
+        self.assertEqual(cached.get_typedmethod(1.0), 2)
+        self.assertEqual(cached.get_typedmethod(0.0), 3)
+        self.assertEqual(cached.get_typedmethod(0), 4)
 
     def test_lru(self):
         cached = Cached(LRUCache(maxsize=2))
@@ -91,16 +90,16 @@ class CachedMethodTest(unittest.TestCase):
         cached.cache.clear()
         self.assertEqual(cached.get(1), 2)
 
-    def test_typed_lru(self):
+    def test_typedmethod_lru(self):
         cached = Cached(LRUCache(maxsize=2))
 
-        self.assertEqual(cached.get_typed(0), 0)
-        self.assertEqual(cached.get_typed(1), 1)
-        self.assertEqual(cached.get_typed(1), 1)
-        self.assertEqual(cached.get_typed(1.0), 2)
-        self.assertEqual(cached.get_typed(1.0), 2)
-        self.assertEqual(cached.get_typed(0.0), 3)
-        self.assertEqual(cached.get_typed(0), 4)
+        self.assertEqual(cached.get_typedmethod(0), 0)
+        self.assertEqual(cached.get_typedmethod(1), 1)
+        self.assertEqual(cached.get_typedmethod(1), 1)
+        self.assertEqual(cached.get_typedmethod(1.0), 2)
+        self.assertEqual(cached.get_typedmethod(1.0), 2)
+        self.assertEqual(cached.get_typedmethod(0.0), 3)
+        self.assertEqual(cached.get_typedmethod(0), 4)
 
     def test_nospace(self):
         cached = Cached(LRUCache(maxsize=0))
@@ -142,10 +141,10 @@ class CachedMethodTest(unittest.TestCase):
         self.assertEqual(cached.get(1), 2)
         self.assertEqual(cached.get(1.0), 2)
 
-        ref = cached.get_typed(1)
+        ref = cached.get_typedmethod(1)
         self.assertEqual(ref, 3)
-        self.assertEqual(cached.get_typed(1), 3)
-        self.assertEqual(cached.get_typed(1.0), 4)
+        self.assertEqual(cached.get_typedmethod(1), 3)
+        self.assertEqual(cached.get_typedmethod(1.0), 4)
 
         cached.cache.clear()
         self.assertEqual(cached.get(1), 5)

{cachetools-5.3.2 → cachetools-5.4.0}/tests/test_func.py

@@ -100,30 +100,32 @@ class DecoratorTestMixin:
 
 
 class FIFODecoratorTest(unittest.TestCase, DecoratorTestMixin):
-
     DECORATOR = staticmethod(cachetools.func.fifo_cache)
 
 
 class LFUDecoratorTest(unittest.TestCase, DecoratorTestMixin):
-
     DECORATOR = staticmethod(cachetools.func.lfu_cache)
 
 
 class LRUDecoratorTest(unittest.TestCase, DecoratorTestMixin):
-
     DECORATOR = staticmethod(cachetools.func.lru_cache)
 
 
 class MRUDecoratorTest(unittest.TestCase, DecoratorTestMixin):
+    def decorator(self, maxsize, **kwargs):
+        import warnings
 
-    DECORATOR = staticmethod(cachetools.func.mru_cache)
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            d = cachetools.func.mru_cache(maxsize, **kwargs)
+        self.assertNotEqual(len(w), 0)
+        self.assertIs(w[0].category, DeprecationWarning)
+        return d
 
 
 class RRDecoratorTest(unittest.TestCase, DecoratorTestMixin):
-
     DECORATOR = staticmethod(cachetools.func.rr_cache)
 
 
 class TTLDecoratorTest(unittest.TestCase, DecoratorTestMixin):
-
     DECORATOR = staticmethod(cachetools.func.ttl_cache)

{cachetools-5.3.2 → cachetools-5.4.0}/tests/test_mru.py

@@ -1,4 +1,5 @@
 import unittest
+import warnings
 
 from cachetools import MRUCache
 
@@ -7,10 +8,16 @@ from . import CacheTestMixin
 
 class MRUCacheTest(unittest.TestCase, CacheTestMixin):
 
+    # TODO: method to create cache that can be overridden
     Cache = MRUCache
 
     def test_evict__writes_only(self):
-        cache = MRUCache(maxsize=2)
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            cache = MRUCache(maxsize=2)
+        self.assertEqual(len(w), 1)
+        self.assertIs(w[0].category, DeprecationWarning)
 
         cache[1] = 1
         cache[2] = 2
@@ -22,7 +29,11 @@ class MRUCacheTest(unittest.TestCase, CacheTestMixin):
         assert 3 in cache
 
     def test_evict__with_access(self):
-        cache = MRUCache(maxsize=2)
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            cache = MRUCache(maxsize=2)
+        self.assertEqual(len(w), 1)
+        self.assertIs(w[0].category, DeprecationWarning)
 
         cache[1] = 1
         cache[2] = 2
@@ -34,7 +45,11 @@ class MRUCacheTest(unittest.TestCase, CacheTestMixin):
         assert 3 in cache
 
     def test_evict__with_delete(self):
-        cache = MRUCache(maxsize=2)
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            cache = MRUCache(maxsize=2)
+        self.assertEqual(len(w), 1)
+        self.assertIs(w[0].category, DeprecationWarning)
 
         cache[1] = 1
         cache[2] = 2

{cachetools-5.3.2 → cachetools-5.4.0}/tox.ini

@@ -32,7 +32,7 @@ commands =
 deps =
     flake8
     flake8-black; implementation_name == "cpython"
-    black==22.12.0; implementation_name == "cpython"
+    black==22.12.0; implementation_name == "cpython" and python_version < "3.8"
     flake8-bugbear
     flake8-import-order
 commands =