cachetools 7.2.4__tar.gz → 7.2.6__tar.gz

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

@@ -1,3 +1,25 @@
+v7.2.6 (2026-10-26)
+===================
+
+- Various performance improvements.
+
+
+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 +184,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 +248,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 +321,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 +446,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 +563,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 +692,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 +761,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 +775,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 +790,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 +818,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 +826,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.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachetools
-Version: 7.2.4
+Version: 7.2.6
 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.6}/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.