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)
===================
- Restore autospec calls to ``@cachedmethod`` decorated methods.
- Improve branch coverage of unit tests.
- Minor type stub improvements.
v7.2.3 (2026-10-17)
===================
- Fix ``@cached`` decorator stacking behavior.
- Minor type stub improvements.
v7.2.2 (2026-10-15)
===================
- Fix ``@cachedmethod`` for subclasses that override a decorated
method and call the base class implementation via ``super()``.
- Restore class access to instance methods decorated with
``@cachedmethod``.
- Improve ``TTLCache`` robustness when calculating expiration time
fails.
- Various unit test improvements.
v7.2.1 (2026-10-05)
===================
- Improve error handling for ``RRCache.popitem()`` when the cache is
empty.
- Minor style and documentation improvements.
- Update CI environment.
v7.2.0 (2026-09-16)
===================
- Deprecate use of ``cache=None`` to suppress caching with the
``@cached`` decorator.
- Add support for Python 3.15.
- Minor test improvements.
- Minor documentation updates.
v7.1.8 (2026-08-31)
===================
- Reject negative ``maxsize`` in ``Cache.__init__``.
v7.1.7 (2026-08-01)
===================
- Improve ``Cache.__setitem__`` behavior when replacing an existing
cache item with a larger value.
- Update CI environment.
v7.1.6 (2026-07-24)
===================
- Minor style improvements to keep ``ruff`` happy.
v7.1.5 (2026-07-23)
===================
- Fix ``TLRUCache`` silently keeping stale values on expired
overwrites.
- Reject negative cache item ``getsizeof`` values.
- Update build environment.
v7.1.4 (2026-05-22)
===================
- Minor unit test improvements.
- Update build environment.
v7.1.3 (2026-05-18)
===================
- Minor type stub improvements.
- Update build environment.
v7.1.2 (2026-05-16)
===================
- Minor type stub improvements.
- Minor documentation improvements.
- Modernize build environment.
v7.1.1 (2026-05-03)
===================
- Various type stub improvements.
v7.1.0 (2026-05-01)
===================
- Add type stubs based on the work of the good people at `typeshed
`__.
- Update unit tests.
v7.0.6 (2026-04-20)
===================
- Minor code improvements.
- Update project URLs.
- Update CI environment.
v7.0.5 (2026-03-09)
===================
- Minor ``@cachedmethod`` performance improvements.
v7.0.4 (2026-03-08)
===================
- Fix and properly document ``@cachedmethod.cache_key`` behavior.
- Minor documentation improvements.
v7.0.3 (2026-03-05)
===================
- Fix ``DeprecationWarning`` when creating an autospec mock with
``@cachedmethod`` decorations.
v7.0.2 (2026-03-02)
===================
- Provide more efficient ``clear()`` implementation for all supported
Cache classes (courtesy Josep Pon Farreny).
v7.0.1 (2026-02-10)
===================
- Various test improvements.
- Update Copilot Instructions.
v7.0.0 (2026-02-01)
===================
- Require Python 3.10 or later (breaking change).
- Drop support for passing ``info`` as fourth positional parameter to
``@cached`` (breaking change).
- Drop support for ``cache(self)`` returning ``None`` with
``@cachedmethod`` (breaking change).
- Convert the ``@cachedmethod`` wrappers to descriptors, deprecating
its use with class methods and instances that do not provide a
mutable ``__dict__`` attribute (potentially breaking change).
- Convert the previously undocumented ``@cachedmethod`` attributes
(``cache``, ``cache_lock``, etc.) to properties for instance
methods, providing official support and documentation (potentially
breaking change).
- Add an optional ``info`` parameter to the ``@cachedmethod``
decorator for reporting per-instance cache statistics. Note that
this requires the instance's ``__dict__`` attribute to be a mutable
mapping.
v6.2.6 (2026-01-27)
===================
- Improve typedkey performance.
- Minor documentation improvements.
- Minor testing improvements.
- Minor code readability improvements.
v6.2.5 (2026-01-25)
===================
- Improve documentation regarding ``@cachedmethod`` with ``lock``
parameter.
- Add test cases for cache stampede scenarios.
- Update CI environment.
v6.2.4 (2025-12-15)
===================
- Fix license information displayed on PyPI by using an updated
version of ``twine`` for uploading.
v6.2.3 (2025-12-12)
===================
- Improve documentation regarding ``@cachedmethod`` with ``condition``
parameter.
- Minor style and readability improvements.
- Modernize build environment.
- Update CI environment.
v6.2.2 (2025-11-13)
===================
- Minor improvements from GitHub Copilot code review.
- Improve documentation.
v6.2.1 (2025-10-12)
===================
- Add support for Python 3.14.
- Improve documentation.
- Update CI environment.
v6.2.0 (2025-08-25)
===================
- Improve general ``RRCache`` performance by storing cache keys in an
additional sequence container. Note that this will increase memory
consumption.
- Add more unit tests.
v6.1.0 (2025-06-16)
===================
- Improve ``LFUCache`` insertion performance by switching to an
implementation based on the `cacheing
`_ library.
- Update CI environment.
v6.0.0 (2025-05-23)
===================
- Require Python 3.9 or later (breaking change).
- Remove ``MRUCache`` and the ``@func.mru_cache`` decorator (breaking
change).
- Add an optional ``condition`` parameter to the ``@cached`` and
``@cachedmethod`` decorators, which, when used with a
``threading.Condition`` instance, should improve `cache stampede
`_ issues in massively
parallel environments. Note that this will inflict some performance
penalty, and therefore has to be enabled explicitly.
- Convert the ``cachetools.func`` decorators to use a
``threading.Condition`` instance to deal with `cache stampede
`_ issues. Note that
this *may* result in a noticeable performance degradation, depending
on your actual use case.
- Deprecate support for ``cache(self)`` returning ``None`` to suppress
caching with the ``@cachedmethod`` decorator.
- Improve documentation.
- Update CI environment.
v5.5.2 (2025-02-20)
===================
- Reduce number of ``@cached`` lock/unlock operations.
- Improve documentation.
- Update CI environment.
v5.5.1 (2025-01-21)
===================
- Add documentation regarding caching of exceptions.
- Officially support Python 3.13.
- Update CI environment.
v5.5.0 (2024-08-18)
===================
- ``TTLCache.expire()`` returns iterable of expired ``(key, value)``
pairs.
- ``TLRUCache.expire()`` returns iterable of expired ``(key, value)``
pairs.
- Documentation improvements.
- Update CI environment.
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)
===================
- Add support for Python 3.12.
- Various documentation improvements.
v5.3.1 (2023-05-27)
===================
- Depend on Python >= 3.7.
v5.3.0 (2023-01-22)
===================
- Add ``cache_info()`` function to ``@cached`` decorator.
v5.2.1 (2023-01-08)
===================
- Add support for Python 3.11.
- Correct version information in RTD documentation.
- ``badges/shields``: Change to GitHub workflow badge routes.
v5.2.0 (2022-05-29)
===================
- Add ``cachetools.keys.methodkey()``.
- Add ``cache_clear()`` function to decorators.
- Add ``src`` directory to ``sys.path`` for Sphinx autodoc.
- Modernize ``func`` wrappers.
v5.1.0 (2022-05-15)
===================
- Add cache decorator parameters as wrapper function attributes.
v5.0.0 (2021-12-21)
===================
- Require Python 3.7 or later (breaking change).
- Remove deprecated submodules (breaking change).
The ``cache``, ``fifo``, ``lfu``, ``lru``, ``mru``, ``rr`` and
``ttl`` submodules have been deleted. Therefore, statements like
``from cachetools.ttl import TTLCache``
will no longer work. Use
``from cachetools import TTLCache``
instead.
- Pass ``self`` to ``@cachedmethod`` key function (breaking change).
The ``key`` function passed to the ``@cachedmethod`` decorator is
now called as ``key(self, *args, **kwargs)``.
The default key function has been changed to ignore its first
argument, so this should only affect applications using custom key
functions with the ``@cachedmethod`` decorator.
- Change exact time of expiration in ``TTLCache`` (breaking change).
``TTLCache`` items now get expired if their expiration time is less
than *or equal to* ``timer()``. For applications using the default
``timer()``, this should be barely noticeable, but it may affect the
use of custom timers with larger tick intervals. Note that this
also implies that a ``TTLCache`` with ``ttl=0`` can no longer hold
any items, since they will expire immediately.
- Change ``Cache.__repr__()`` format (breaking change).
String representations of cache instances now use a more compact and
efficient format, e.g.
``LRUCache({1: 1, 2: 2}, maxsize=10, currsize=2)``
- Add TLRU cache implementation.
- Documentation improvements.
v4.2.4 (2021-09-30)
===================
- Add submodule shims for backward compatibility.
v4.2.3 (2021-09-29)
===================
- Add documentation and tests for using ``TTLCache`` with
``datetime``.
- Link to typeshed typing stubs.
- Flatten package file hierarchy.
v4.2.2 (2021-04-27)
===================
- Update build environment.
- Remove Python 2 remnants.
- Format code with Black.
v4.2.1 (2021-01-24)
===================
- Handle ``__missing__()`` not storing cache items.
- Clean up ``__missing__()`` example.
v4.2.0 (2020-12-10)
===================
- Add FIFO cache implementation.
- Add MRU cache implementation.
- Improve behavior of decorators in case of race conditions.
- Improve documentation regarding mutability of caches values and use
of key functions with decorators.
- Officially support Python 3.9.
v4.1.1 (2020-06-28)
===================
- Improve ``popitem()`` exception context handling.
- Replace ``float('inf')`` with ``math.inf``.
- Improve "envkey" documentation example.
v4.1.0 (2020-04-08)
===================
- Support ``user_function`` with ``cachetools.func`` decorators
(Python 3.8 compatibility).
- Support ``cache_parameters()`` with ``cachetools.func`` decorators
(Python 3.9 compatibility).
v4.0.0 (2019-12-15)
===================
- Require Python 3.5 or later.
v3.1.1 (2019-05-23)
===================
- Document how to use shared caches with ``@cachedmethod``.
- Fix pickling/unpickling of cache keys.
v3.1.0 (2019-01-29)
===================
- Fix Python 3.8 compatibility issue.
- Use ``time.monotonic`` as default timer if available.
- Improve documentation regarding thread safety.
v3.0.0 (2018-11-04)
===================
- Officially support Python 3.7.
- Drop Python 3.3 support (breaking change).
- Remove ``missing`` cache constructor parameter (breaking change).
- Remove ``self`` from ``@cachedmethod`` key arguments (breaking
change).
- Add support for ``maxsize=None`` in ``cachetools.func`` decorators.
v2.1.0 (2018-05-12)
===================
- Deprecate ``missing`` cache constructor parameter.
- Handle overridden ``getsizeof()`` method in subclasses.
- Fix Python 2.7 ``RRCache`` pickling issues.
- Various documentation improvements.
v2.0.1 (2017-08-11)
===================
- Officially support Python 3.6.
- Move documentation to RTD.
- Documentation: Update import paths for key functions (courtesy of
slavkoja).
v2.0.0 (2016-10-03)
===================
- Drop Python 3.2 support (breaking change).
- Drop support for deprecated features (breaking change).
- Move key functions to separate package (breaking change).
- Accept non-integer ``maxsize`` in ``Cache.__repr__()``.
v1.1.6 (2016-04-01)
===================
- Reimplement ``LRUCache`` and ``TTLCache`` using
``collections.OrderedDict``. Note that this will break pickle
compatibility with previous versions.
- Fix ``TTLCache`` not calling ``__missing__()`` of derived classes.
- Handle ``ValueError`` in ``Cache.__missing__()`` for consistency
with caching decorators.
- Improve how ``TTLCache`` handles expired items.
- Use ``Counter.most_common()`` for ``LFUCache.popitem()``.
v1.1.5 (2015-10-25)
===================
- Refactor ``Cache`` base class. Note that this will break pickle
compatibility with previous versions.
- Clean up ``LRUCache`` and ``TTLCache`` implementations.
v1.1.4 (2015-10-24)
===================
- Refactor ``LRUCache`` and ``TTLCache`` implementations. Note that
this will break pickle compatibility with previous versions.
- Document pending removal of deprecated features.
- Minor documentation improvements.
v1.1.3 (2015-09-15)
===================
- Fix pickle tests.
v1.1.2 (2015-09-15)
===================
- Fix pickling of large ``LRUCache`` and ``TTLCache`` instances.
v1.1.1 (2015-09-07)
===================
- Improve key functions.
- Improve documentation.
- Improve unit test coverage.
v1.1.0 (2015-08-28)
===================
- Add ``@cached`` function decorator.
- Add ``hashkey`` and ``typedkey`` functions.
- 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 ``cache`` attribute for ``@cachedmethod`` wrappers.
- Deprecate ``getsizeof`` and ``lock`` arguments for ``cachetools.func``
decorator.
v1.0.3 (2015-06-26)
===================
- Clear cache statistics when calling ``clear_cache()``.
v1.0.2 (2015-06-18)
===================
- Allow simple cache instances to be pickled.
- Refactor ``Cache.getsizeof`` and ``Cache.missing`` default
implementation.
v1.0.1 (2015-06-06)
===================
- Code cleanup for improved PEP 8 conformance.
- Add documentation and unit tests for using ``@cachedmethod`` with
generic mutable mappings.
- Improve documentation.
v1.0.0 (2014-12-19)
===================
- Provide ``RRCache.choice`` property.
- Improve documentation.
v0.8.2 (2014-12-15)
===================
- Use a ``NestedTimer`` for ``TTLCache``.
v0.8.1 (2014-12-07)
===================
- Deprecate ``Cache.getsize()``.
v0.8.0 (2014-12-03)
===================
- Ignore ``ValueError`` raised on cache insertion in decorators.
- Add ``Cache.getsize()``.
- Add ``Cache.__missing__()``.
- Feature freeze for ``v1.0``.
v0.7.1 (2014-11-22)
===================
- Fix ``MANIFEST.in``.
v0.7.0 (2014-11-12)
===================
- Deprecate ``TTLCache.ExpiredError``.
- Add ``choice`` argument to ``RRCache`` constructor.
- Refactor ``LFUCache``, ``LRUCache`` and ``TTLCache``.
- Use custom ``NullContext`` implementation for unsynchronized
function decorators.
v0.6.0 (2014-10-13)
===================
- Raise ``TTLCache.ExpiredError`` for expired ``TTLCache`` items.
- Support unsynchronized function decorators.
- Allow ``@cachedmethod.cache()`` to return ``None``.
v0.5.1 (2014-09-25)
===================
- No formatting of ``KeyError`` arguments.
- Update ``README.rst``.
v0.5.0 (2014-09-23)
===================
- Do not delete expired items in TTLCache.__getitem__().
- Add ``@ttl_cache`` function decorator.
- Fix public ``getsizeof()`` usage.
v0.4.0 (2014-06-16)
===================
- Add ``TTLCache``.
- Add ``Cache`` base class.
- Remove ``@cachedmethod`` ``lock`` parameter.
v0.3.1 (2014-05-07)
===================
- Add proper locking for ``cache_clear()`` and ``cache_info()``.
- Report ``size`` in ``cache_info()``.
v0.3.0 (2014-05-06)
===================
- Remove ``@cache`` decorator.
- Add ``size``, ``getsizeof`` members.
- Add ``@cachedmethod`` decorator.
v0.2.0 (2014-04-02)
===================
- Add ``@cache`` decorator.
- Update documentation.
v0.1.0 (2014-03-27)
===================
- Initial release.