pax_global_header00006660000000000000000000000064135755074630014531gustar00rootroot0000000000000052 comment=fa9d4760dc44cd77f5eafd30cbaeed40a3435c96 cachetools-4.0.0/000077500000000000000000000000001357550746300136565ustar00rootroot00000000000000cachetools-4.0.0/.gitignore000066400000000000000000000001411357550746300156420ustar00rootroot00000000000000*.egg-info *.pyc *.swp .cache/ .coverage .tox/ MANIFEST build/ dist/ docs/_build/ .pytest_cache/ cachetools-4.0.0/.travis.yml000066400000000000000000000002131357550746300157630ustar00rootroot00000000000000language: python python: - 3.5 - 3.6 - 3.7 - 3.8 - pypy3 install: - pip install coveralls tox script: - tox after_success: - coveralls cachetools-4.0.0/CHANGELOG.rst000066400000000000000000000127011357550746300157000ustar00rootroot00000000000000v4.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`` fuctions. - 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. cachetools-4.0.0/LICENSE000066400000000000000000000020751357550746300146670ustar00rootroot00000000000000The MIT License (MIT) Copyright (c) 2014-2019 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 the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. cachetools-4.0.0/MANIFEST.in000066400000000000000000000002471357550746300154170ustar00rootroot00000000000000include CHANGELOG.rst include LICENSE include MANIFEST.in include README.rst include tox.ini recursive-include docs * prune docs/_build recursive-include tests *.py cachetools-4.0.0/README.rst000066400000000000000000000066601357550746300153550ustar00rootroot00000000000000cachetools ======================================================================== .. image:: http://img.shields.io/pypi/v/cachetools :target: https://pypi.org/project/cachetools/ :alt: Latest PyPI version .. image:: https://img.shields.io/readthedocs/cachetools :target: http://cachetools.readthedocs.io/ :alt: Documentation build status .. image:: http://img.shields.io/travis/tkem/cachetools :target: https://travis-ci.org/tkem/cachetools/ :alt: Travis CI build status .. image:: http://img.shields.io/coveralls/tkem/cachetools :target: https://coveralls.io/r/tkem/cachetools :alt: Test coverage .. image:: https://img.shields.io/github/license/tkem/cachetools :target: http://raw.github.com/tkem/cachetools/master/LICENSE :alt: License This module provides various memoizing collections and decorators, including variants of the Python Standard Library's `@lru_cache`_ function decorator. .. code-block:: python from cachetools import cached, LRUCache, TTLCache # speed up calculating Fibonacci numbers with dynamic programming @cached(cache={}) def fib(n): return n if n < 2 else fib(n - 1) + fib(n - 2) # cache least recently used Python Enhancement Proposals @cached(cache=LRUCache(maxsize=32)) def get_pep(num): url = 'http://www.python.org/dev/peps/pep-%04d/' % num with urllib.request.urlopen(url) as s: return s.read() # cache weather data for no longer than ten minutes @cached(cache=TTLCache(maxsize=1024, ttl=600)) def get_weather(place): return owm.weather_at_place(place).get_weather() For the purpose of this module, a *cache* is a mutable_ mapping_ of a fixed maximum size. When the cache is full, i.e. by adding another item the cache would exceed its maximum size, the cache must choose which item(s) to discard based on a suitable `cache algorithm`_. In general, a cache's size is the total size of its items, and an item's size is a property or function of its value, e.g. the result of ``sys.getsizeof(value)``. For the trivial but common case that each item counts as ``1``, a cache's size is equal to the number of its items, or ``len(cache)``. Multiple cache classes based on different caching algorithms are implemented, and decorators for easily memoizing function and method calls are provided, too. Installation ------------------------------------------------------------------------ cachetools is available from PyPI_ and can be installed by running:: pip install cachetools Project Resources ------------------------------------------------------------------------ - `Documentation`_ - `Issue tracker`_ - `Source code`_ - `Change log`_ License ------------------------------------------------------------------------ Copyright (c) 2014-2019 Thomas Kemmer. Licensed under the `MIT License`_. .. _@lru_cache: http://docs.python.org/3/library/functools.html#functools.lru_cache .. _mutable: http://docs.python.org/dev/glossary.html#term-mutable .. _mapping: http://docs.python.org/dev/glossary.html#term-mapping .. _cache algorithm: http://en.wikipedia.org/wiki/Cache_algorithms .. _PyPI: https://pypi.org/project/cachetools/ .. _Documentation: https://cachetools.readthedocs.io/ .. _Issue tracker: https://github.com/tkem/cachetools/issues/ .. _Source code: https://github.com/tkem/cachetools/ .. _Change log: https://github.com/tkem/cachetools/blob/master/CHANGELOG.rst .. _MIT License: http://raw.github.com/tkem/cachetools/master/LICENSE cachetools-4.0.0/cachetools/000077500000000000000000000000001357550746300160025ustar00rootroot00000000000000cachetools-4.0.0/cachetools/__init__.py000066400000000000000000000005671357550746300201230ustar00rootroot00000000000000"""Extensible memoizing collections and decorators.""" from .cache import Cache from .decorators import cached, cachedmethod from .lfu import LFUCache from .lru import LRUCache from .rr import RRCache from .ttl import TTLCache __all__ = ( 'Cache', 'LFUCache', 'LRUCache', 'RRCache', 'TTLCache', 'cached', 'cachedmethod' ) __version__ = '4.0.0' cachetools-4.0.0/cachetools/abc.py000066400000000000000000000020641357550746300171030ustar00rootroot00000000000000from abc import abstractmethod from collections.abc import MutableMapping class DefaultMapping(MutableMapping): __slots__ = () @abstractmethod def __contains__(self, key): # pragma: nocover return False @abstractmethod def __getitem__(self, key): # pragma: nocover if hasattr(self.__class__, '__missing__'): return self.__class__.__missing__(self, key) else: raise KeyError(key) def get(self, key, default=None): if key in self: return self[key] else: return default __marker = object() def pop(self, key, default=__marker): if key in self: value = self[key] del self[key] elif default is self.__marker: raise KeyError(key) else: value = default return value def setdefault(self, key, default=None): if key in self: value = self[key] else: self[key] = value = default return value DefaultMapping.register(dict) cachetools-4.0.0/cachetools/cache.py000066400000000000000000000043401357550746300174200ustar00rootroot00000000000000from .abc import DefaultMapping class _DefaultSize(object): def __getitem__(self, _): return 1 def __setitem__(self, _, value): assert value == 1 def pop(self, _): return 1 class Cache(DefaultMapping): """Mutable mapping to serve as a simple cache or cache base class.""" __size = _DefaultSize() def __init__(self, maxsize, getsizeof=None): if getsizeof: self.getsizeof = getsizeof if self.getsizeof is not Cache.getsizeof: self.__size = dict() self.__data = dict() self.__currsize = 0 self.__maxsize = maxsize def __repr__(self): return '%s(%r, maxsize=%r, currsize=%r)' % ( self.__class__.__name__, list(self.__data.items()), self.__maxsize, self.__currsize, ) def __getitem__(self, key): try: return self.__data[key] except KeyError: return self.__missing__(key) def __setitem__(self, key, value): maxsize = self.__maxsize size = self.getsizeof(value) if size > maxsize: raise ValueError('value too large') if key not in self.__data or self.__size[key] < size: while self.__currsize + size > maxsize: self.popitem() if key in self.__data: diffsize = size - self.__size[key] else: diffsize = size self.__data[key] = value self.__size[key] = size self.__currsize += diffsize def __delitem__(self, key): size = self.__size.pop(key) del self.__data[key] self.__currsize -= size def __contains__(self, key): return key in self.__data def __missing__(self, key): raise KeyError(key) def __iter__(self): return iter(self.__data) def __len__(self): return len(self.__data) @property def maxsize(self): """The maximum size of the cache.""" return self.__maxsize @property def currsize(self): """The current size of the cache.""" return self.__currsize @staticmethod def getsizeof(value): """Return the size of a cache element's value.""" return 1 cachetools-4.0.0/cachetools/decorators.py000066400000000000000000000054151357550746300205260ustar00rootroot00000000000000import functools from .keys import hashkey def cached(cache, key=hashkey, lock=None): """Decorator to wrap a function with a memoizing callable that saves results in a cache. """ def decorator(func): if cache is None: def wrapper(*args, **kwargs): return func(*args, **kwargs) elif lock is None: def wrapper(*args, **kwargs): k = key(*args, **kwargs) try: return cache[k] except KeyError: pass # key not found v = func(*args, **kwargs) try: cache[k] = v except ValueError: pass # value too large return v else: def wrapper(*args, **kwargs): k = key(*args, **kwargs) try: with lock: return cache[k] except KeyError: pass # key not found v = func(*args, **kwargs) try: with lock: cache[k] = v except ValueError: pass # value too large return v return functools.update_wrapper(wrapper, func) return decorator def cachedmethod(cache, key=hashkey, lock=None): """Decorator to wrap a class or instance method with a memoizing callable that saves results in a cache. """ def decorator(method): if lock is None: def wrapper(self, *args, **kwargs): c = cache(self) if c is None: return method(self, *args, **kwargs) k = key(*args, **kwargs) try: return c[k] except KeyError: pass # key not found v = method(self, *args, **kwargs) try: c[k] = v except ValueError: pass # value too large return v else: def wrapper(self, *args, **kwargs): c = cache(self) if c is None: return method(self, *args, **kwargs) k = key(*args, **kwargs) try: with lock(self): return c[k] except KeyError: pass # key not found v = method(self, *args, **kwargs) try: with lock(self): c[k] = v except ValueError: pass # value too large return v return functools.update_wrapper(wrapper, method) return decorator cachetools-4.0.0/cachetools/func.py000066400000000000000000000066741357550746300173240ustar00rootroot00000000000000"""`functools.lru_cache` compatible memoizing function decorators.""" import collections import functools import random import time try: from threading import RLock except ImportError: # pragma: no cover from dummy_threading import RLock from . import keys from .lfu import LFUCache from .lru import LRUCache from .rr import RRCache from .ttl import TTLCache __all__ = ('lfu_cache', 'lru_cache', 'rr_cache', 'ttl_cache') _CacheInfo = collections.namedtuple('CacheInfo', [ 'hits', 'misses', 'maxsize', 'currsize' ]) class _UnboundCache(dict): maxsize = None @property def currsize(self): return len(self) class _UnboundTTLCache(TTLCache): def __init__(self, ttl, timer): TTLCache.__init__(self, float('inf'), ttl, timer) @property def maxsize(self): return None def _cache(cache, typed=False): def decorator(func): key = keys.typedkey if typed else keys.hashkey lock = RLock() stats = [0, 0] def cache_info(): with lock: hits, misses = stats maxsize = cache.maxsize currsize = cache.currsize return _CacheInfo(hits, misses, maxsize, currsize) def cache_clear(): with lock: try: cache.clear() finally: stats[:] = [0, 0] def wrapper(*args, **kwargs): k = key(*args, **kwargs) with lock: try: v = cache[k] stats[0] += 1 return v except KeyError: stats[1] += 1 v = func(*args, **kwargs) try: with lock: cache[k] = v except ValueError: pass # value too large return v functools.update_wrapper(wrapper, func) wrapper.cache_info = cache_info wrapper.cache_clear = cache_clear return wrapper return decorator def lfu_cache(maxsize=128, typed=False): """Decorator to wrap a function with a memoizing callable that saves up to `maxsize` results based on a Least Frequently Used (LFU) algorithm. """ if maxsize is None: return _cache(_UnboundCache(), typed) else: return _cache(LFUCache(maxsize), typed) def lru_cache(maxsize=128, typed=False): """Decorator to wrap a function with a memoizing callable that saves up to `maxsize` results based on a Least Recently Used (LRU) algorithm. """ if maxsize is None: return _cache(_UnboundCache(), typed) else: return _cache(LRUCache(maxsize), typed) def rr_cache(maxsize=128, choice=random.choice, typed=False): """Decorator to wrap a function with a memoizing callable that saves up to `maxsize` results based on a Random Replacement (RR) algorithm. """ if maxsize is None: return _cache(_UnboundCache(), typed) else: return _cache(RRCache(maxsize, choice), typed) def 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) algorithm with a per-item time-to-live (TTL) value. """ if maxsize is None: return _cache(_UnboundTTLCache(ttl, timer), typed) else: return _cache(TTLCache(maxsize, ttl, timer), typed) cachetools-4.0.0/cachetools/keys.py000066400000000000000000000026721357550746300173360ustar00rootroot00000000000000"""Key functions for memoizing decorators.""" __all__ = ('hashkey', 'typedkey') class _HashedTuple(tuple): """A tuple that ensures that hash() will be called no more than once per element, since cache decorators will hash the key multiple times on a cache miss. See also _HashedSeq in the standard library functools implementation. """ __hashvalue = None def __hash__(self, hash=tuple.__hash__): hashvalue = self.__hashvalue if hashvalue is None: self.__hashvalue = hashvalue = hash(self) return hashvalue def __add__(self, other, add=tuple.__add__): return _HashedTuple(add(self, other)) def __radd__(self, other, add=tuple.__add__): return _HashedTuple(add(other, self)) def __getstate__(self): return {} # used for separating keyword arguments; we do not use an object # instance here so identity is preserved when pickling/unpickling _kwmark = (_HashedTuple,) def hashkey(*args, **kwargs): """Return a cache key for the specified hashable arguments.""" if kwargs: return _HashedTuple(args + sum(sorted(kwargs.items()), _kwmark)) else: return _HashedTuple(args) def typedkey(*args, **kwargs): """Return a typed cache key for the specified hashable arguments.""" key = hashkey(*args, **kwargs) key += tuple(type(v) for v in args) key += tuple(type(v) for _, v in sorted(kwargs.items())) return key cachetools-4.0.0/cachetools/lfu.py000066400000000000000000000020111357550746300171340ustar00rootroot00000000000000import collections from .cache import Cache class LFUCache(Cache): """Least Frequently Used (LFU) cache implementation.""" def __init__(self, maxsize, getsizeof=None): Cache.__init__(self, maxsize, getsizeof) self.__counter = collections.Counter() def __getitem__(self, key, cache_getitem=Cache.__getitem__): value = cache_getitem(self, key) self.__counter[key] -= 1 return value def __setitem__(self, key, value, cache_setitem=Cache.__setitem__): cache_setitem(self, key, value) self.__counter[key] -= 1 def __delitem__(self, key, cache_delitem=Cache.__delitem__): cache_delitem(self, key) del self.__counter[key] def popitem(self): """Remove and return the `(key, value)` pair least frequently used.""" try: (key, _), = self.__counter.most_common(1) except ValueError: raise KeyError('%s is empty' % self.__class__.__name__) else: return (key, self.pop(key)) cachetools-4.0.0/cachetools/lru.py000066400000000000000000000022041357550746300171540ustar00rootroot00000000000000import collections from .cache import Cache class LRUCache(Cache): """Least Recently Used (LRU) cache implementation.""" def __init__(self, maxsize, getsizeof=None): Cache.__init__(self, maxsize, getsizeof) self.__order = collections.OrderedDict() def __getitem__(self, key, cache_getitem=Cache.__getitem__): value = cache_getitem(self, key) self.__update(key) return value def __setitem__(self, key, value, cache_setitem=Cache.__setitem__): cache_setitem(self, key, value) self.__update(key) def __delitem__(self, key, cache_delitem=Cache.__delitem__): cache_delitem(self, key) del self.__order[key] def popitem(self): """Remove and return the `(key, value)` pair least recently used.""" try: key = next(iter(self.__order)) except StopIteration: raise KeyError('%s is empty' % self.__class__.__name__) else: return (key, self.pop(key)) def __update(self, key): try: self.__order.move_to_end(key) except KeyError: self.__order[key] = None cachetools-4.0.0/cachetools/rr.py000066400000000000000000000016561357550746300170070ustar00rootroot00000000000000import random from .cache import Cache # random.choice cannot be pickled in Python 2.7 def _choice(seq): return random.choice(seq) class RRCache(Cache): """Random Replacement (RR) cache implementation.""" def __init__(self, maxsize, choice=random.choice, getsizeof=None): Cache.__init__(self, maxsize, getsizeof) # TODO: use None as default, assing to self.choice directly? if choice is random.choice: self.__choice = _choice else: self.__choice = choice @property def choice(self): """The `choice` function used by the cache.""" return self.__choice def popitem(self): """Remove and return a random `(key, value)` pair.""" try: key = self.__choice(list(self)) except IndexError: raise KeyError('%s is empty' % self.__class__.__name__) else: return (key, self.pop(key)) cachetools-4.0.0/cachetools/ttl.py000066400000000000000000000132421357550746300171610ustar00rootroot00000000000000import collections import time from .cache import Cache class _Link(object): __slots__ = ('key', 'expire', 'next', 'prev') def __init__(self, key=None, expire=None): self.key = key self.expire = expire def __reduce__(self): return _Link, (self.key, self.expire) def unlink(self): next = self.next prev = self.prev prev.next = next next.prev = prev class _Timer(object): def __init__(self, timer): self.__timer = timer self.__nesting = 0 def __call__(self): if self.__nesting == 0: return self.__timer() else: return self.__time def __enter__(self): if self.__nesting == 0: self.__time = time = self.__timer() else: time = self.__time self.__nesting += 1 return time def __exit__(self, *exc): self.__nesting -= 1 def __reduce__(self): return _Timer, (self.__timer,) def __getattr__(self, name): return getattr(self.__timer, name) class TTLCache(Cache): """LRU Cache implementation with per-item time-to-live (TTL) value.""" def __init__(self, maxsize, ttl, timer=time.monotonic, getsizeof=None): Cache.__init__(self, maxsize, getsizeof) self.__root = root = _Link() root.prev = root.next = root self.__links = collections.OrderedDict() self.__timer = _Timer(timer) self.__ttl = ttl def __contains__(self, key): try: link = self.__links[key] # no reordering except KeyError: return False else: return not (link.expire < self.__timer()) def __getitem__(self, key, cache_getitem=Cache.__getitem__): try: link = self.__getlink(key) except KeyError: expired = False else: expired = link.expire < self.__timer() if expired: return self.__missing__(key) else: return cache_getitem(self, key) def __setitem__(self, key, value, cache_setitem=Cache.__setitem__): with self.__timer as time: self.expire(time) cache_setitem(self, key, value) try: link = self.__getlink(key) except KeyError: self.__links[key] = link = _Link(key) else: link.unlink() link.expire = time + self.__ttl link.next = root = self.__root link.prev = prev = root.prev prev.next = root.prev = link def __delitem__(self, key, cache_delitem=Cache.__delitem__): cache_delitem(self, key) link = self.__links.pop(key) link.unlink() if link.expire < self.__timer(): raise KeyError(key) def __iter__(self): root = self.__root curr = root.next while curr is not root: # "freeze" time for iterator access with self.__timer as time: if not (curr.expire < time): yield curr.key curr = curr.next def __len__(self): root = self.__root curr = root.next time = self.__timer() count = len(self.__links) while curr is not root and curr.expire < time: count -= 1 curr = curr.next return count def __setstate__(self, state): self.__dict__.update(state) root = self.__root root.prev = root.next = root for link in sorted(self.__links.values(), key=lambda obj: obj.expire): link.next = root link.prev = prev = root.prev prev.next = root.prev = link self.expire(self.__timer()) def __repr__(self, cache_repr=Cache.__repr__): with self.__timer as time: self.expire(time) return cache_repr(self) @property def currsize(self): with self.__timer as time: self.expire(time) return super(TTLCache, self).currsize @property def timer(self): """The timer function used by the cache.""" return self.__timer @property def ttl(self): """The time-to-live value of the cache's items.""" return self.__ttl def expire(self, time=None): """Remove expired items from the cache.""" if time is None: time = self.__timer() root = self.__root curr = root.next links = self.__links cache_delitem = Cache.__delitem__ while curr is not root and curr.expire < time: cache_delitem(self, curr.key) del links[curr.key] next = curr.next curr.unlink() curr = next def clear(self): with self.__timer as time: self.expire(time) Cache.clear(self) def get(self, *args, **kwargs): with self.__timer: return Cache.get(self, *args, **kwargs) def pop(self, *args, **kwargs): with self.__timer: return Cache.pop(self, *args, **kwargs) def setdefault(self, *args, **kwargs): with self.__timer: return Cache.setdefault(self, *args, **kwargs) def popitem(self): """Remove and return the `(key, value)` pair least recently used that has not already expired. """ with self.__timer as time: self.expire(time) try: key = next(iter(self.__links)) except StopIteration: raise KeyError('%s is empty' % self.__class__.__name__) else: return (key, self.pop(key)) def __getlink(self, key): value = self.__links[key] self.__links.move_to_end(key) return value cachetools-4.0.0/docs/000077500000000000000000000000001357550746300146065ustar00rootroot00000000000000cachetools-4.0.0/docs/.gitignore000066400000000000000000000000071357550746300165730ustar00rootroot00000000000000_build cachetools-4.0.0/docs/Makefile000066400000000000000000000127141357550746300162530ustar00rootroot00000000000000# Makefile for Sphinx documentation # # You can set these variables from the command line. SPHINXOPTS = SPHINXBUILD = sphinx-build PAPER = BUILDDIR = _build # Internal variables. PAPEROPT_a4 = -D latex_paper_size=a4 PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . .PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" @echo " dirhtml to make HTML files named index.html in directories" @echo " singlehtml to make a single large HTML file" @echo " pickle to make pickle files" @echo " json to make JSON files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" @echo " text to make text files" @echo " man to make manual pages" @echo " texinfo to make Texinfo files" @echo " info to make Texinfo files and run them through makeinfo" @echo " gettext to make PO message catalogs" @echo " changes to make an overview of all changed/added/deprecated items" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: -rm -rf $(BUILDDIR)/* html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @echo "Build finished; now you can run "qcollectiongenerator" with the" \ ".qhcp project file in $(BUILDDIR)/qthelp, like this:" @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/cachetools.qhcp" @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cachetools.qhc" devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @echo "Build finished." @echo "To view the help file:" @echo "# mkdir -p $$HOME/.local/share/devhelp/cachetools" @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/cachetools" @echo "# devhelp" epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." texinfo: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." info: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." gettext: $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." cachetools-4.0.0/docs/conf.py000066400000000000000000000010671357550746300161110ustar00rootroot00000000000000def get_version(): import configparser import pathlib cp = configparser.ConfigParser() # Python 3.5 ConfigParser does not accept Path as filename cp.read(str(pathlib.Path(__file__).parent.parent / "setup.cfg")) return cp["metadata"]["version"] project = 'cachetools' copyright = '2014-2019 Thomas Kemmer' version = get_version() release = version extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.doctest', 'sphinx.ext.todo' ] exclude_patterns = ['_build'] master_doc = 'index' html_theme = 'default' cachetools-4.0.0/docs/index.rst000066400000000000000000000416541357550746300164610ustar00rootroot00000000000000********************************************************************* :mod:`cachetools` --- Extensible memoizing collections and decorators ********************************************************************* .. module:: cachetools This module provides various memoizing collections and decorators, including variants of the Python Standard Library's `@lru_cache`_ function decorator. For the purpose of this module, a *cache* is a mutable_ mapping_ of a fixed maximum size. When the cache is full, i.e. by adding another item the cache would exceed its maximum size, the cache must choose which item(s) to discard based on a suitable `cache algorithm`_. In general, a cache's size is the total size of its items, and an item's size is a property or function of its value, e.g. the result of ``sys.getsizeof(value)``. For the trivial but common case that each item counts as :const:`1`, a cache's size is equal to the number of its items, or ``len(cache)``. Multiple cache classes based on different caching algorithms are implemented, and decorators for easily memoizing function and method calls are provided, too. .. testsetup:: * import operator from cachetools import cached, cachedmethod, LRUCache from unittest import mock urllib = mock.MagicMock() 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.MutableMapping`, and provide :attr:`maxsize` and :attr:`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. :class:`Cache` also features a :meth:`getsizeof` method, which returns the size of a given `value`. The default implementation of :meth:`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 function of one argument used to retrieve the size of an item's value. .. note:: Please be aware that all these classes are *not* thread-safe. Access to a shared cache from multiple threads must be properly synchronized, e.g. by using one of the memoizing decorators with a suitable `lock` object. .. autoclass:: Cache(maxsize, getsizeof=None) :members: This class discards arbitrary items using :meth:`popitem` to make space when necessary. Derived classes may override :meth:`popitem` to implement specific caching strategies. If a subclass has to keep track of item access, insertion or deletion, it may additionally need to override :meth:`__getitem__`, :meth:`__setitem__` and :meth:`__delitem__`. .. autoclass:: LFUCache(maxsize, getsizeof=None) :members: This class counts how often an item is retrieved, and discards the items used least often to make space when necessary. .. autoclass:: LRUCache(maxsize, getsizeof=None) :members: This class discards the least recently used items first to make space when necessary. .. autoclass:: RRCache(maxsize, choice=random.choice, getsizeof=None) :members: This class randomly selects candidate items and discards them to make space when necessary. By default, items are selected from the list of cache keys using :func:`random.choice`. The optional argument `choice` may specify an alternative function that returns an arbitrary element from a non-empty sequence. .. autoclass:: TTLCache(maxsize, ttl, timer=time.monotonic, getsizeof=None) :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 expired items are there to remove, the least recently used items will be discarded first to make space when necessary. By default, the time-to-live is specified in seconds and :func:`time.monotonic` is used to retrieve the current time. A custom `timer` function can be supplied if needed. .. 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`. 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: .. doctest:: :pyversion: >= 3 >>> class MyCache(LRUCache): ... def popitem(self): ... key, value = super().popitem() ... print('Key "%s" evicted with value "%s"' % (key, value)) ... return key, value >>> c = MyCache(maxsize=2) >>> c['a'] = 1 >>> c['b'] = 2 >>> c['c'] = 3 Key "a" evicted with value "1" Similar to the standard library's :class:`collections.defaultdict`, subclasses of :class:`Cache` may implement a :meth:`__missing__` method which is called by :meth:`Cache.__getitem__` if the requested key is not found: .. doctest:: :pyversion: >= 3 >>> class PepStore(LRUCache): ... def __missing__(self, key): ... """Retrieve text of a Python Enhancement Proposal""" ... url = 'http://www.python.org/dev/peps/pep-%04d/' % key ... try: ... with urllib.request.urlopen(url) as s: ... pep = s.read() ... self[key] = pep # store text in cache ... return pep ... except urllib.error.HTTPError: ... return 'Not Found' # do not store in cache >>> peps = PepStore(maxsize=4) >>> for n in 8, 9, 290, 308, 320, 8, 218, 320, 279, 289, 320: ... pep = peps[n] >>> print(sorted(peps.keys())) [218, 279, 289, 320] Note, though, that such a class does not really behave like a *cache* any more, and will lead to surprising results when used with any of the memoizing decorators described below. However, it may be useful in its own right. Memoizing decorators ==================== The :mod:`cachetools` module provides decorators for memoizing function and method calls. This can save time when a function is often called with the same arguments: .. doctest:: >>> @cached(cache={}) ... def fib(n): ... 'Compute the nth number in the Fibonacci sequence' ... return n if n < 2 else fib(n - 1) + fib(n - 2) >>> fib(42) 267914296 .. decorator:: cached(cache, key=cachetools.keys.hashkey, lock=None) Decorator to wrap a function with a memoizing callable that saves results in a cache. The `cache` argument specifies a cache object to store previous function arguments and return values. Note that `cache` need not be an instance of the cache implementations provided by the :mod:`cachetools` module. :func:`cached` will work with any mutable mapping type, including plain :class:`dict` and :class:`weakref.WeakValueDictionary`. `key` specifies a function that will be called with the same positional and keyword arguments as the wrapped function itself, and which has to return a suitable cache key. Since caches are mappings, the object returned by `key` must be hashable. The default is to call :func:`cachetools.keys.hashkey`. If `lock` is not :const:`None`, it must specify an object implementing the `context manager`_ protocol. Any access to the cache will then be nested in a ``with lock:`` statement. This can be used for synchronizing thread access to the cache by providing a :class:`threading.RLock` instance, for example. .. note:: The `lock` context manager is used only to guard access to the cache object. The underlying wrapped function will be called outside the `with` statement, and must be thread-safe by itself. The original underlying function is accessible through the :attr:`__wrapped__` attribute of the memoizing wrapper function. This can be used for introspection or for bypassing the cache. To perform operations on the cache object, for example to clear the cache during runtime, the cache should be assigned to a variable. When a `lock` object is used, any access to the cache from outside the function wrapper should also be performed within an appropriate `with` statement: .. testcode:: from threading import RLock cache = LRUCache(maxsize=32) lock = RLock() @cached(cache, lock=lock) def get_pep(num): 'Retrieve text of a Python Enhancement Proposal' url = 'http://www.python.org/dev/peps/pep-%04d/' % num with urllib.request.urlopen(url) as s: return s.read() # make sure access to cache is synchronized with lock: cache.clear() It is also possible to use a single shared cache object with multiple functions. However, care must be taken that different cache keys are generated for each function, even for identical function arguments: .. doctest:: :options: +ELLIPSIS >>> from cachetools.keys import hashkey >>> from functools import partial >>> # shared cache for integer sequences >>> numcache = {} >>> # compute Fibonacci numbers >>> @cached(numcache, key=partial(hashkey, 'fib')) ... def fib(n): ... 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) >>> fib(42) 267914296 >>> luc(42) 599074578 >>> list(sorted(numcache.items())) [..., (('fib', 42), 267914296), ..., (('luc', 42), 599074578)] .. decorator:: cachedmethod(cache, key=cachetools.keys.hashkey, lock=None) Decorator to wrap a class or instance method with a memoizing callable that saves results in a (possibly shared) cache. The main difference between this and the :func:`cached` function decorator is that `cache` and `lock` are not passed objects, but functions. Both will be called with :const:`self` (or :const:`cls` for class methods) as their sole argument to retrieve the cache or lock object for the method's respective instance or class. .. note:: As with :func:`cached`, the context manager obtained by calling ``lock(self)`` will only guard access to the cache itself. It is the user's responsibility to handle concurrent calls to the underlying wrapped method in a multithreaded environment. One advantage of :func:`cachedmethod` over the :func:`cached` function decorator is that cache properties such as `maxsize` can be set at runtime: .. testcode:: class CachedPEPs(object): def __init__(self, cachesize): self.cache = LRUCache(maxsize=cachesize) @cachedmethod(operator.attrgetter('cache')) def get(self, num): """Retrieve text of a Python Enhancement Proposal""" url = 'http://www.python.org/dev/peps/pep-%04d/' % num with urllib.request.urlopen(url) as s: return s.read() peps = CachedPEPs(cachesize=10) print("PEP #1: %s" % peps.get(1)) .. testoutput:: :hide: :options: +ELLIPSIS PEP #1: ... When using a shared cache for multiple methods, be aware that different cache keys must be created for each method even when function arguments are the same, just as with the `@cached` decorator: .. testcode:: class CachedReferences(object): def __init__(self, cachesize): self.cache = LRUCache(maxsize=cachesize) @cachedmethod(lambda self: self.cache, key=partial(hashkey, 'pep')) def get_pep(self, num): """Retrieve text of a Python Enhancement Proposal""" url = 'http://www.python.org/dev/peps/pep-%04d/' % num with urllib.request.urlopen(url) as s: return s.read() @cachedmethod(lambda self: self.cache, key=partial(hashkey, 'rfc')) def get_rfc(self, num): """Retrieve text of an IETF Request for Comments""" url = 'https://tools.ietf.org/rfc/rfc%d.txt' % num with urllib.request.urlopen(url) as s: return s.read() docs = CachedReferences(cachesize=100) print("PEP #1: %s" % docs.get_pep(1)) print("RFC #1: %s" % docs.get_rfc(1)) .. testoutput:: :hide: :options: +ELLIPSIS PEP #1: ... RFC #1: ... ***************************************************************** :mod:`cachetools.keys` --- Key functions for memoizing decorators ***************************************************************** .. module:: cachetools.keys This module provides several functions that can be used as key functions with the :func:`cached` and :func:`cachedmethod` decorators: .. autofunction:: hashkey This function returns a :class:`tuple` instance suitable as a cache key, provided the positional and keywords arguments are hashable. .. autofunction:: typedkey This function is similar to :func:`hashkey`, but arguments of different types will yield distinct cache keys. For example, ``typedkey(3)`` and ``typedkey(3.0)`` will return different results. 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:: @cached(LRUCache(maxsize=128)) def foo(x, y, z, env={}): pass However, if `env` always holds only hashable values itself, a custom key function can be written that handles the `env` keyword argument specially:: def envkey(*args, env={}, **kwargs): key = hashkey(*args, **kwargs) key += tuple(sorted(env.items())) return key The :func:`envkey` function can then be used in decorator declarations like this:: @cached(LRUCache(maxsize=128), key=envkey) **************************************************************************** :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 caching strategy is effectively disabled and the cache can grow without bound. If the optional argument `typed` is set to :const:`True`, function arguments of different types will be cached separately. For example, ``f(3)`` and ``f(3.0)`` will be treated as distinct calls with distinct results. The wrapped function is instrumented with :func:`cache_info` and :func:`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. .. decorator:: lfu_cache(maxsize=128, typed=False) Decorator that wraps a function with a memoizing callable that saves up to `maxsize` results based on a Least Frequently Used (LFU) algorithm. .. decorator:: lru_cache(maxsize=128, typed=False) Decorator that wraps a function with a memoizing callable that saves up to `maxsize` results based on a Least Recently Used (LRU) algorithm. .. decorator:: rr_cache(maxsize=128, choice=random.choice, typed=False) Decorator that wraps a function with a memoizing callable that saves up to `maxsize` results based on a Random Replacement (RR) algorithm. .. decorator:: 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) algorithm with a per-item time-to-live (TTL) value. .. _@lru_cache: http://docs.python.org/3/library/functools.html#functools.lru_cache .. _cache algorithm: http://en.wikipedia.org/wiki/Cache_algorithms .. _context manager: http://docs.python.org/dev/glossary.html#term-context-manager .. _mapping: http://docs.python.org/dev/glossary.html#term-mapping .. _mutable: http://docs.python.org/dev/glossary.html#term-mutable cachetools-4.0.0/setup.cfg000066400000000000000000000017761357550746300155120ustar00rootroot00000000000000[metadata] name = cachetools version = 4.0.0 url = https://github.com/tkem/cachetools/ author = Thomas Kemmer author_email = tkemmer@computer.org license = MIT license_file = LICENSE description = Extensible memoizing collections and decorators long_description = file: README.rst classifiers = Development Status :: 5 - Production/Stable Environment :: Other Environment Intended Audience :: Developers License :: OSI Approved :: MIT License Operating System :: OS Independent Programming Language :: Python Programming Language :: Python :: 3 Programming Language :: Python :: 3.5 Programming Language :: Python :: 3.6 Programming Language :: Python :: 3.7 Programming Language :: Python :: 3.8 Topic :: Software Development :: Libraries :: Python Modules [options] packages = find: python_requires = ~= 3.5 [options.packages.find] exclude = tests tests.* [flake8] exclude = .git, .tox [build_sphinx] source-dir = docs/ build-dir = docs/_build all_files = 1 cachetools-4.0.0/setup.py000066400000000000000000000000461357550746300153700ustar00rootroot00000000000000from setuptools import setup setup() cachetools-4.0.0/tests/000077500000000000000000000000001357550746300150205ustar00rootroot00000000000000cachetools-4.0.0/tests/__init__.py000066400000000000000000000213041357550746300171310ustar00rootroot00000000000000class CacheTestMixin(object): Cache = None def test_defaults(self): cache = self.Cache(maxsize=1) self.assertEqual(0, len(cache)) self.assertEqual(1, cache.maxsize) self.assertEqual(0, cache.currsize) self.assertEqual(1, cache.getsizeof(None)) self.assertEqual(1, cache.getsizeof('')) self.assertEqual(1, cache.getsizeof(0)) self.assertTrue(repr(cache).startswith(cache.__class__.__name__)) def test_insert(self): cache = self.Cache(maxsize=2) cache.update({1: 1, 2: 2}) self.assertEqual(2, len(cache)) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) cache[3] = 3 self.assertEqual(2, len(cache)) self.assertEqual(3, cache[3]) self.assertTrue(1 in cache or 2 in cache) cache[4] = 4 self.assertEqual(2, len(cache)) self.assertEqual(4, cache[4]) self.assertTrue(1 in cache or 2 in cache or 3 in cache) def test_update(self): cache = self.Cache(maxsize=2) cache.update({1: 1, 2: 2}) self.assertEqual(2, len(cache)) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) cache.update({1: 1, 2: 2}) self.assertEqual(2, len(cache)) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) cache.update({1: 'a', 2: 'b'}) self.assertEqual(2, len(cache)) self.assertEqual('a', cache[1]) self.assertEqual('b', cache[2]) def test_delete(self): cache = self.Cache(maxsize=2) cache.update({1: 1, 2: 2}) self.assertEqual(2, len(cache)) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) del cache[2] self.assertEqual(1, len(cache)) self.assertEqual(1, cache[1]) self.assertNotIn(2, cache) del cache[1] self.assertEqual(0, len(cache)) self.assertNotIn(1, cache) self.assertNotIn(2, cache) with self.assertRaises(KeyError): del cache[1] self.assertEqual(0, len(cache)) self.assertNotIn(1, cache) self.assertNotIn(2, cache) def test_pop(self): cache = self.Cache(maxsize=2) cache.update({1: 1, 2: 2}) self.assertEqual(2, cache.pop(2)) self.assertEqual(1, len(cache)) self.assertEqual(1, cache.pop(1)) self.assertEqual(0, len(cache)) with self.assertRaises(KeyError): cache.pop(2) with self.assertRaises(KeyError): cache.pop(1) with self.assertRaises(KeyError): cache.pop(0) self.assertEqual(None, cache.pop(2, None)) self.assertEqual(None, cache.pop(1, None)) self.assertEqual(None, cache.pop(0, None)) def test_popitem(self): cache = self.Cache(maxsize=2) cache.update({1: 1, 2: 2}) self.assertIn(cache.pop(1), {1: 1, 2: 2}) self.assertEqual(1, len(cache)) self.assertIn(cache.pop(2), {1: 1, 2: 2}) self.assertEqual(0, len(cache)) with self.assertRaises(KeyError): cache.popitem() def _test_missing(self, cache): self.assertEqual(0, cache.currsize) self.assertEqual(2, cache.maxsize) self.assertEqual(0, len(cache)) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) self.assertEqual(2, len(cache)) self.assertTrue(1 in cache and 2 in cache) self.assertEqual(3, cache[3]) self.assertEqual(2, len(cache)) self.assertTrue(3 in cache) self.assertTrue(1 in cache or 2 in cache) self.assertTrue(1 not in cache or 2 not in cache) self.assertEqual(4, cache[4]) self.assertEqual(2, len(cache)) self.assertTrue(4 in cache) self.assertTrue(1 in cache or 2 in cache or 3 in cache) # verify __missing__() is *not* called for any operations # besides __getitem__() self.assertEqual(4, cache.get(4)) self.assertEqual(None, cache.get(5)) self.assertEqual(5 * 5, cache.get(5, 5 * 5)) self.assertEqual(2, len(cache)) self.assertEqual(4, cache.pop(4)) with self.assertRaises(KeyError): cache.pop(5) self.assertEqual(None, cache.pop(5, None)) self.assertEqual(5 * 5, cache.pop(5, 5 * 5)) self.assertEqual(1, len(cache)) cache.clear() cache[1] = 1 + 1 self.assertEqual(1 + 1, cache.setdefault(1)) self.assertEqual(1 + 1, cache.setdefault(1, 1)) self.assertEqual(1 + 1, cache[1]) self.assertEqual(2 + 2, cache.setdefault(2, 2 + 2)) self.assertEqual(2 + 2, cache.setdefault(2, None)) self.assertEqual(2 + 2, cache.setdefault(2)) self.assertEqual(2 + 2, cache[2]) self.assertEqual(2, len(cache)) self.assertTrue(1 in cache and 2 in cache) self.assertEqual(None, cache.setdefault(3)) self.assertEqual(2, len(cache)) self.assertTrue(3 in cache) self.assertTrue(1 in cache or 2 in cache) self.assertTrue(1 not in cache or 2 not in cache) def _test_missing_getsizeof(self, cache): self.assertEqual(0, cache.currsize) self.assertEqual(2, cache.maxsize) self.assertEqual(1, cache[1]) self.assertIn(1, cache) self.assertEqual(2, cache[2]) self.assertNotIn(1, cache) self.assertIn(2, cache) self.assertEqual(3, cache[3]) self.assertNotIn(1, cache) self.assertIn(2, cache) self.assertNotIn(3, cache) def test_missing_subclass(self): class Cache(self.Cache): def __missing__(self, key): try: self[key] = key except ValueError: pass return key self._test_missing(Cache(maxsize=2)) self._test_missing_getsizeof(Cache(maxsize=2, getsizeof=lambda x: x)) def _test_getsizeof(self, cache): self.assertEqual(0, cache.currsize) self.assertEqual(3, cache.maxsize) self.assertEqual(1, cache.getsizeof(1)) self.assertEqual(2, cache.getsizeof(2)) self.assertEqual(3, cache.getsizeof(3)) cache.update({1: 1, 2: 2}) self.assertEqual(2, len(cache)) self.assertEqual(3, cache.currsize) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) cache[1] = 2 self.assertEqual(1, len(cache)) self.assertEqual(2, cache.currsize) self.assertEqual(2, cache[1]) self.assertNotIn(2, cache) cache.update({1: 1, 2: 2}) self.assertEqual(2, len(cache)) self.assertEqual(3, cache.currsize) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) cache[3] = 3 self.assertEqual(1, len(cache)) self.assertEqual(3, cache.currsize) self.assertEqual(3, cache[3]) self.assertNotIn(1, cache) self.assertNotIn(2, cache) with self.assertRaises(ValueError): cache[3] = 4 self.assertEqual(1, len(cache)) self.assertEqual(3, cache.currsize) self.assertEqual(3, cache[3]) with self.assertRaises(ValueError): cache[4] = 4 self.assertEqual(1, len(cache)) self.assertEqual(3, cache.currsize) self.assertEqual(3, cache[3]) def test_getsizeof_param(self): self._test_getsizeof(self.Cache(maxsize=3, getsizeof=lambda x: x)) def test_getsizeof_subclass(self): class Cache(self.Cache): def getsizeof(self, value): return value self._test_getsizeof(Cache(maxsize=3)) def test_pickle(self): import pickle source = self.Cache(maxsize=2) source.update({1: 1, 2: 2}) cache = pickle.loads(pickle.dumps(source)) self.assertEqual(source, cache) self.assertEqual(2, len(cache)) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) cache[3] = 3 self.assertEqual(2, len(cache)) self.assertEqual(3, cache[3]) self.assertTrue(1 in cache or 2 in cache) cache[4] = 4 self.assertEqual(2, len(cache)) self.assertEqual(4, cache[4]) self.assertTrue(1 in cache or 2 in cache or 3 in cache) self.assertEqual(cache, pickle.loads(pickle.dumps(cache))) def test_pickle_maxsize(self): import pickle import sys # test empty cache, single element, large cache (recursion limit) for n in [0, 1, sys.getrecursionlimit() * 2]: source = self.Cache(maxsize=n) source.update((i, i) for i in range(n)) cache = pickle.loads(pickle.dumps(source)) self.assertEqual(n, len(cache)) self.assertEqual(source, cache) cachetools-4.0.0/tests/test_cache.py000066400000000000000000000002251357550746300174730ustar00rootroot00000000000000import unittest import cachetools from . import CacheTestMixin class CacheTest(unittest.TestCase, CacheTestMixin): Cache = cachetools.Cache cachetools-4.0.0/tests/test_func.py000066400000000000000000000062441357550746300173720ustar00rootroot00000000000000import unittest import cachetools.func class DecoratorTestMixin(object): def decorator(self, maxsize, typed=False, lock=None): raise NotImplementedError def test_decorator(self): cached = self.decorator(maxsize=2)(lambda n: n) self.assertEqual(cached.cache_info(), (0, 0, 2, 0)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (0, 1, 2, 1)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (1, 1, 2, 1)) self.assertEqual(cached(1.0), 1.0) self.assertEqual(cached.cache_info(), (2, 1, 2, 1)) def test_decorator_clear(self): cached = self.decorator(maxsize=2)(lambda n: n) self.assertEqual(cached.cache_info(), (0, 0, 2, 0)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (0, 1, 2, 1)) cached.cache_clear() self.assertEqual(cached.cache_info(), (0, 0, 2, 0)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (0, 1, 2, 1)) def test_decorator_nocache(self): cached = self.decorator(maxsize=0)(lambda n: n) self.assertEqual(cached.cache_info(), (0, 0, 0, 0)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (0, 1, 0, 0)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (0, 2, 0, 0)) self.assertEqual(cached(1.0), 1.0) self.assertEqual(cached.cache_info(), (0, 3, 0, 0)) def test_decorator_unbound(self): cached = self.decorator(maxsize=None)(lambda n: n) self.assertEqual(cached.cache_info(), (0, 0, None, 0)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (0, 1, None, 1)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (1, 1, None, 1)) self.assertEqual(cached(1.0), 1.0) self.assertEqual(cached.cache_info(), (2, 1, None, 1)) def test_decorator_typed(self): cached = self.decorator(maxsize=2, typed=True)(lambda n: n) self.assertEqual(cached.cache_info(), (0, 0, 2, 0)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (0, 1, 2, 1)) self.assertEqual(cached(1), 1) self.assertEqual(cached.cache_info(), (1, 1, 2, 1)) self.assertEqual(cached(1.0), 1.0) self.assertEqual(cached.cache_info(), (1, 2, 2, 2)) self.assertEqual(cached(1.0), 1.0) self.assertEqual(cached.cache_info(), (2, 2, 2, 2)) class LFUDecoratorTest(unittest.TestCase, DecoratorTestMixin): def decorator(self, maxsize, **kwargs): return cachetools.func.lfu_cache(maxsize, **kwargs) class LRUDecoratorTest(unittest.TestCase, DecoratorTestMixin): def decorator(self, maxsize, **kwargs): return cachetools.func.lru_cache(maxsize, **kwargs) class RRDecoratorTest(unittest.TestCase, DecoratorTestMixin): def decorator(self, maxsize, **kwargs): return cachetools.func.rr_cache(maxsize, **kwargs) class TTLDecoratorTest(unittest.TestCase, DecoratorTestMixin): def decorator(self, maxsize, **kwargs): return cachetools.func.ttl_cache(maxsize, **kwargs) cachetools-4.0.0/tests/test_keys.py000066400000000000000000000051451357550746300174110ustar00rootroot00000000000000import unittest import cachetools.keys class CacheKeysTest(unittest.TestCase): def test_hashkey(self, key=cachetools.keys.hashkey): self.assertEqual(key(), key()) self.assertEqual(hash(key()), hash(key())) self.assertEqual(key(1, 2, 3), key(1, 2, 3)) self.assertEqual(hash(key(1, 2, 3)), hash(key(1, 2, 3))) self.assertEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=0)) self.assertEqual(hash(key(1, 2, 3, x=0)), hash(key(1, 2, 3, x=0))) self.assertNotEqual(key(1, 2, 3), key(3, 2, 1)) self.assertNotEqual(key(1, 2, 3), key(1, 2, 3, x=None)) self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=None)) self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, y=0)) with self.assertRaises(TypeError): hash(key({})) # untyped keys compare equal self.assertEqual(key(1, 2, 3), key(1.0, 2.0, 3.0)) self.assertEqual(hash(key(1, 2, 3)), hash(key(1.0, 2.0, 3.0))) def test_typedkey(self, key=cachetools.keys.typedkey): self.assertEqual(key(), key()) self.assertEqual(hash(key()), hash(key())) self.assertEqual(key(1, 2, 3), key(1, 2, 3)) self.assertEqual(hash(key(1, 2, 3)), hash(key(1, 2, 3))) self.assertEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=0)) self.assertEqual(hash(key(1, 2, 3, x=0)), hash(key(1, 2, 3, x=0))) self.assertNotEqual(key(1, 2, 3), key(3, 2, 1)) self.assertNotEqual(key(1, 2, 3), key(1, 2, 3, x=None)) self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, x=None)) self.assertNotEqual(key(1, 2, 3, x=0), key(1, 2, 3, y=0)) with self.assertRaises(TypeError): hash(key({})) # typed keys compare unequal self.assertNotEqual(key(1, 2, 3), key(1.0, 2.0, 3.0)) def test_addkeys(self, key=cachetools.keys.hashkey): self.assertIsInstance(key(), tuple) self.assertIsInstance(key(1, 2, 3) + key(4, 5, 6), type(key())) self.assertIsInstance(key(1, 2, 3) + (4, 5, 6), type(key())) self.assertIsInstance((1, 2, 3) + key(4, 5, 6), type(key())) def test_pickle(self, key=cachetools.keys.hashkey): import pickle for k in [key(), key('abc'), key('abc', 123), key('abc', q='abc')]: # white-box test: assert cached hash value is not pickled self.assertEqual(len(k.__dict__), 0) h = hash(k) self.assertEqual(len(k.__dict__), 1) pickled = pickle.loads(pickle.dumps(k)) self.assertEqual(len(pickled.__dict__), 0) self.assertEqual(k, pickled) self.assertEqual(h, hash(pickled)) cachetools-4.0.0/tests/test_lfu.py000066400000000000000000000022561357550746300172240ustar00rootroot00000000000000import unittest from cachetools import LFUCache from . import CacheTestMixin class LFUCacheTest(unittest.TestCase, CacheTestMixin): Cache = LFUCache def test_lfu(self): cache = LFUCache(maxsize=2) cache[1] = 1 cache[1] cache[2] = 2 cache[3] = 3 self.assertEqual(len(cache), 2) self.assertEqual(cache[1], 1) self.assertTrue(2 in cache or 3 in cache) self.assertTrue(2 not in cache or 3 not in cache) cache[4] = 4 self.assertEqual(len(cache), 2) self.assertEqual(cache[4], 4) self.assertEqual(cache[1], 1) def test_lfu_getsizeof(self): cache = LFUCache(maxsize=3, getsizeof=lambda x: x) cache[1] = 1 cache[2] = 2 self.assertEqual(len(cache), 2) self.assertEqual(cache[1], 1) self.assertEqual(cache[2], 2) cache[3] = 3 self.assertEqual(len(cache), 1) self.assertEqual(cache[3], 3) self.assertNotIn(1, cache) self.assertNotIn(2, cache) with self.assertRaises(ValueError): cache[4] = 4 self.assertEqual(len(cache), 1) self.assertEqual(cache[3], 3) cachetools-4.0.0/tests/test_lru.py000066400000000000000000000025331357550746300172360ustar00rootroot00000000000000import unittest from cachetools import LRUCache from . import CacheTestMixin class LRUCacheTest(unittest.TestCase, CacheTestMixin): Cache = LRUCache def test_lru(self): cache = LRUCache(maxsize=2) cache[1] = 1 cache[2] = 2 cache[3] = 3 self.assertEqual(len(cache), 2) self.assertEqual(cache[2], 2) self.assertEqual(cache[3], 3) self.assertNotIn(1, cache) cache[2] cache[4] = 4 self.assertEqual(len(cache), 2) self.assertEqual(cache[2], 2) self.assertEqual(cache[4], 4) self.assertNotIn(3, cache) cache[5] = 5 self.assertEqual(len(cache), 2) self.assertEqual(cache[4], 4) self.assertEqual(cache[5], 5) self.assertNotIn(2, cache) def test_lru_getsizeof(self): cache = LRUCache(maxsize=3, getsizeof=lambda x: x) cache[1] = 1 cache[2] = 2 self.assertEqual(len(cache), 2) self.assertEqual(cache[1], 1) self.assertEqual(cache[2], 2) cache[3] = 3 self.assertEqual(len(cache), 1) self.assertEqual(cache[3], 3) self.assertNotIn(1, cache) self.assertNotIn(2, cache) with self.assertRaises(ValueError): cache[4] = 4 self.assertEqual(len(cache), 1) self.assertEqual(cache[3], 3) cachetools-4.0.0/tests/test_method.py000066400000000000000000000115331357550746300177140ustar00rootroot00000000000000import operator import unittest from cachetools import LRUCache, cachedmethod, keys class Cached(object): def __init__(self, cache, count=0): self.cache = cache self.count = count @cachedmethod(operator.attrgetter('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): count = self.count self.count += 1 return count # https://github.com/tkem/cachetools/issues/107 def __hash__(self): raise TypeError('unhashable type') class Locked(object): def __init__(self, cache): self.cache = cache self.count = 0 @cachedmethod(operator.attrgetter('cache'), lock=lambda self: self) def get(self, value): return self.count def __enter__(self): self.count += 1 def __exit__(self, *exc): pass class CachedMethodTest(unittest.TestCase): def test_dict(self): cached = Cached({}) self.assertEqual(cached.get(0), 0) self.assertEqual(cached.get(1), 1) self.assertEqual(cached.get(1), 1) self.assertEqual(cached.get(1.0), 1) self.assertEqual(cached.get(1.0), 1) cached.cache.clear() self.assertEqual(cached.get(1), 2) def test_typed_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) def test_lru(self): cached = Cached(LRUCache(maxsize=2)) self.assertEqual(cached.get(0), 0) self.assertEqual(cached.get(1), 1) self.assertEqual(cached.get(1), 1) self.assertEqual(cached.get(1.0), 1) self.assertEqual(cached.get(1.0), 1) cached.cache.clear() self.assertEqual(cached.get(1), 2) def test_typed_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) def test_nospace(self): cached = Cached(LRUCache(maxsize=0)) self.assertEqual(cached.get(0), 0) self.assertEqual(cached.get(1), 1) self.assertEqual(cached.get(1), 2) self.assertEqual(cached.get(1.0), 3) self.assertEqual(cached.get(1.0), 4) def test_nocache(self): cached = Cached(None) self.assertEqual(cached.get(0), 0) self.assertEqual(cached.get(1), 1) self.assertEqual(cached.get(1), 2) self.assertEqual(cached.get(1.0), 3) self.assertEqual(cached.get(1.0), 4) def test_weakref(self): import weakref import fractions import gc # in Python 3.4, `int` does not support weak references even # when subclassed, but Fraction apparently does... class Int(fractions.Fraction): def __add__(self, other): return Int(fractions.Fraction.__add__(self, other)) cached = Cached(weakref.WeakValueDictionary(), count=Int(0)) self.assertEqual(cached.get(0), 0) gc.collect() self.assertEqual(cached.get(0), 1) ref = cached.get(1) self.assertEqual(ref, 2) self.assertEqual(cached.get(1), 2) self.assertEqual(cached.get(1.0), 2) ref = cached.get_typed(1) self.assertEqual(ref, 3) self.assertEqual(cached.get_typed(1), 3) self.assertEqual(cached.get_typed(1.0), 4) cached.cache.clear() self.assertEqual(cached.get(1), 5) def test_locked_dict(self): cached = Locked({}) self.assertEqual(cached.get(0), 1) self.assertEqual(cached.get(1), 3) self.assertEqual(cached.get(1), 3) self.assertEqual(cached.get(1.0), 3) self.assertEqual(cached.get(2.0), 7) def test_locked_nocache(self): cached = Locked(None) self.assertEqual(cached.get(0), 0) self.assertEqual(cached.get(1), 0) self.assertEqual(cached.get(1), 0) self.assertEqual(cached.get(1.0), 0) self.assertEqual(cached.get(1.0), 0) def test_locked_nospace(self): cached = Locked(LRUCache(maxsize=0)) self.assertEqual(cached.get(0), 1) self.assertEqual(cached.get(1), 3) self.assertEqual(cached.get(1), 5) self.assertEqual(cached.get(1.0), 7) self.assertEqual(cached.get(1.0), 9) cachetools-4.0.0/tests/test_rr.py000066400000000000000000000015001357550746300170500ustar00rootroot00000000000000import unittest from cachetools import RRCache from . import CacheTestMixin class RRCacheTest(unittest.TestCase, CacheTestMixin): Cache = RRCache def test_rr(self): cache = RRCache(maxsize=2, choice=min) self.assertEqual(min, cache.choice) cache[1] = 1 cache[2] = 2 cache[3] = 3 self.assertEqual(2, len(cache)) self.assertEqual(2, cache[2]) self.assertEqual(3, cache[3]) self.assertNotIn(1, cache) cache[0] = 0 self.assertEqual(2, len(cache)) self.assertEqual(0, cache[0]) self.assertEqual(3, cache[3]) self.assertNotIn(2, cache) cache[4] = 4 self.assertEqual(2, len(cache)) self.assertEqual(3, cache[3]) self.assertEqual(4, cache[4]) self.assertNotIn(0, cache) cachetools-4.0.0/tests/test_ttl.py000066400000000000000000000122001357550746300172270ustar00rootroot00000000000000import unittest from cachetools import TTLCache from . import CacheTestMixin class Timer: def __init__(self, auto=False): self.auto = auto self.time = 0 def __call__(self): if self.auto: self.time += 1 return self.time def tick(self): self.time += 1 class TTLTestCache(TTLCache): def __init__(self, maxsize, ttl=0, **kwargs): TTLCache.__init__(self, maxsize, ttl=ttl, timer=Timer(), **kwargs) class TTLCacheTest(unittest.TestCase, CacheTestMixin): Cache = TTLTestCache def test_ttl(self): cache = TTLCache(maxsize=2, ttl=1, timer=Timer()) self.assertEqual(0, cache.timer()) self.assertEqual(1, cache.ttl) cache[1] = 1 self.assertEqual({1}, set(cache)) self.assertEqual(1, len(cache)) self.assertEqual(1, cache[1]) cache.timer.tick() self.assertEqual({1}, set(cache)) self.assertEqual(1, len(cache)) self.assertEqual(1, cache[1]) cache[2] = 2 self.assertEqual({1, 2}, set(cache)) self.assertEqual(2, len(cache)) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) cache.timer.tick() self.assertEqual({2}, set(cache)) self.assertEqual(1, len(cache)) self.assertNotIn(1, cache) self.assertEqual(2, cache[2]) cache[3] = 3 self.assertEqual({2, 3}, set(cache)) self.assertEqual(2, len(cache)) self.assertNotIn(1, cache) self.assertEqual(2, cache[2]) self.assertEqual(3, cache[3]) cache.timer.tick() self.assertEqual({3}, set(cache)) self.assertEqual(1, len(cache)) self.assertNotIn(1, cache) self.assertNotIn(2, cache) self.assertEqual(3, cache[3]) cache.timer.tick() self.assertEqual(set(), set(cache)) self.assertEqual(0, len(cache)) self.assertNotIn(1, cache) self.assertNotIn(2, cache) self.assertNotIn(3, cache) with self.assertRaises(KeyError): del cache[1] with self.assertRaises(KeyError): cache.pop(2) with self.assertRaises(KeyError): del cache[3] def test_ttl_lru(self): cache = TTLCache(maxsize=2, ttl=0, timer=Timer()) cache[1] = 1 cache[2] = 2 cache[3] = 3 self.assertEqual(len(cache), 2) self.assertNotIn(1, cache) self.assertEqual(cache[2], 2) self.assertEqual(cache[3], 3) cache[2] cache[4] = 4 self.assertEqual(len(cache), 2) self.assertNotIn(1, cache) self.assertEqual(cache[2], 2) self.assertNotIn(3, cache) self.assertEqual(cache[4], 4) cache[5] = 5 self.assertEqual(len(cache), 2) self.assertNotIn(1, cache) self.assertNotIn(2, cache) self.assertNotIn(3, cache) self.assertEqual(cache[4], 4) self.assertEqual(cache[5], 5) def test_ttl_expire(self): cache = TTLCache(maxsize=3, ttl=2, timer=Timer()) with cache.timer as time: self.assertEqual(time, cache.timer()) self.assertEqual(2, cache.ttl) cache[1] = 1 cache.timer.tick() cache[2] = 2 cache.timer.tick() cache[3] = 3 self.assertEqual(2, cache.timer()) self.assertEqual({1, 2, 3}, set(cache)) self.assertEqual(3, len(cache)) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) self.assertEqual(3, cache[3]) cache.expire() self.assertEqual({1, 2, 3}, set(cache)) self.assertEqual(3, len(cache)) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) self.assertEqual(3, cache[3]) cache.expire(3) self.assertEqual({2, 3}, set(cache)) self.assertEqual(2, len(cache)) self.assertNotIn(1, cache) self.assertEqual(2, cache[2]) self.assertEqual(3, cache[3]) cache.expire(4) self.assertEqual({3}, set(cache)) self.assertEqual(1, len(cache)) self.assertNotIn(1, cache) self.assertNotIn(2, cache) self.assertEqual(3, cache[3]) cache.expire(5) self.assertEqual(set(), set(cache)) self.assertEqual(0, len(cache)) self.assertNotIn(1, cache) self.assertNotIn(2, cache) self.assertNotIn(3, cache) def test_ttl_atomic(self): cache = TTLCache(maxsize=1, ttl=1, timer=Timer(auto=True)) cache[1] = 1 self.assertEqual(1, cache[1]) cache[1] = 1 self.assertEqual(1, cache.get(1)) cache[1] = 1 self.assertEqual(1, cache.pop(1)) cache[1] = 1 self.assertEqual(1, cache.setdefault(1)) cache[1] = 1 cache.clear() self.assertEqual(0, len(cache)) def test_ttl_tuple_key(self): cache = TTLCache(maxsize=1, ttl=0, timer=Timer()) self.assertEqual(0, cache.ttl) cache[(1, 2, 3)] = 42 self.assertEqual(42, cache[(1, 2, 3)]) cache.timer.tick() with self.assertRaises(KeyError): cache[(1, 2, 3)] self.assertNotIn((1, 2, 3), cache) cachetools-4.0.0/tests/test_wrapper.py000066400000000000000000000111401357550746300201060ustar00rootroot00000000000000import unittest import cachetools import cachetools.keys class DecoratorTestMixin(object): def cache(self, minsize): raise NotImplementedError def func(self, *args, **kwargs): if hasattr(self, 'count'): self.count += 1 else: self.count = 0 return self.count def test_decorator(self): cache = self.cache(2) wrapper = cachetools.cached(cache)(self.func) self.assertEqual(len(cache), 0) self.assertEqual(wrapper.__wrapped__, self.func) self.assertEqual(wrapper(0), 0) self.assertEqual(len(cache), 1) self.assertIn(cachetools.keys.hashkey(0), cache) self.assertNotIn(cachetools.keys.hashkey(1), cache) self.assertNotIn(cachetools.keys.hashkey(1.0), cache) self.assertEqual(wrapper(1), 1) self.assertEqual(len(cache), 2) self.assertIn(cachetools.keys.hashkey(0), cache) self.assertIn(cachetools.keys.hashkey(1), cache) self.assertIn(cachetools.keys.hashkey(1.0), cache) self.assertEqual(wrapper(1), 1) self.assertEqual(len(cache), 2) self.assertEqual(wrapper(1.0), 1) self.assertEqual(len(cache), 2) self.assertEqual(wrapper(1.0), 1) self.assertEqual(len(cache), 2) def test_decorator_typed(self): cache = self.cache(3) key = cachetools.keys.typedkey wrapper = cachetools.cached(cache, key=key)(self.func) self.assertEqual(len(cache), 0) self.assertEqual(wrapper.__wrapped__, self.func) self.assertEqual(wrapper(0), 0) self.assertEqual(len(cache), 1) self.assertIn(cachetools.keys.typedkey(0), cache) self.assertNotIn(cachetools.keys.typedkey(1), cache) self.assertNotIn(cachetools.keys.typedkey(1.0), cache) self.assertEqual(wrapper(1), 1) self.assertEqual(len(cache), 2) self.assertIn(cachetools.keys.typedkey(0), cache) self.assertIn(cachetools.keys.typedkey(1), cache) self.assertNotIn(cachetools.keys.typedkey(1.0), cache) self.assertEqual(wrapper(1), 1) self.assertEqual(len(cache), 2) self.assertEqual(wrapper(1.0), 2) self.assertEqual(len(cache), 3) self.assertIn(cachetools.keys.typedkey(0), cache) self.assertIn(cachetools.keys.typedkey(1), cache) self.assertIn(cachetools.keys.typedkey(1.0), cache) self.assertEqual(wrapper(1.0), 2) self.assertEqual(len(cache), 3) def test_decorator_lock(self): class Lock(object): count = 0 def __enter__(self): Lock.count += 1 def __exit__(self, *exc): pass cache = self.cache(2) wrapper = cachetools.cached(cache, lock=Lock())(self.func) self.assertEqual(len(cache), 0) self.assertEqual(wrapper.__wrapped__, self.func) self.assertEqual(wrapper(0), 0) self.assertEqual(Lock.count, 2) self.assertEqual(wrapper(1), 1) self.assertEqual(Lock.count, 4) self.assertEqual(wrapper(1), 1) self.assertEqual(Lock.count, 5) class CacheWrapperTest(unittest.TestCase, DecoratorTestMixin): def cache(self, minsize): return cachetools.Cache(maxsize=minsize) def test_zero_size_cache_decorator(self): cache = self.cache(0) wrapper = cachetools.cached(cache)(self.func) self.assertEqual(len(cache), 0) self.assertEqual(wrapper.__wrapped__, self.func) self.assertEqual(wrapper(0), 0) self.assertEqual(len(cache), 0) def test_zero_size_cache_decorator_lock(self): class Lock(object): count = 0 def __enter__(self): Lock.count += 1 def __exit__(self, *exc): pass cache = self.cache(0) wrapper = cachetools.cached(cache, lock=Lock())(self.func) self.assertEqual(len(cache), 0) self.assertEqual(wrapper.__wrapped__, self.func) self.assertEqual(wrapper(0), 0) self.assertEqual(len(cache), 0) self.assertEqual(Lock.count, 2) class DictWrapperTest(unittest.TestCase, DecoratorTestMixin): def cache(self, minsize): return dict() class NoneWrapperTest(unittest.TestCase): def func(self, *args, **kwargs): return args + tuple(kwargs.items()) def test_decorator(self): wrapper = cachetools.cached(None)(self.func) self.assertEqual(wrapper.__wrapped__, self.func) self.assertEqual(wrapper(0), (0,)) self.assertEqual(wrapper(1), (1,)) self.assertEqual(wrapper(1, foo='bar'), (1, ('foo', 'bar'))) cachetools-4.0.0/tox.ini000066400000000000000000000011771357550746300151770ustar00rootroot00000000000000[tox] envlist = check-manifest,docs,doctest,flake8,py [testenv] deps = coverage pytest pytest-cov commands = py.test --basetemp={envtmpdir} --cov=cachetools {posargs} [testenv:check-manifest] deps = check-manifest commands = check-manifest skip_install = true [testenv:docs] deps = sphinx commands = sphinx-build -W -b html -d {envtmpdir}/doctrees docs {envtmpdir}/html [testenv:doctest] deps = sphinx commands = sphinx-build -W -b doctest -d {envtmpdir}/doctrees docs {envtmpdir}/doctest [testenv:flake8] deps = flake8 flake8-import-order commands = flake8 skip_install = true