cachetools 7.2.4__tar.gz → 7.2.5__tar.gz

{cachetools-7.2.4 → cachetools-7.2.5}/CHANGELOG.rst

@@ -1,3 +1,19 @@
+v7.2.5 (2026-10-25)
+===================
+
+- Fix ``@cachedmethod`` with ``condition`` for decorated methods
+  taking a ``pending`` keyword argument (broken since v7.0.0).
+
+- Fix pickling and deep-copying of instances using ``@cachedmethod``
+  (broken since v7.0.0).
+
+- Fix calling ``@cachedmethod`` decorated methods through the class
+  with the receiver (``self``) passed as a keyword argument (broken
+  since v7.2.4).
+
+- Various documentation improvements.
+
+
 v7.2.4 (2026-10-19)
 ===================
 
@@ -162,7 +178,7 @@ v7.0.3 (2026-03-05)
 v7.0.2 (2026-03-02)
 ===================
 
-- Provide more efficient ``clear()`` implementation for all support
+- Provide more efficient ``clear()`` implementation for all supported
   Cache classes (courtesy Josep Pon Farreny).
 
 
@@ -226,7 +242,7 @@ v6.2.5 (2026-01-25)
 v6.2.4 (2025-12-15)
 ===================
 
-- Fix license information displayed on PyPI be using an updated
+- Fix license information displayed on PyPI by using an updated
   version of ``twine`` for uploading.
 
 
@@ -299,7 +315,7 @@ v6.0.0 (2025-05-23)
 - Convert the ``cachetools.func`` decorators to use a
   ``threading.Condition`` instance to deal with `cache stampede
   <https://en.wikipedia.org/wiki/Cache_stampede>`_ issues.  Note that
-  this *may* result in a noticable performance degradation, depending
+  this *may* result in a noticeable performance degradation, depending
   on your actual use case.
 
 - Deprecate support for ``cache(self)`` returning ``None`` to suppress
@@ -424,7 +440,7 @@ v5.0.0 (2021-12-21)
 
   ``from cachetools.ttl import TTLCache``
 
-  will no longer work. Use
+  will no longer work.  Use
 
   ``from cachetools import TTLCache``
 
@@ -541,7 +557,7 @@ v3.1.1 (2019-05-23)
 
 - Document how to use shared caches with ``@cachedmethod``.
 
-- Fix pickling/unpickling of cache keys
+- Fix pickling/unpickling of cache keys.
 
 
 v3.1.0 (2019-01-29)
@@ -670,17 +686,17 @@ v1.1.0 (2015-08-28)
 
 - Add ``hashkey`` and ``typedkey`` functions.
 
-- Add `key` and `lock` arguments to ``@cachedmethod``.
+- Add ``key`` and ``lock`` arguments to ``@cachedmethod``.
 
 - Set ``__wrapped__`` attributes for Python versions < 3.2.
 
 - Move ``functools`` compatible decorators to ``cachetools.func``.
 
-- Deprecate ``@cachedmethod`` `typed` argument.
+- Deprecate ``@cachedmethod`` ``typed`` argument.
 
-- Deprecate `cache` attribute for ``@cachedmethod`` wrappers.
+- Deprecate ``cache`` attribute for ``@cachedmethod`` wrappers.
 
-- Deprecate `getsizeof` and `lock` arguments for `cachetools.func`
+- Deprecate ``getsizeof`` and ``lock`` arguments for ``cachetools.func``
   decorator.
 
 
@@ -739,13 +755,13 @@ v0.8.0 (2014-12-03)
 
 - Add ``Cache.__missing__()``.
 
-- Feature freeze for `v1.0`.
+- Feature freeze for ``v1.0``.
 
 
 v0.7.1 (2014-11-22)
 ===================
 
-- Fix `MANIFEST.in`.
+- Fix ``MANIFEST.in``.
 
 
 v0.7.0 (2014-11-12)
@@ -753,7 +769,7 @@ v0.7.0 (2014-11-12)
 
 - Deprecate ``TTLCache.ExpiredError``.
 
-- Add `choice` argument to ``RRCache`` constructor.
+- Add ``choice`` argument to ``RRCache`` constructor.
 
 - Refactor ``LFUCache``, ``LRUCache`` and ``TTLCache``.
 
@@ -768,7 +784,7 @@ v0.6.0 (2014-10-13)
 
 - Support unsynchronized function decorators.
 
-- Allow ``@cachedmethod.cache()`` to return None
+- Allow ``@cachedmethod.cache()`` to return ``None``.
 
 
 v0.5.1 (2014-09-25)
@@ -796,7 +812,7 @@ v0.4.0 (2014-06-16)
 
 - Add ``Cache`` base class.
 
-- Remove ``@cachedmethod`` `lock` parameter.
+- Remove ``@cachedmethod`` ``lock`` parameter.
 
 
 v0.3.1 (2014-05-07)
@@ -804,7 +820,7 @@ v0.3.1 (2014-05-07)
 
 - Add proper locking for ``cache_clear()`` and ``cache_info()``.
 
-- Report `size` in ``cache_info()``.
+- Report ``size`` in ``cache_info()``.
 
 
 v0.3.0 (2014-05-06)

{cachetools-7.2.4/src/cachetools.egg-info → cachetools-7.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.2.4
+Version: 7.2.5
 Summary: Extensible memoizing collections and decorators
 Author-email: Thomas Kemmer <tkemmer@computer.org>
 Maintainer-email: Thomas Kemmer <tkemmer@computer.org>

{cachetools-7.2.4 → cachetools-7.2.5}/docs/index.rst

@@ -36,21 +36,23 @@ Cache implementations
 This module provides several classes implementing caches using
 different cache algorithms.  All these classes derive from class
 :class:`Cache`, which in turn derives from
-:class:`collections.abc.MutableMapping`, and provide :attr:`maxsize`
-and :attr:`currsize` properties to retrieve the maximum and current
+:class:`collections.abc.MutableMapping`, and provide
+:attr:`~Cache.maxsize` and :attr:`~Cache.currsize` properties to
+retrieve the maximum and current
 size 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.
 
-In general, a cache's size is the total size of its item's values.
-Therefore, :class:`Cache` provides a :meth:`getsizeof` method, which
+In general, a cache's size is the total size of its items' values.
+Therefore, :class:`Cache` provides a :meth:`~Cache.getsizeof` method, which
 returns the size of a given `value`.  The default implementation of
-:meth:`getsizeof` returns :const:`1` irrespective of its argument,
+:meth:`~Cache.getsizeof` returns :const:`1` irrespective of its argument,
 making the cache's size equal to the number of its items, or
 `len(cache)`.  For convenience, all cache classes accept an optional
 named constructor parameter `getsizeof`, which may specify a callable
-``getsizeof(value) -> int`` used to retrieve the size of an item's
-value.
+``getsizeof(value)`` returning a non-negative number as the size of
+an item's value.  An item whose size exceeds :attr:`~Cache.maxsize` cannot be
+stored, and trying to do so raises :exc:`ValueError`.
 
 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
@@ -92,6 +94,9 @@ inserted into the cache.
    This class counts how often an item is retrieved, and discards the
    items used least often to make space when necessary.
 
+   Updating a cache item via :meth:`LFUCache.__setitem__` also counts
+   as a use of the item, i.e. it will increment the item's use count.
+
 .. autoclass:: LRUCache(maxsize, getsizeof=None)
    :members: popitem
 
@@ -113,8 +118,8 @@ inserted into the cache.
    :members: popitem, timer, ttl
 
    This class associates a time-to-live value with each item.  Items
-   that expire because they have exceeded their time-to-live will be
-   no longer accessible, and will be removed eventually.  If no
+   that expire because they have exceeded their time-to-live will no
+   longer be accessible, and will be removed eventually.  If no
    expired items are there to remove, the least recently used items
    will be discarded first to make space when necessary.
 
@@ -140,14 +145,13 @@ inserted into the cache.
 
    .. method:: expire(self, time=None)
 
-      Expired items will be removed from a cache only at the next
-      mutating operation, e.g. :meth:`__setitem__` or
-      :meth:`__delitem__`, and therefore may still claim memory.
-      Calling this method removes all items whose time-to-live would
-      have expired by `time`, so garbage collection is free to reuse
-      their memory.  If `time` is :const:`None`, this removes all
-      items that have expired by the current value returned by
-      :attr:`timer`.
+      Expired items will be removed from a cache lazily, e.g. when
+      :meth:`__setitem__` is next called, and therefore may still
+      claim memory.  Calling this method removes all items whose
+      time-to-live would have expired by `time`, so garbage collection
+      is free to reuse their memory.  If `time` is :const:`None`, this
+      removes all items that have expired by the current value
+      returned by :attr:`timer`.
 
       :returns: An iterable of expired `(key, value)` pairs.
 
@@ -187,20 +191,19 @@ inserted into the cache.
       cache = TLRUCache(maxsize=10, ttu=datetime_ttu, timer=datetime.now)
 
    Items that expire because they have exceeded their time-to-use will
-   be no longer accessible, and will be removed eventually.  If no
+   no longer be accessible, and will be removed eventually.  If no
    expired items are there to remove, the least recently used items
    will be discarded first to make space when necessary.
 
    .. method:: expire(self, time=None)
 
-      Expired items will be removed from a cache only at the next
-      mutating operation, e.g. :meth:`__setitem__` or
-      :meth:`__delitem__`, and therefore may still claim memory.
-      Calling this method removes all items whose time-to-use would
-      have expired by `time`, so garbage collection is free to reuse
-      their memory.  If `time` is :const:`None`, this removes all
-      items that have expired by the current value returned by
-      :attr:`timer`.
+      Expired items will be removed from a cache lazily, e.g. when
+      :meth:`__setitem__` is next called, and therefore may still
+      claim memory.  Calling this method removes all items whose
+      time-to-use would have expired by `time`, so garbage collection
+      is free to reuse their memory.  If `time` is :const:`None`, this
+      removes all items that have expired by the current value
+      returned by :attr:`timer`.
 
       :returns: An iterable of expired `(key, value)` pairs.
 
@@ -208,10 +211,11 @@ inserted into the cache.
 Extending cache classes
 =======================
 
-Sometimes it may be desirable to notice when and what cache items are
-evicted, i.e. removed from a cache to make room for new items.  Since
-all cache implementations call :meth:`popitem` to evict items from the
-cache, this can be achieved by overriding this method in a subclass:
+Sometimes it may be desirable to be notified when cache items are
+evicted, i.e. removed from a cache to make room for new items, and
+which ones.  Since all cache implementations call :meth:`popitem` to
+evict items from the cache, this can be achieved by overriding this
+method in a subclass:
 
 .. doctest::
 
@@ -229,10 +233,10 @@ cache, this can be achieved by overriding this method in a subclass:
 
 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 overriding :meth:`expire`, a subclass will be able to track
-expired items:
+be called, but :meth:`expire` will be called lazily, e.g. from the
+next :meth:`__setitem__`, and will return an iterable of the expired
+`(key, value)` pairs.  By overriding :meth:`expire`, a subclass will
+be able to track expired items:
 
 .. doctest::
 
@@ -329,16 +333,16 @@ often called with the same arguments:
       therefore must be `thread-safe`_ by itself.
 
    If `condition` is not :const:`None`, it must specify a `condition
-   variable`_, i.e. an object providing :func:`wait()`,
-   :func:`wait_for()`, :func:`notify()` and :func:`notify_all()`
+   variable`_, i.e. an object providing :meth:`wait()`,
+   :meth:`wait_for()`, :meth:`notify()` and :meth:`notify_all()`
    methods as defined by :class:`threading.Condition`.  Using a
    `condition` variable will prevent concurrent execution of the
    wrapped function with *identical* parameters, or cache keys.
    Instead, a calling thread will check if an identical function call
-   is already executing, and will then :func:`wait()` for the pending
-   call to finish.  The executing thread will :func:`notify()` any
-   waiting threads as soon as the function completes, which will then
-   return the cached function result.
+   is already executing, and will then wait for the pending call to
+   finish.  The executing thread will notify any waiting threads as
+   soon as the function completes, which will then return the cached
+   function result.
 
    .. note::
 
@@ -346,7 +350,7 @@ often called with the same arguments:
       make :func:`cached` `thread-safe`_, it may still be subject to
       `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.
+      these situations, but will incur a performance penalty.
 
    If no separate `lock` parameter is provided, `condition` must also
    implement the `context manager`_ protocol, and will also be used to
@@ -374,7 +378,7 @@ often called with the same arguments:
           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
+   decorator also provides a :meth:`cache_clear()` function which
    takes care of locking automatically, if needed:
 
    .. testcode::
@@ -389,8 +393,8 @@ often called with the same arguments:
 
    .. note::
 
-      Note that this will inflict some performance penalty, so it has
-      to be enabled explicitly.
+      This will incur a small performance penalty, so it has to be
+      enabled explicitly.
 
    .. doctest::
 
@@ -427,18 +431,18 @@ often called with the same arguments:
       >>> # compute Fibonacci numbers
       >>> @cached(numcache, key=partial(hashkey, 'fib'))
       ... def fib(n):
-      ...    return n if n < 2 else fib(n - 1) + fib(n - 2)
+      ...     return n if n < 2 else fib(n - 1) + fib(n - 2)
 
       >>> # compute Lucas numbers
       >>> @cached(numcache, key=partial(hashkey, 'luc'))
       ... def luc(n):
-      ...    return 2 - n if n < 2 else luc(n - 1) + luc(n - 2)
+      ...     return 2 - n if n < 2 else luc(n - 1) + luc(n - 2)
 
       >>> fib(42)
       267914296
       >>> luc(42)
       599074578
-      >>> list(sorted(numcache.items()))
+      >>> sorted(numcache.items())
       [..., (('fib', 42), 267914296), ..., (('luc', 42), 599074578)]
 
 
@@ -507,7 +511,7 @@ often called with the same arguments:
    .. doctest::
 
       >>> def foo(a=1):
-      ...     _foo(a)
+      ...     return _foo(a)
       ...
       >>> @cached(LRUCache(maxsize=100))
       ... def _foo(a):
@@ -533,10 +537,10 @@ often called with the same arguments:
    saves results in a cache.
 
    The main difference between this and the :func:`cached` function
-   decorator is that `cache`, `lock` and `condition` are not passed
-   objects, but functions.  Those will be called with :const:`self` as
-   their sole argument to retrieve a valid cache, lock, or condition
-   object for the respective instance.
+   decorator is that `cache`, `lock` and `condition` are not objects
+   but functions.  These will be called with `self` as their sole
+   argument to retrieve the cache, lock and condition objects for the
+   respective instance.
 
    .. note::
 
@@ -549,15 +553,15 @@ often called with the same arguments:
    `key`, `lock` and `condition` parameters are also available as
    :attr:`cache`, :attr:`cache_key`, :attr:`cache_lock` and
    :attr:`cache_condition` attributes of the wrapped instance method.
-   A :func:`cache_clear()` function will also be provided, as well as
-   an optional :func:`cache_info()` function reporting per-instance
+   A :meth:`cache_clear()` function will also be provided, as well as
+   an optional :meth:`cache_info()` function reporting per-instance
    cache statistics.
 
    Also, mostly for efficiency, this decorator requires that the
    :attr:`__dict__` attribute on each instance be a mutable mapping.
-   This means it will not work with some types, such as metaclasses,
-   and those that specify :attr:`__slots__` without including
-   :attr:`__dict__` as one of the defined slots.
+   This means it will not work with some types, such as those that
+   specify :attr:`__slots__` without including :attr:`__dict__` as one
+   of the defined slots.
 
    One advantage of :func:`cachedmethod` over the :func:`cached`
    function decorator is that cache properties such as `maxsize` can
@@ -587,7 +591,7 @@ often called with the same arguments:
       >>> # remove an individual cached PEP from the cache
       >>> key = peps.get.cache_key(320)
       >>> with peps.get.cache_lock:
-      ...    del peps.get.cache[key]
+      ...     del peps.get.cache[key]
 
       >>> peps.get.cache_info()
       CacheInfo(hits=3, misses=8, maxsize=32, currsize=7)
@@ -601,13 +605,12 @@ 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
-   implicit 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. `self`.  This is mostly for historical
+   reasons, but also ensures that `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
-   be part of the cache key.
+   e.g. :func:`cachetools.keys.hashkey`, if you need `self` to be part
+   of the cache key.
 
    When using a shared cache for multiple methods, be aware that
    different cache keys must be created for each method even when
@@ -634,7 +637,7 @@ often called with the same arguments:
           @cachedmethod(lambda self: self.cache, key=partial(methodkey, method='rfc'))
           def get_rfc(self, num):
               """Retrieve text of an IETF Request for Comments"""
-              url = 'https://tools.ietf.org/rfc/rfc%d.txt' % num
+              url = 'https://www.rfc-editor.org/rfc/rfc%d.txt' % num
               with urllib.request.urlopen(url) as s:
                   return s.read()
 
@@ -652,7 +655,7 @@ often called with the same arguments:
 
    Note how keyword arguments are used with :func:`functools.partial`
    to create distinct cache keys, to avoid issues with
-   :func:`methodkey` skipping its initial `self` argument.
+   :func:`~cachetools.keys.methodkey` skipping its initial `self` argument.
 
    .. versionchanged:: 7.0
 
@@ -664,7 +667,7 @@ often called with the same arguments:
       instance methods, and are finally officially supported.
 
       Require :attr:`__dict__` to be a mutable mapping to support
-      per-instance :func:`cache_info()`.
+      per-instance :meth:`cache_info()`.
 
       Returning :const:`None` from `cache(self)` is no longer supported.
 
@@ -692,18 +695,19 @@ often called with the same arguments:
 .. module:: cachetools.keys
 
 This module provides several functions that can be used as key
-functions with the :func:`cached` and :func:`cachedmethod` decorators:
+functions with the :func:`~cachetools.cached` and
+:func:`~cachetools.cachedmethod` decorators:
 
 .. autofunction:: hashkey
 
    This function returns a :class:`tuple` instance suitable as a cache
-   key, provided the positional and keywords arguments are hashable.
+   key, provided the positional and keyword arguments are hashable.
 
 .. autofunction:: methodkey
 
    This function is similar to :func:`hashkey`, but ignores its
    first positional argument, i.e. `self` when used with the
-   :func:`cachedmethod` decorator.
+   :func:`~cachetools.cachedmethod` decorator.
 
 .. autofunction:: typedkey
 
@@ -715,12 +719,12 @@ functions with the :func:`cached` and :func:`cachedmethod` decorators:
 
    This function is similar to :func:`typedkey`, but ignores its
    first positional argument, i.e. `self` when used with the
-   :func:`cachedmethod` decorator.
+   :func:`~cachetools.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
-will raise a :class:`TypeError`, since :class:`dict` is not hashable::
+will raise a :exc:`TypeError`, since :class:`dict` is not hashable::
 
   @cached(LRUCache(maxsize=128))
   def foo(x, y, z, env={}):
@@ -735,7 +739,7 @@ specially::
       key += tuple(sorted(env.items()))
       return key
 
-The :func:`envkey` function can then be used in decorator declarations
+The ``envkey`` function can then be used in decorator declarations
 like this::
 
   @cached(LRUCache(maxsize=128), key=envkey)
@@ -746,19 +750,19 @@ like this::
 
 
 ****************************************************************************
-:mod:`cachetools.func` --- :func:`functools.lru_cache` compatible decorators
+:mod:`cachetools.func` --- :func:`functools.lru_cache`-compatible decorators
 ****************************************************************************
 
 .. module:: cachetools.func
 
-To ease migration from (or to) Python 3's :func:`functools.lru_cache`,
-this module provides several memoizing function decorators with a
-similar API.  All these decorators wrap a function with a memoizing
-callable that saves up to the `maxsize` most recent calls, using
-different caching strategies.  If `maxsize` is set to :const:`None`,
-the size limit is disabled and the cache can grow without bound.
-For :func:`ttl_cache`, the time-to-live still applies, so cached
-results expire after `ttl` even without a size limit.
+To ease migration from (or to) :func:`functools.lru_cache`, this
+module provides several memoizing function decorators with a similar
+API.  All these decorators wrap a function with a memoizing callable
+that saves up to `maxsize` results, using different caching
+strategies.  If `maxsize` is set to :const:`None`, the size limit is
+disabled and the cache can grow without bound.  For :func:`ttl_cache`,
+the time-to-live still applies, so cached results expire after `ttl`
+even without a size limit.
 
 If the optional argument `typed` is set to :const:`True`, function
 arguments of different types will be cached separately.  For example,
@@ -774,16 +778,16 @@ leaving the `maxsize` at its default value of 128::
       sentence = sentence.casefold()
       return sum(sentence.count(vowel) for vowel in 'aeiou')
 
-The wrapped function is instrumented with a :func:`cache_parameters`
+The wrapped function is instrumented with a :meth:`cache_parameters`
 function that returns a new :class:`dict` showing the values for
 `maxsize` and `typed`.  This is for information purposes only.
 Mutating the values has no effect.
 
-The wrapped function is also instrumented with :func:`cache_info` and
-:func:`cache_clear` functions to provide information about cache
+The wrapped function is also instrumented with :meth:`cache_info` and
+:meth:`cache_clear` functions to provide information about cache
 performance and clear the cache.  Please see the
 :func:`functools.lru_cache` documentation for details.  Also note that
-all the decorators in this module are thread-safe by default.
+all the decorators in this module are thread-safe.
 
 
 .. decorator:: fifo_cache(user_function)
@@ -817,8 +821,8 @@ all the decorators in this module are thread-safe by default.
 .. decorator:: ttl_cache(user_function)
                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)
+   Decorator that wraps 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.  By default,
    the time-to-live is set to 600 seconds and :func:`time.monotonic`
    is used to retrieve the current time.

{cachetools-7.2.4 → cachetools-7.2.5}/src/cachetools/__init__.py

@@ -12,7 +12,7 @@ __all__ = (
     "cachedmethod",
 )
 
-__version__ = "7.2.4"
+__version__ = "7.2.5"
 
 import collections
 import collections.abc
@@ -266,7 +266,7 @@ class LFUCache(Cache):
         self.__links.clear()
 
     def __touch(self, key):
-        """Increment use count"""
+        """Increment use count."""
         link = self.__links[key]
         curr = link.next
         if curr.count != link.count + 1:
@@ -319,7 +319,7 @@ class LRUCache(Cache):
         self.__order.clear()
 
     def __touch(self, key):
-        """Mark as recently used"""
+        """Mark as recently used."""
         try:
             self.__order.move_to_end(key)
         except KeyError:
@@ -370,7 +370,7 @@ class RRCache(Cache):
 
 
 class _TimedCache(Cache):
-    """Base class for time aware cache implementations."""
+    """Base class for time-aware cache implementations."""
 
     class _Timer:
         def __init__(self, timer):
@@ -590,7 +590,7 @@ class TTLCache(_TimedCache):
 
 
 class TLRUCache(_TimedCache):
-    """Time aware Least Recently Used (TLRU) cache implementation."""
+    """Time-aware Least Recently Used (TLRU) cache implementation."""
 
     __HEAP_CLEANUP_FACTOR = 2  # clean up the heap if size > N * len(items)
 
@@ -668,7 +668,7 @@ class TLRUCache(_TimedCache):
 
     @property
     def ttu(self):
-        """The local time-to-use function used by the cache."""
+        """The time-to-use function used by the cache."""
         return self.__ttu
 
     def expire(self, time=None):

{cachetools-7.2.4 → cachetools-7.2.5}/src/cachetools/__init__.pyi

@@ -232,6 +232,14 @@ class _cachedmethod_unbound(Generic[_P, _R]):
     __qualname__: str
     __doc__: str | None
     @overload
+    def __get__(
+        self, obj: None, objtype: type | None = None
+    ) -> _cachedmethod_unbound[_P, _R]: ...
+    @overload
+    def __get__(
+        self, obj: Any, objtype: type | None = None
+    ) -> _cachedmethod_wrapper[_P, _R]: ...
+    @overload
     def __call__(self, obj: Any, /, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
     # deprecated @classmethod use
     @overload

{cachetools-7.2.4 → cachetools-7.2.5}/src/cachetools/_cachedmethod.py

@@ -17,16 +17,24 @@ def _none(_):
 class _WrapperBase:
     """Wrapper base class providing default implementations for properties."""
 
-    def __init__(self, obj, method, cache, key, lock=None, cond=None):
+    def __init__(self, obj, descriptor, method, cache, key, lock=None, cond=None):
         if isinstance(obj, type):
             _warn_classmethod(stacklevel=5)
         functools.update_wrapper(self, method)
         self._obj = obj  # protected
+        self.__descriptor = descriptor
         self.__cache = cache
         self.__key = functools.partial(key, obj)
         self.__lock = lock if lock is not None else _none
         self.__cond = cond if cond is not None else _none
 
+    def __reduce__(self):
+        # rebuild via the descriptor instead of pickling unpicklable
+        # internals, e.g. __wrapped__, lock/cond closures; note that
+        # this will also reset hits and misses counts for *Info*
+        # wrappers
+        return (self.__descriptor.__get__, (self._obj,))
+
     def __call__(self, *args, **kwargs):
         raise NotImplementedError()  # pragma: no cover
 
@@ -59,8 +67,8 @@ class _WrapperBase:
 def _condition_info(method, cache, key, lock, cond, info):
     class Descriptor(_MethodDescriptor):
         class Wrapper(_WrapperBase):
-            def __init__(self, obj):
-                super().__init__(obj, method, cache, key, lock, cond)
+            def __init__(self, obj, descriptor):
+                super().__init__(obj, descriptor, method, cache, key, lock, cond)
                 self.__hits = self.__misses = 0
                 self.__pending = set()
 
@@ -107,8 +115,8 @@ def _condition_info(method, cache, key, lock, cond, info):
 def _locked_info(method, cache, key, lock, info):
     class Descriptor(_MethodDescriptor):
         class Wrapper(_WrapperBase):
-            def __init__(self, obj):
-                super().__init__(obj, method, cache, key, lock)
+            def __init__(self, obj, descriptor):
+                super().__init__(obj, descriptor, method, cache, key, lock)
                 self.__hits = self.__misses = 0
 
             def __call__(self, *args, **kwargs):
@@ -147,8 +155,8 @@ def _locked_info(method, cache, key, lock, info):
 def _unlocked_info(method, cache, key, info):
     class Descriptor(_MethodDescriptor):
         class Wrapper(_WrapperBase):
-            def __init__(self, obj):
-                super().__init__(obj, method, cache, key)
+            def __init__(self, obj, descriptor):
+                super().__init__(obj, descriptor, method, cache, key)
                 self.__hits = self.__misses = 0
 
             def __call__(self, *args, **kwargs):
@@ -181,7 +189,7 @@ def _condition(method, cache, key, lock, cond):
     # backward-compatible weakref dictionary for Python >= 3.13
     pending = weakref.WeakKeyDictionary()
 
-    def wrapper(self, pending, *args, **kwargs):
+    def wrapper(self, pending, /, *args, **kwargs):
         c = cache(self)
         k = key(self, *args, **kwargs)
         with lock(self):
@@ -214,8 +222,8 @@ def _condition(method, cache, key, lock, cond):
 
     class Descriptor(_ClassMethodDescriptor):
         class Wrapper(_WrapperBase):
-            def __init__(self, obj):
-                super().__init__(obj, method, cache, key, lock, cond)
+            def __init__(self, obj, descriptor):
+                super().__init__(obj, descriptor, method, cache, key, lock, cond)
                 self.__pending = set()
 
             def __call__(self, *args, **kwargs):
@@ -254,8 +262,8 @@ def _locked(method, cache, key, lock):
 
     class Descriptor(_ClassMethodDescriptor):
         class Wrapper(_WrapperBase):
-            def __init__(self, obj):
-                super().__init__(obj, method, cache, key, lock)
+            def __init__(self, obj, descriptor):
+                super().__init__(obj, descriptor, method, cache, key, lock)
 
             def __call__(self, *args, **kwargs):
                 return wrapper(self._obj, *args, **kwargs)
@@ -288,8 +296,8 @@ def _unlocked(method, cache, key):
 
     class Descriptor(_ClassMethodDescriptor):
         class Wrapper(_WrapperBase):
-            def __init__(self, obj):
-                super().__init__(obj, method, cache, key)
+            def __init__(self, obj, descriptor):
+                super().__init__(obj, descriptor, method, cache, key)
 
             def __call__(self, *args, **kwargs):
                 return wrapper(self._obj, *args, **kwargs)

{cachetools-7.2.4 → cachetools-7.2.5}/src/cachetools/_descriptor.py

@@ -26,12 +26,14 @@ class _MethodDescriptor:
     """Descriptor class implementing the basic descriptor protocol."""
 
     def __init__(self, deprecated=False):
+        self.__owner = None
         self.__attrname = None
         self.__deprecated = deprecated
         self.__unbound = None
 
     def __set_name__(self, owner, name):
         if self.__attrname is None:
+            self.__owner = owner
             self.__attrname = name
         elif name != self.__attrname:
             raise TypeError(
@@ -45,7 +47,7 @@ class _MethodDescriptor:
             return self.__get_unbound()
         elif self.__attrname is not None:
             # replace descriptor instance with wrapper in instance dict
-            wrapper = self.Wrapper(obj)  # type: ignore
+            wrapper = self.Wrapper(obj, self)  # type: ignore
             try:
                 descriptor = next(
                     (
@@ -86,12 +88,21 @@ class _MethodDescriptor:
                     raise TypeError(msg) from None
         elif self.__deprecated:
             # deprecated @classmethod, warning already raised elsewhere
-            wrapper = self.Wrapper(obj)  # type: ignore
+            wrapper = self.Wrapper(obj, self)  # type: ignore
         else:
             msg = "Cannot use @cachedmethod instance without calling __set_name__ on it"
             raise TypeError(msg) from None
         return wrapper
 
+    def __reduce__(self):
+        # pickle and copy by reference, so wrappers and their keys in
+        # "__cachetools_cachedmethods" can be pickled and deep-copied
+        return (self._lookup, (self.__owner, self.__attrname))
+
+    @staticmethod
+    def _lookup(owner, name):
+        return owner.__dict__[name]
+
     def __get_unbound(self):
         # Created once and shared by all class accesses; objtype is not
         # used for instance lookups, so it need not be bound here.
@@ -111,16 +122,46 @@ class _Unbound:
     def __init__(self, descriptor):
         functools.update_wrapper(self, descriptor.__wrapped__)
         self.__descriptor = descriptor
+        self.__receiver = None  # name of the wrapped method's first parameter
+
+    def __reduce__(self):
+        # pickle and copy by reference, as functions are
+        return (self.__descriptor.__get__, (None,))
+
+    # bind like a method when aliased in another class body
+    def __get__(self, obj, objtype=None):
+        if obj is None:
+            return self
+        return self.__descriptor.__get__(obj)
 
     # Receiver is taken from *args so autospec'd instances accept any call,
     # as they did before class access returned a callable.
     def __call__(self, /, *args, **kwargs):
-        if not args:
-            msg = "Cannot call @cachedmethod through the class without an instance"
-            raise TypeError(msg)
-        obj, *args = args
+        if args:
+            obj, *args = args
+        else:
+            obj = self.__pop_receiver(kwargs)
         return self.__descriptor.__get__(obj)(*args, **kwargs)
 
+    def __pop_receiver(self, kwargs):
+        # the receiver may also be passed by keyword, as for a plain function
+        if self.__receiver is None:
+            import inspect
+
+            self.__receiver = ""
+            try:
+                param = next(iter(inspect.signature(self).parameters.values()))
+            except (ValueError, StopIteration):
+                pass  # no signature, or no parameters at all
+            else:
+                if param.kind is param.POSITIONAL_OR_KEYWORD:
+                    self.__receiver = param.name
+        try:
+            return kwargs.pop(self.__receiver)
+        except KeyError:
+            msg = "Cannot call @cachedmethod through the class without an instance"
+            raise TypeError(msg) from None
+
 
 class _ClassMethodDescriptor(_MethodDescriptor):
     """Descriptor base class supporting deprecated @classmethod use."""

{cachetools-7.2.4 → cachetools-7.2.5/src/cachetools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.2.4
+Version: 7.2.5
 Summary: Extensible memoizing collections and decorators
 Author-email: Thomas Kemmer <tkemmer@computer.org>
 Maintainer-email: Thomas Kemmer <tkemmer@computer.org>

{cachetools-7.2.4 → cachetools-7.2.5}/tests/test_cachedmethod.py

@@ -1,5 +1,6 @@
 import unittest
 import warnings
+from collections.abc import Callable
 
 from cachetools import Cache, cachedmethod, keys
 
@@ -69,6 +70,18 @@ class Cached:
     def get_lock_cond_info(self, value):
         return self.__get(value)
 
+    get_aliased = cachedmethod(lambda self: self.cache)(__get)
+
+
+class CachedChild(Cached):
+    def __init__(self, cache, child_cache):
+        super().__init__(cache)
+        self.child_cache = child_cache
+
+    @cachedmethod(lambda self: self.child_cache, info=True)
+    def get_info(self, value):
+        return super().get_info(value) + 1
+
 
 class Unhashable(Cached):
     # https://github.com/tkem/cachetools/issues/107
@@ -421,6 +434,121 @@ class MethodDecoratorTestMixin(SimplifiedTestCaseProtocol):
         self.assertEqual(len(cache), 0)
         self.assertEqual(cached.cond.count, 4)
 
+    def test_decorator_pickle(self):
+        import pickle
+
+        cache = self.cache(3)
+        cached = Cached(cache)
+        self.assertEqual(len(cache), 0)
+
+        unpickled = pickle.loads(pickle.dumps(cached))
+        self.assertEqual(len(unpickled.get_cond.cache), 0)
+        self.assertEqual(len(cache), 0)
+        self.assertEqual(unpickled.get_cond(0), 0)
+        self.assertEqual(len(unpickled.get_cond.cache), 1)
+        self.assertEqual(len(cache), 0)
+        self.assertEqual(unpickled.get_cond(1), 1)
+        self.assertEqual(len(unpickled.get_cond.cache), 2)
+        self.assertEqual(len(cache), 0)
+
+        self.assertEqual(len(cache), 0)
+        self.assertEqual(cached.get_cond(0), 0)
+        self.assertEqual(len(cache), 1)
+
+        unpickled = pickle.loads(pickle.dumps(cached))
+        self.assertEqual(len(unpickled.get_cond.cache), 1)
+        self.assertEqual(len(cache), 1)
+        self.assertEqual(unpickled.get_cond(0), 0)
+        self.assertEqual(len(unpickled.get_cond.cache), 1)
+        self.assertEqual(len(cache), 1)
+        self.assertEqual(unpickled.get_cond(1), 1)
+        self.assertEqual(len(unpickled.get_cond.cache), 2)
+        self.assertEqual(len(cache), 1)
+
+    def test_decorator_pickle_info(self):
+        import pickle
+
+        cache = self.cache(3)
+        cached = Cached(cache)
+        maxsize = cache.maxsize if isinstance(cache, Cache) else None
+        self.assertEqual(len(cache), 0)
+
+        # hits and misses will be reset when unpickling - since these
+        # are primarily used for debugging/tuning, this is probably OK
+        unpickled = pickle.loads(pickle.dumps(cached))
+        self.assertEqual(unpickled.get_cond_info.cache_info(), (0, 0, maxsize, 0))
+        self.assertEqual(unpickled.get_cond_info(0), 0)
+        self.assertEqual(unpickled.get_cond_info.cache_info(), (0, 1, maxsize, 1))
+        self.assertEqual(unpickled.get_cond_info(1), 1)
+        self.assertEqual(unpickled.get_cond_info.cache_info(), (0, 2, maxsize, 2))
+        self.assertEqual(len(cache), 0)
+
+        self.assertEqual(cached.get_cond_info(0), 0)
+        self.assertEqual(len(cache), 1)
+
+        unpickled = pickle.loads(pickle.dumps(cached))
+        self.assertEqual(unpickled.get_cond_info.cache_info(), (0, 0, maxsize, 1))
+        self.assertEqual(unpickled.get_cond_info(0), 0)
+        self.assertEqual(unpickled.get_cond_info.cache_info(), (1, 0, maxsize, 1))
+        self.assertEqual(unpickled.get_cond_info(1), 1)
+        self.assertEqual(unpickled.get_cond_info.cache_info(), (1, 1, maxsize, 2))
+        self.assertEqual(unpickled.get_cond_info(0), 0)
+        self.assertEqual(unpickled.get_cond_info.cache_info(), (2, 1, maxsize, 2))
+        self.assertEqual(len(cache), 1)
+
+    def test_decorator_pickle_super(self):
+        import pickle
+
+        self._test_copy_super(lambda obj: pickle.loads(pickle.dumps(obj)))
+
+    def test_decorator_deepcopy_super(self):
+        import copy
+
+        self._test_copy_super(copy.deepcopy)
+
+    def _test_copy_super(self, copyfunc: Callable[[CachedChild], CachedChild]):
+        base_cache = self.cache(3)
+        maxsize = base_cache.maxsize if isinstance(base_cache, Cache) else None
+        cached = CachedChild(base_cache, self.cache(3))
+        self.assertEqual(cached.get_info(0), 1)
+
+        copied = copyfunc(cached)
+        child = copied.get_info
+        base = super(CachedChild, copied).get_info
+        self.assertIsNot(base, child)
+        self.assertIs(base, super(CachedChild, copied).get_info)
+        self.assertIs(child.cache, copied.child_cache)
+        self.assertIs(base.cache, copied.cache)
+        self.assertEqual(len(vars(copied)["__cachetools_cachedmethods"]), 1)
+        # hits and misses are reset
+        self.assertEqual(child.cache_info(), (0, 0, maxsize, 1))
+        self.assertEqual(base.cache_info(), (0, 0, maxsize, 1))
+
+        self.assertEqual(copied.get_info(0), 1)
+        self.assertEqual(child.cache_info(), (1, 0, maxsize, 1))
+        self.assertEqual(base.cache_info(), (0, 0, maxsize, 1))
+        self.assertEqual(copied.get_info(1), 2)
+        self.assertEqual(child.cache_info(), (1, 1, maxsize, 2))
+        self.assertEqual(base.cache_info(), (0, 1, maxsize, 2))
+        self.assertEqual(len(vars(copied)["__cachetools_cachedmethods"]), 1)
+        self.assertEqual(len(base_cache), 1)
+
+    def test_decorator_pickle_aliased(self):
+        import pickle
+
+        cache = self.cache(3)
+        cached = Cached(cache)
+        self.assertEqual(len(cache), 0)
+
+        self.assertEqual(cached.get_aliased(0), 0)
+        self.assertEqual(len(cache), 1)
+
+        unpickled = pickle.loads(pickle.dumps(cached))
+        self.assertEqual(len(unpickled.get_aliased.cache), 1)
+        self.assertEqual(unpickled.get_aliased(0), 0)
+        self.assertEqual(len(unpickled.get_aliased.cache), 1)
+        self.assertEqual(len(cache), 1)
+
     def test_decorator_slots(self):
 
         class Slots:
@@ -706,6 +834,28 @@ class CacheMethodTest(unittest.TestCase, MethodDecoratorTestMixin):
         self.assertEqual(super(GrandChild, cached).get_typed(0), 1)
         self.assertEqual(super(Child, cached).get_typed(0.0), 0)
 
+    def test_cond_pending_keyword(self):
+        # Up until cachetools v7.2.4, @cachedmethod with condition and
+        # info=False raised a TypeError when the wrapped method
+        # received a valid "pending" keyword argument.
+        for info in (False, True):
+            with self.subTest(info=info):
+
+                class Pending(Cached):
+                    @cachedmethod(
+                        lambda obj: obj.cache,
+                        condition=lambda obj: obj.cond,
+                        info=info,
+                    )
+                    def get_pending(self, pending):
+                        return self.get(pending)
+
+                cached = Pending(self.cache(2))
+                self.assertEqual(cached.get_pending(pending=0), 0)
+                self.assertEqual(cached.get_pending(pending=0), 0)
+                cached.get_pending.cache_clear()
+                self.assertEqual(cached.get_pending(pending=0), 1)
+
 
 class DictMethodTest(unittest.TestCase, MethodDecoratorTestMixin):
     def cache(self, minsize, **_kwargs):
@@ -791,6 +941,41 @@ class UnboundMethodTest(unittest.TestCase):
         with self.assertRaises(TypeError):
             Cached.get()  # type: ignore
 
+    def test_class_call_keyword_receiver(self):
+        cached = Cached(Cache(2))
+        self.assertEqual(Cached.get(self=cached, value=1), 0)  # type: ignore
+        self.assertEqual(Cached.get(cached, value=1), 0)
+        self.assertEqual(Cached.get(self=cached, value=2), 1)  # type: ignore
+        self.assertEqual(cached.count, 2)
+        with self.assertRaises(TypeError):
+            Cached.get(value=1)
+
+        class Named:
+            def __init__(self, cache):
+                self.cache = cache
+
+            @cachedmethod(lambda this: this.cache)
+            def get(this, value):
+                return value
+
+            @cachedmethod(lambda self: self.cache)
+            def get_posonly(self, /, value):
+                return value
+
+            @cachedmethod(lambda self: self.cache)  # type: ignore
+            def get_noargs():
+                return 42
+
+        named = Named(Cache(2))
+        self.assertEqual(Named.get(this=named, value=1), 1)  # type: ignore
+        self.assertEqual(Named.get(named, value=1), 1)
+        with self.assertRaises(TypeError):
+            Named.get(self=named, value=1)  # type: ignore
+        with self.assertRaises(TypeError):
+            Named.get_posonly(self=named, value=1)  # type: ignore
+        with self.assertRaises(TypeError):
+            Named.get_noargs()
+
     def test_class_access_identity(self):
         self.assertIs(Cached.get, Cached.get)
         self.assertIs(Cached.get_info, Cached.get_info)
@@ -806,6 +991,30 @@ class UnboundMethodTest(unittest.TestCase):
         self.assertEqual(Cached.get.__wrapped__(cached, 1), 1)
         self.assertEqual(len(cached.cache), 0)
 
+    def test_class_access_pickle(self):
+        import pickle
+
+        for proto in range(pickle.HIGHEST_PROTOCOL + 1):
+            with self.subTest(proto=proto):
+                self.assertIs(pickle.loads(pickle.dumps(Cached.get, proto)), Cached.get)
+
+    def test_class_access_copy(self):
+        import copy
+
+        self.assertIs(copy.copy(Cached.get), Cached.get)
+        self.assertIs(copy.deepcopy(Cached.get), Cached.get)
+
+    def test_class_access_alias(self):
+        class Alias(Cached):
+            alias = Cached.get
+
+        self.assertIs(Alias.alias, Cached.get)
+        cached = Alias(Cache(2))
+        self.assertEqual(cached.alias(1), 0)
+        self.assertEqual(cached.alias(1), 0)
+        self.assertIs(cached.alias, cached.get)
+        self.assertEqual(len(cached.cache), 1)
+
     def test_autospec_no_warnings(self):
         import unittest.mock