pax_global_header00006660000000000000000000000064126131600160014506gustar00rootroot0000000000000052 comment=42853733d0caf68ef5bf5933a377572b05437e2c cachetools-1.1.5/000077500000000000000000000000001261316001600136365ustar00rootroot00000000000000cachetools-1.1.5/.gitignore000066400000000000000000000004731261316001600156320ustar00rootroot00000000000000*.py[cod] # C extensions *.so # Packages *.egg *.egg-info dist build eggs parts bin var sdist develop-eggs .installed.cfg lib lib64 __pycache__ # Installer logs pip-log.txt # Unit test / coverage reports .coverage .tox nosetests.xml # Translations *.mo # Mr Developer .mr.developer.cfg .project .pydevproject cachetools-1.1.5/.travis.yml000066400000000000000000000003171261316001600157500ustar00rootroot00000000000000sudo: false language: python python: - 2.7 - 3.2 - 3.3 - 3.4 - 3.5-dev install: - pip install . "coverage<4" coveralls flake8 flake8-import-order nose script: - flake8 - nosetests after_success: - coveralls cachetools-1.1.5/CHANGES.rst000066400000000000000000000071051261316001600154430ustar00rootroot00000000000000v1.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-1.1.5/LICENSE000066400000000000000000000020761261316001600146500ustar00rootroot00000000000000The MIT License (MIT) Copyright (c) 2014, 2015 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-1.1.5/MANIFEST.in000066400000000000000000000001511261316001600153710ustar00rootroot00000000000000include CHANGES.rst include LICENSE include MANIFEST.in include README.rst recursive-include tests *.py cachetools-1.1.5/README.rst000066400000000000000000000061001261316001600153220ustar00rootroot00000000000000cachetools ======================================================================== This module provides various memoizing collections and decorators, including variants of the Python 3 Standard Library `@lru_cache`_ function decorator. .. code-block:: pycon >>> from cachetools import LRUCache >>> cache = LRUCache(maxsize=2) >>> cache.update([('first', 1), ('second', 2)]) >>> cache LRUCache([('second', 2), ('first', 1)], maxsize=2, currsize=2) >>> cache['third'] = 3 >>> cache LRUCache([('second', 2), ('third', 3)], maxsize=2, currsize=2) >>> cache['second'] 2 >>> cache['fourth'] = 4 >>> cache LRUCache([('second', 2), ('fourth', 4)], maxsize=2, currsize=2) 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 ------------------------------------------------------------------------ Install cachetools using pip:: pip install cachetools Project Resources ------------------------------------------------------------------------ .. image:: http://img.shields.io/pypi/v/cachetools.svg?style=flat :target: https://pypi.python.org/pypi/cachetools/ :alt: Latest PyPI version .. image:: http://img.shields.io/pypi/dm/cachetools.svg?style=flat :target: https://pypi.python.org/pypi/cachetools/ :alt: Number of PyPI downloads .. image:: http://img.shields.io/travis/tkem/cachetools/master.svg?style=flat :target: https://travis-ci.org/tkem/cachetools/ :alt: Travis CI build status .. image:: http://img.shields.io/coveralls/tkem/cachetools/master.svg?style=flat :target: https://coveralls.io/r/tkem/cachetools :alt: Test coverage - `Documentation`_ - `Issue Tracker`_ - `Source Code`_ - `Change Log`_ License ------------------------------------------------------------------------ Copyright (c) 2014, 2015 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 .. _Documentation: http://pythonhosted.org/cachetools/ .. _Issue Tracker: https://github.com/tkem/cachetools/issues/ .. _Source Code: https://github.com/tkem/cachetools/ .. _Change Log: https://github.com/tkem/cachetools/blob/master/CHANGES.rst .. _MIT License: http://raw.github.com/tkem/cachetools/master/LICENSE cachetools-1.1.5/cachetools/000077500000000000000000000000001261316001600157625ustar00rootroot00000000000000cachetools-1.1.5/cachetools/__init__.py000066400000000000000000000106431261316001600200770ustar00rootroot00000000000000"""Extensible memoizing collections and decorators.""" import functools import warnings from .cache import Cache from .func import lfu_cache, lru_cache, rr_cache, ttl_cache from .keys import hashkey, typedkey from .lfu import LFUCache from .lru import LRUCache from .rr import RRCache from .ttl import TTLCache __all__ = ( 'Cache', 'LFUCache', 'LRUCache', 'RRCache', 'TTLCache', 'cached', 'cachedmethod', 'hashkey', 'typedkey', # make cachetools.func.* available for backwards compatibility 'lfu_cache', 'lru_cache', 'rr_cache', 'ttl_cache', ) __version__ = '1.1.5' _default = [] # evaluates to False if hasattr(functools.update_wrapper(lambda f: f(), lambda: 42), '__wrapped__'): _update_wrapper = functools.update_wrapper else: def _update_wrapper(wrapper, wrapped): functools.update_wrapper(wrapper, wrapped) wrapper.__wrapped__ = wrapped return wrapper 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 _update_wrapper(wrapper, func) return decorator def cachedmethod(cache, key=_default, lock=None, typed=_default): """Decorator to wrap a class or instance method with a memoizing callable that saves results in a cache. """ if key is not _default and not callable(key): key, typed = _default, key if typed is not _default: warnings.warn("Passing 'typed' to cachedmethod() is deprecated, " "use 'key=typedkey' instead", DeprecationWarning, 2) def decorator(method): # pass method to default key function for backwards compatibilty if key is _default: makekey = functools.partial(typedkey if typed else hashkey, method) else: makekey = key # custom key function always receive method args if lock is None: def wrapper(self, *args, **kwargs): c = cache(self) if c is None: return method(self, *args, **kwargs) k = makekey(self, *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 = makekey(self, *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 _update_wrapper(wrapper, method) # deprecated wrapper attribute def getter(self): warnings.warn('%s.cache is deprecated' % method.__name__, DeprecationWarning, 2) return cache(self) wrapper.cache = getter return wrapper return decorator cachetools-1.1.5/cachetools/cache.py000066400000000000000000000060611261316001600174020ustar00rootroot00000000000000import collections class _DefaultSize(object): def __getitem__(self, _): return 1 def __setitem__(self, _, value): assert value == 1 def pop(self, _): return 1 class Cache(collections.MutableMapping): """Mutable mapping to serve as a simple cache or cache base class.""" __size = _DefaultSize() def __init__(self, maxsize, missing=None, getsizeof=None): if missing: self.__missing = missing if getsizeof: self.__getsizeof = getsizeof self.__size = dict() self.__data = dict() self.__currsize = 0 self.__maxsize = maxsize def __repr__(self): return '%s(%r, maxsize=%d, currsize=%d)' % ( self.__class__.__name__, list(self.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): value = self.__missing(key) self.__setitem__(key, value) return value def __iter__(self): return iter(self.__data) def __len__(self): return len(self.__data) @staticmethod def __getsizeof(value): return 1 @staticmethod def __missing(key): raise KeyError(key) @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 def getsizeof(self, value): """Return the size of a cache element's value.""" return self.__getsizeof(value) # collections.MutableMapping mixin methods do not handle __missing__ 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] return value elif default is self.__marker: raise KeyError(key) else: return default def setdefault(self, key, default=None): if key not in self: self[key] = default return self[key] cachetools-1.1.5/cachetools/func.py000066400000000000000000000075131261316001600172750ustar00rootroot00000000000000"""`functools.lru_cache` compatible memoizing function decorators.""" import collections import functools import random import time import warnings try: from threading import RLock except ImportError: from dummy_threading import RLock from .keys import hashkey, typedkey __all__ = ('lfu_cache', 'lru_cache', 'rr_cache', 'ttl_cache') class _NLock: def __enter__(self): pass def __exit__(self, *exc): pass _CacheInfo = collections.namedtuple('CacheInfo', [ 'hits', 'misses', 'maxsize', 'currsize' ]) _marker = object() def _deprecated(message, level=2): warnings.warn('%s is deprecated' % message, DeprecationWarning, level) def _cache(cache, typed=False, context=_marker): def decorator(func): key = typedkey if typed else hashkey if context is _marker: lock = RLock() elif context is None: lock = _NLock() else: lock = context() 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) if not hasattr(wrapper, '__wrapped__'): wrapper.__wrapped__ = func # Python < 3.2 wrapper.cache_info = cache_info wrapper.cache_clear = cache_clear return wrapper return decorator def lfu_cache(maxsize=128, typed=False, getsizeof=None, lock=_marker): """Decorator to wrap a function with a memoizing callable that saves up to `maxsize` results based on a Least Frequently Used (LFU) algorithm. """ from .lfu import LFUCache if lock is not _marker: _deprecated("Passing 'lock' to lfu_cache()", 3) return _cache(LFUCache(maxsize, getsizeof), typed, lock) def lru_cache(maxsize=128, typed=False, getsizeof=None, lock=_marker): """Decorator to wrap a function with a memoizing callable that saves up to `maxsize` results based on a Least Recently Used (LRU) algorithm. """ from .lru import LRUCache if lock is not _marker: _deprecated("Passing 'lock' to lru_cache()", 3) return _cache(LRUCache(maxsize, getsizeof), typed, lock) def rr_cache(maxsize=128, choice=random.choice, typed=False, getsizeof=None, lock=_marker): """Decorator to wrap a function with a memoizing callable that saves up to `maxsize` results based on a Random Replacement (RR) algorithm. """ from .rr import RRCache if lock is not _marker: _deprecated("Passing 'lock' to rr_cache()", 3) return _cache(RRCache(maxsize, choice, getsizeof), typed, lock) def ttl_cache(maxsize=128, ttl=600, timer=time.time, typed=False, getsizeof=None, lock=_marker): """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. """ from .ttl import TTLCache if lock is not _marker: _deprecated("Passing 'lock' to ttl_cache()", 3) return _cache(TTLCache(maxsize, ttl, timer, getsizeof), typed, lock) cachetools-1.1.5/cachetools/keys.py000066400000000000000000000017311261316001600173110ustar00rootroot00000000000000__all__ = ('hashkey', 'typedkey') class _HashedTuple(tuple): __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)) _kwmark = (object(),) 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-1.1.5/cachetools/lfu.py000066400000000000000000000020341261316001600171210ustar00rootroot00000000000000import collections import operator from .cache import Cache class LFUCache(Cache): """Least Frequently Used (LFU) cache implementation.""" def __init__(self, maxsize, missing=None, getsizeof=None): Cache.__init__(self, maxsize, missing, 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 = min(self.__counter.items(), key=operator.itemgetter(1))[0] except ValueError: raise KeyError('cache is empty') return key, self.pop(key) cachetools-1.1.5/cachetools/lru.py000066400000000000000000000052411261316001600171400ustar00rootroot00000000000000from .cache import Cache class _Link(object): __slots__ = 'key', 'prev', 'next' def __getstate__(self): if hasattr(self, 'key'): return (self.key,) else: return None def __setstate__(self, state): self.key, = state def insert(self, next): self.next = next self.prev = prev = next.prev prev.next = next.prev = self def unlink(self): next = self.next prev = self.prev prev.next = next next.prev = prev class LRUCache(Cache): """Least Recently Used (LRU) cache implementation.""" def __init__(self, maxsize, missing=None, getsizeof=None): Cache.__init__(self, maxsize, missing, getsizeof) self.__root = root = _Link() root.prev = root.next = root self.__links = {} def __repr__(self, cache_getitem=Cache.__getitem__): # prevent item reordering return '%s(%r, maxsize=%d, currsize=%d)' % ( self.__class__.__name__, [(key, cache_getitem(self, key)) for key in self], self.maxsize, self.currsize, ) def __getitem__(self, key, cache_getitem=Cache.__getitem__): value = cache_getitem(self, key) link = self.__links[key] link.unlink() link.insert(self.__root) return value def __setitem__(self, key, value, cache_setitem=Cache.__setitem__): cache_setitem(self, key, value) try: link = self.__links[key] except KeyError: link = self.__links[key] = _Link() else: link.unlink() link.key = key link.insert(self.__root) def __delitem__(self, key, cache_delitem=Cache.__delitem__): cache_delitem(self, key) links = self.__links links[key].unlink() del links[key] def __getstate__(self): state = self.__dict__.copy() root = self.__root links = state['__links'] = [root] link = root.next while link is not root: links.append(link) link = link.next return state def __setstate__(self, state): links = state.pop('__links') count = len(links) for index, link in enumerate(links): link.prev = links[index - 1] link.next = links[(index + 1) % count] self.__dict__.update(state) def popitem(self): """Remove and return the `(key, value)` pair least recently used.""" root = self.__root link = root.next if link is root: raise KeyError('%s is empty' % self.__class__.__name__) key = link.key return (key, self.pop(key)) cachetools-1.1.5/cachetools/rr.py000066400000000000000000000012541261316001600167610ustar00rootroot00000000000000import random from .cache import Cache class RRCache(Cache): """Random Replacement (RR) cache implementation.""" def __init__(self, maxsize, choice=random.choice, missing=None, getsizeof=None): Cache.__init__(self, maxsize, missing, getsizeof) self.__choice = choice def popitem(self): """Remove and return a random `(key, value)` pair.""" try: key = self.__choice(list(self)) except IndexError: raise KeyError('cache is empty') return (key, self.pop(key)) @property def choice(self): """The `choice` function used by the cache.""" return self.__choice cachetools-1.1.5/cachetools/ttl.py000066400000000000000000000163611261316001600171460ustar00rootroot00000000000000import functools import time from .cache import Cache class _Link(object): __slots__ = ( 'key', 'expire', 'size', 'ttl_prev', 'ttl_next', 'lru_prev', 'lru_next' ) def __getstate__(self): if hasattr(self, 'key'): return (self.key, self.expire, self.size) else: return None def __setstate__(self, state): self.key, self.expire, self.size = state def insert_lru(self, next): self.lru_next = next self.lru_prev = prev = next.lru_prev prev.lru_next = next.lru_prev = self def insert_ttl(self, next): self.ttl_next = next self.ttl_prev = prev = next.ttl_prev prev.ttl_next = next.ttl_prev = self def insert(self, next): self.insert_lru(next) self.insert_ttl(next) def unlink_lru(self): lru_next = self.lru_next lru_prev = self.lru_prev lru_prev.lru_next = lru_next lru_next.lru_prev = lru_prev def unlink_ttl(self): ttl_next = self.ttl_next ttl_prev = self.ttl_prev ttl_prev.ttl_next = ttl_next ttl_next.ttl_prev = ttl_prev def unlink(self): self.unlink_lru() self.unlink_ttl() class _NestedTimer(object): def __init__(self, timer): self.__timer = timer self.__nesting = 0 def __enter__(self): if self.__nesting == 0: self.__time = self.__timer() self.__nesting += 1 return self.__time def __exit__(self, *exc): self.__nesting -= 1 def __call__(self): if self.__nesting == 0: return self.__timer() else: return self.__time def __getattr__(self, name): return getattr(self.__timer, name) def __getstate__(self): return (self.__timer, self.__nesting) def __setstate__(self, state): self.__timer, self.__nesting = state class TTLCache(Cache): """LRU Cache implementation with per-item time-to-live (TTL) value.""" def __init__(self, maxsize, ttl, timer=time.time, missing=None, getsizeof=None): Cache.__init__(self, maxsize, missing, getsizeof) self.__root = root = _Link() root.ttl_prev = root.ttl_next = root root.lru_prev = root.lru_next = root self.__links = {} self.__timer = _NestedTimer(timer) self.__ttl = ttl def __repr__(self, cache_getitem=Cache.__getitem__): # prevent item reordering/expiration return '%s(%r, maxsize=%d, currsize=%d)' % ( self.__class__.__name__, [(key, cache_getitem(self, key)) for key in self], self.maxsize, self.currsize, ) def __getitem__(self, key, cache_getitem=Cache.__getitem__, cache_missing=Cache.__missing__): with self.__timer as time: value = cache_getitem(self, key) link = self.__links[key] if link.expire < time: return cache_missing(self, key) link.unlink_lru() link.insert_lru(self.__root) return value def __setitem__(self, key, value, cache_setitem=Cache.__setitem__, cache_getsizeof=Cache.getsizeof): with self.__timer as time: self.expire(time) cache_setitem(self, key, value) try: link = self.__links[key] except KeyError: link = self.__links[key] = _Link() else: link.unlink() link.key = key link.expire = time + self.__ttl link.size = cache_getsizeof(self, value) link.insert(self.__root) def __delitem__(self, key, cache_delitem=Cache.__delitem__): with self.__timer as time: self.expire(time) cache_delitem(self, key) links = self.__links links[key].unlink() del links[key] def __contains__(self, key): with self.__timer as time: if key not in self.__links: return False elif self.__links[key].expire < time: return False else: return True def __iter__(self): timer = self.__timer root = self.__root curr = root.ttl_next while curr is not root: with timer as time: if not (curr.expire < time): yield curr.key curr = curr.ttl_next def __len__(self, cache_len=Cache.__len__): root = self.__root head = root.ttl_next expired = 0 with self.__timer as time: while head is not root and head.expire < time: expired += 1 head = head.ttl_next return cache_len(self) - expired def __getstate__(self): state = self.__dict__.copy() root = self.__root links = state['__links'] = [(root, root)] lru, ttl = root.lru_next, root.ttl_next while lru is not root: links.append((lru, ttl)) lru = lru.lru_next ttl = ttl.ttl_next return state def __setstate__(self, state): links = state.pop('__links') count = len(links) for index, (lru, ttl) in enumerate(links): lru.lru_prev, ttl.ttl_prev = links[index - 1] lru.lru_next, ttl.ttl_next = links[(index + 1) % count] self.__dict__.update(state) @property def currsize(self): root = self.__root head = root.ttl_next expired = 0 with self.__timer as time: while head is not root and head.expire < time: expired += head.size head = head.ttl_next return super(TTLCache, self).currsize - expired @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 head = root.ttl_next links = self.__links cache_delitem = Cache.__delitem__ while head is not root and head.expire < time: cache_delitem(self, head.key) del links[head.key] next = head.ttl_next head.unlink() head = next 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) root = self.__root link = root.lru_next if link is root: raise KeyError('%s is empty' % self.__class__.__name__) key = link.key return (key, self.pop(key)) # mixin methods def __nested(method): def wrapper(self, *args, **kwargs): with self.__timer: return method(self, *args, **kwargs) return functools.update_wrapper(wrapper, method) get = __nested(Cache.get) pop = __nested(Cache.pop) setdefault = __nested(Cache.setdefault) cachetools-1.1.5/docs/000077500000000000000000000000001261316001600145665ustar00rootroot00000000000000cachetools-1.1.5/docs/.gitignore000066400000000000000000000000071261316001600165530ustar00rootroot00000000000000_build cachetools-1.1.5/docs/Makefile000066400000000000000000000127141261316001600162330ustar00rootroot00000000000000# 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-1.1.5/docs/conf.py000066400000000000000000000174431261316001600160760ustar00rootroot00000000000000# -*- coding: utf-8 -*- # # cachetools documentation build configuration file, created by # sphinx-quickstart on Mon Feb 10 09:15:34 2014. # # This file is execfile()d with the current directory set to its containing dir. # # Note that not all possible configuration values are present in this # autogenerated file. # # All configuration values have a default; values that are commented out # serve to show the default. import sys import os # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.insert(0, os.path.abspath('.')) sys.path.insert(0, os.path.abspath('..')) from cachetools import __version__ # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. #needs_sphinx = '1.0' # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', 'sphinx.ext.coverage'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. #source_encoding = 'utf-8-sig' # The master toctree document. master_doc = 'index' # General information about the project. project = u'cachetools' copyright = u'2014, 2015 Thomas Kemmer' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the # built documents. # # The short X.Y version. version = __version__ # The full version, including alpha/beta/rc tags. release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. #language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: #today = '' # Else, today_fmt is used as the format for a strftime call. #today_fmt = '%B %d, %Y' # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. #add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). #add_module_names = True # If true, sectionauthor and moduleauthor directives will be shown in the # output. They are ignored by default. #show_authors = False # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] # -- Options for HTML output --------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. html_theme = 'default' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. #html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. #html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". #html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None # The name of an image file (relative to this directory) to place at the top # of the sidebar. #html_logo = None # The name of an image file (within the static path) to use as favicon of the # docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. #html_favicon = None # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". #html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. #html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. #html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. #html_additional_pages = {} # If false, no module index is generated. #html_domain_indices = True # If false, no index is generated. #html_use_index = True # If true, the index is split into individual pages for each letter. #html_split_index = False # If true, links to the reST sources are added to the pages. #html_show_sourcelink = True # If true, "Created using Sphinx" is shown in the HTML footer. Default is True. #html_show_sphinx = True # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. #html_show_copyright = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the # base URL from which the finished HTML is served. #html_use_opensearch = '' # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None # Output file base name for HTML help builder. htmlhelp_basename = 'cachetoolsdoc' # -- Options for LaTeX output -------------------------------------------------- latex_elements = { # The paper size ('letterpaper' or 'a4paper'). #'papersize': 'letterpaper', # The font size ('10pt', '11pt' or '12pt'). #'pointsize': '10pt', # Additional stuff for the LaTeX preamble. #'preamble': '', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('index', 'cachetools.tex', u'cachetools Documentation', u'Thomas Kemmer', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. #latex_use_parts = False # If true, show page references after internal links. #latex_show_pagerefs = False # If true, show URL addresses after external links. #latex_show_urls = False # Documents to append as an appendix to all manuals. #latex_appendices = [] # If false, no module index is generated. #latex_domain_indices = True # -- Options for manual page output -------------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ ('index', 'cachetools', u'cachetools Documentation', [u'Thomas Kemmer'], 1) ] # If true, show URL addresses after external links. #man_show_urls = False # -- Options for Texinfo output ------------------------------------------------ # Grouping the document tree into Texinfo files. List of tuples # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ ('index', 'cachetools', u'cachetools Documentation', u'Thomas Kemmer', 'cachetools', 'One line description of project.', 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. #texinfo_appendices = [] # If false, no module index is generated. #texinfo_domain_indices = True # How to display URL addresses: 'footnote', 'no', or 'inline'. #texinfo_show_urls = 'footnote' cachetools-1.1.5/docs/index.rst000066400000000000000000000422371261316001600164370ustar00rootroot00000000000000:mod:`cachetools` --- Extensible memoizing collections and decorators ======================================================================= .. module:: cachetools This module provides various memoizing collections and decorators, including variants of the Python 3 Standard Library `@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. .. note:: Several features are now marked as deprecated and will be removed in the next major release, :mod:`cachetools` version 2.0. If you happen to rely on any of these features, it is highly recommended to specify your module dependencies accordingly, for example ``cachetools ~= 1.1`` when using :mod:`setuptools`. .. versionchanged:: 1.1 Moved :func:`functools.lru_cache` compatible decorators to the :mod:`cachetools.func` module. For backwards compatibility, they continue to be visible in this module as well. 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:`setitem` calls :meth:`popitem` repeatedly until there is enough room for the item to be added. All cache classes accept an optional `missing` keyword argument in their constructor, which can be used to provide a default *factory function*. If the key `key` is not present, the ``cache[key]`` operation calls :meth:`Cache.__missing__`, which in turn calls `missing` with `key` as its sole argument. The cache will then store the object returned from ``missing(key)`` as the new cache value for `key`, possibly discarding other items if the cache is full. This may be used to provide memoization for existing single-argument functions:: from cachetools import LRUCache import urllib.request 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() cache = LRUCache(maxsize=4, missing=get_pep) for n in 8, 9, 290, 308, 320, 8, 218, 320, 279, 289, 320, 9991: try: print(n, len(cache[n])) except urllib.error.HTTPError: print(n, 'Not Found') print(sorted(cache.keys())) :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. .. autoclass:: Cache :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__`. If a subclass wants to store meta data with its values, i.e. the `value` argument passed to :meth:`Cache.__setitem__` is different from what the derived class's :meth:`__setitem__` received, it will probably need to override :meth:`getsizeof`, too. .. autoclass:: LFUCache :members: This class counts how often an item is retrieved, and discards the items used least often to make space when necessary. .. autoclass:: LRUCache :members: This class discards the least recently used items first to make space when necessary. .. autoclass:: RRCache(maxsize, choice=random.choice, missing=None, 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.time, missing=None, getsizeof=None) :members: :exclude-members: expire This class associates a time-to-live value with each item. Items that expire because they have exceeded their time-to-live will be removed automatically. If no expired items are there to remove, the least recently used items will be discarded first to make space when necessary. Trying to access an expired item will raise a :exc:`KeyError`. By default, the time-to-live is specified in seconds, and the :func:`time.time` function is used to retrieve the current time. A custom `timer` function can be supplied if needed. .. automethod:: expire(self, time=None) Since expired items will be "physically" removed from a cache only at the next mutating operation, e.g. :meth:`__setitem__` or :meth:`__delitem__`, to avoid changing the underlying dictionary while iterating over it, expired items may still claim memory although they are no longer accessible. 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`. 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:: from cachetools import cached @cached(cache={}) def fib(n): return n if n < 2 else fib(n - 1) + fib(n - 2) for i in range(100): print('fib(%d) = %d' % (i, fib(i))) .. decorator:: cached(cache, key=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 functions 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:`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:: from threading import RLock from cachetools import cached, LRUCache cache = LRUCache(maxsize=100) lock = RLock() @cached(cache, lock=lock) def fib(n): return n if n < 2 else fib(n - 1) + fib(n - 2) # 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:: from functools import partial from cachetools import cached, hashkey, LRUCache cache = LRUCache(maxsize=100) @cached(cache, key=partial(hashkey, 'fib')) def fib(n): return n if n < 2 else fib(n - 1) + fib(n - 2) @cached(cache, key=partial(hashkey, 'fac')) def fac(n): return 1 if n == 0 else n * fac(n - 1) print(fib(42)) print(fac(42)) print(cache) .. versionadded:: 1.1 .. decorator:: cachedmethod(cache, key=hashkey, lock=None, typed=False) 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. If `key` or the optional `typed` keyword argument are set to :const:`True`, the :func:`typedkey` function is used for generating hash keys. This has been deprecated in favor of specifying ``key=typedkey`` explicitly. One advantage of :func:`cachedmethod` over the :func:`cached` function decorator is that cache properties such as `maxsize` can be set at runtime:: import operator import urllib.request from cachetools import LRUCache, cachedmethod 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)) For backwards compatibility, the default key function used by :func:`cachedmethod` will generate distinct keys for different methods to ease using a shared cache with multiple methods. This has been deprecated, and relying on this feature is strongly discouraged. When using a shared cache, distinct key functions should be used, as with the :func:`cached` decorator. .. versionadded:: 1.1 The optional `key` and `lock` parameters. .. versionchanged:: 1.1 The :attr:`__wrapped__` attribute is now set when running Python 2.7, too. .. deprecated:: 1.1 The `typed` argument. Use ``key=typedkey`` instead. .. deprecated:: 1.1 When using a shared cached for multiple methods, distinct key function should be used. .. deprecated:: 1.1 The wrapper function's :attr:`cache` attribute. Use the original function passed as the decorator's `cache` argument to access the cache object. Key functions ------------------------------------------------------------------------ The following functions 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. .. versionadded:: 1.1 .. 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. .. versionadded:: 1.1 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(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. Note that unlike :func:`functools.lru_cache`, setting `maxsize` to :const:`None` is not supported. The wrapped function is instrumented with :func:`cache_info` and :func:`cache_clear` functions to provide information about cache performance and clear the cache. See the :func:`functools.lru_cache` documentation for details. In addition to `maxsize`, all decorators accept the following optional keyword arguments: - `typed`, if is set to :const:`True`, will cause function arguments of different types to be cached separately. For example, ``f(3)`` and ``f(3.0)`` will be treated as distinct calls with distinct results. - `getsizeof` specifies a function of one argument that will be applied to each cache value to determine its size. The default value is :const:`None`, which will assign each item an equal size of :const:`1`. This has been deprecated in favor of the new :func:`cachetools.cached` decorator, which allows passing fully customized cache objects. - `lock` specifies a function of zero arguments that returns a `context manager`_ to lock the cache when necessary. If not specified, :class:`threading.RLock` will be used to synchronize access from multiple threads. The use of `lock` is discouraged, and the `lock` argument has been deprecated. .. versionadded:: 1.1 Formerly, the decorators provided by :mod:`cachetools.func` were part of the :mod:`cachetools` module. .. decorator:: lfu_cache(maxsize=128, typed=False, getsizeof=None, lock=threading.RLock) Decorator that wraps a function with a memoizing callable that saves up to `maxsize` results based on a Least Frequently Used (LFU) algorithm. .. deprecated:: 1.1 The `getsizeof` and `lock` arguments. .. decorator:: lru_cache(maxsize=128, typed=False, getsizeof=None, lock=threading.RLock) Decorator that wraps a function with a memoizing callable that saves up to `maxsize` results based on a Least Recently Used (LRU) algorithm. .. deprecated:: 1.1 The `getsizeof` and `lock` arguments. .. decorator:: rr_cache(maxsize=128, choice=random.choice, typed=False, getsizeof=None, lock=threading.RLock) Decorator that wraps a function with a memoizing callable that saves up to `maxsize` results based on a Random Replacement (RR) algorithm. .. deprecated:: 1.1 The `getsizeof` and `lock` arguments. .. decorator:: ttl_cache(maxsize=128, ttl=600, timer=time.time, typed=False, getsizeof=None, lock=threading.RLock) 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. .. deprecated:: 1.1 The `getsizeof` and `lock` arguments. .. _@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-1.1.5/setup.cfg000066400000000000000000000003751261316001600154640ustar00rootroot00000000000000[bdist_wheel] universal = 1 [flake8] exclude = .git,build,docs,setup.py [nosetests] with-coverage = 1 cover-package = cachetools [build_sphinx] source-dir = docs/ build-dir = docs/_build all_files = 1 [upload_sphinx] upload-dir = docs/_build/html cachetools-1.1.5/setup.py000066400000000000000000000025221261316001600153510ustar00rootroot00000000000000import os.path, codecs, re from setuptools import setup with codecs.open(os.path.join(os.path.dirname(__file__), 'cachetools', '__init__.py'), encoding='utf8') as f: metadata = dict(re.findall(r"__([a-z]+)__ = '([^']+)", f.read())) setup( name='cachetools', version=metadata['version'], author='Thomas Kemmer', author_email='tkemmer@computer.org', url='https://github.com/tkem/cachetools', license='MIT', description='Extensible memoizing collections and decorators', long_description=open('README.rst').read(), keywords='cache caching memoize memoizing memoization LRU LFU TTL', 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 :: 2', 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', 'Programming Language :: Python :: 3.2', 'Programming Language :: Python :: 3.3', 'Programming Language :: Python :: 3.4', 'Topic :: Software Development :: Libraries :: Python Modules' ], packages=['cachetools'], test_suite='tests' ) cachetools-1.1.5/tests/000077500000000000000000000000001261316001600150005ustar00rootroot00000000000000cachetools-1.1.5/tests/__init__.py000066400000000000000000000173651261316001600171250ustar00rootroot00000000000000class CacheTestMixin(object): def cache(self, maxsize, missing=None, getsizeof=None): raise NotImplementedError def test_cache_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_cache_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_cache_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_cache_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_cache_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_cache_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_cache_missing(self): cache = self.cache(maxsize=2, missing=lambda x: x) 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_cache_getsizeof(self): cache = self.cache(maxsize=3, getsizeof=lambda x: x) self.assertEqual(3, cache.maxsize) self.assertEqual(0, cache.currsize) 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_cache_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_cache_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-1.1.5/tests/test_cache.py000066400000000000000000000004031261316001600174510ustar00rootroot00000000000000import unittest from cachetools import Cache from . import CacheTestMixin class CacheTest(unittest.TestCase, CacheTestMixin): def cache(self, maxsize, missing=None, getsizeof=None): return Cache(maxsize, missing=missing, getsizeof=getsizeof) cachetools-1.1.5/tests/test_func.py000066400000000000000000000107221261316001600173460ustar00rootroot00000000000000import unittest import warnings 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_nosize(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_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)) def test_decorator_lock(self): class Lock(object): count = 0 def __enter__(self): Lock.count += 1 def __exit__(self, *exc): pass with warnings.catch_warnings(record=True) as w: warnings.simplefilter('always') cached = self.decorator(maxsize=2, lock=Lock)(lambda n: n) self.assertEqual(len(w), 1) self.assertIs(w[0].category, DeprecationWarning) self.assertEqual(cached.cache_info(), (0, 0, 2, 0)) self.assertEqual(Lock.count, 1) self.assertEqual(cached(1), 1) self.assertEqual(Lock.count, 3) self.assertEqual(cached.cache_info(), (0, 1, 2, 1)) self.assertEqual(Lock.count, 4) self.assertEqual(cached(1), 1) self.assertEqual(Lock.count, 5) self.assertEqual(cached.cache_info(), (1, 1, 2, 1)) self.assertEqual(Lock.count, 6) self.assertEqual(cached(1.0), 1.0) self.assertEqual(Lock.count, 7) self.assertEqual(cached.cache_info(), (2, 1, 2, 1)) self.assertEqual(Lock.count, 8) def test_decorator_nolock(self): with warnings.catch_warnings(record=True) as w: warnings.simplefilter('always') cached = self.decorator(maxsize=2, lock=None)(lambda n: n) self.assertEqual(len(w), 1) self.assertIs(w[0].category, DeprecationWarning) 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)) 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-1.1.5/tests/test_keys.py000066400000000000000000000040621261316001600173660ustar00rootroot00000000000000import unittest import cachetools class CacheKeysTest(unittest.TestCase): def test_hashkey(self, key=cachetools.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.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.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())) cachetools-1.1.5/tests/test_lfu.py000066400000000000000000000024401261316001600171770ustar00rootroot00000000000000import unittest from cachetools import LFUCache from . import CacheTestMixin class LFUCacheTest(unittest.TestCase, CacheTestMixin): def cache(self, maxsize, missing=None, getsizeof=None): return LFUCache(maxsize, missing=missing, getsizeof=getsizeof) def test_lfu(self): cache = self.cache(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 = self.cache(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-1.1.5/tests/test_lru.py000066400000000000000000000027151261316001600172200ustar00rootroot00000000000000import unittest from cachetools import LRUCache from . import CacheTestMixin class LRUCacheTest(unittest.TestCase, CacheTestMixin): def cache(self, maxsize, missing=None, getsizeof=None): return LRUCache(maxsize, missing=missing, getsizeof=getsizeof) def test_lru(self): cache = self.cache(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 = self.cache(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-1.1.5/tests/test_method.py000066400000000000000000000144321261316001600176750ustar00rootroot00000000000000import operator import unittest import warnings from cachetools import LRUCache, cachedmethod, typedkey 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=typedkey) def get_typed(self, value): count = self.count self.count += 1 return count 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.cache, cached.get.cache(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.cache, cached.get_typed.cache(cached)) 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.cache, cached.get.cache(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_lru(self): cached = Cached(LRUCache(maxsize=2)) self.assertEqual(cached.cache, cached.get_typed.cache(cached)) 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.cache, cached.get.cache(cached)) 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(None, cached.get.cache(cached)) 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 # 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.cache, cached.get.cache(cached)) self.assertEqual(cached.get(0), 0) 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.cache, cached.get.cache(cached)) 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(None, cached.get.cache(cached)) 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.cache, cached.get.cache(cached)) 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) def test_typed_deprecated(self): with warnings.catch_warnings(record=True) as w: warnings.simplefilter("always") cachedmethod(lambda self: None, None)(lambda self: None) self.assertIs(w[-1].category, DeprecationWarning) with warnings.catch_warnings(record=True) as w: warnings.simplefilter("always") cachedmethod(lambda self: None, False)(lambda self: None) self.assertIs(w[-1].category, DeprecationWarning) with warnings.catch_warnings(record=True) as w: warnings.simplefilter("always") cachedmethod(lambda self: None, True)(lambda self: None) self.assertIs(w[-1].category, DeprecationWarning) with warnings.catch_warnings(record=True) as w: warnings.simplefilter("always") cachedmethod(lambda self: None, typed=None)(lambda self: None) self.assertIs(w[-1].category, DeprecationWarning) cachetools-1.1.5/tests/test_rr.py000066400000000000000000000021161261316001600170340ustar00rootroot00000000000000import random import unittest from cachetools import RRCache from . import CacheTestMixin # random.choice cannot be pickled... def choice(seq): return random.choice(seq) class RRCacheTest(unittest.TestCase, CacheTestMixin): def cache(self, maxsize, choice=choice, missing=None, getsizeof=None): return RRCache(maxsize, choice=choice, missing=missing, getsizeof=getsizeof) def test_choice(self): cache = self.cache(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-1.1.5/tests/test_ttl.py000066400000000000000000000126571261316001600172270ustar00rootroot00000000000000import 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 TTLCacheTest(unittest.TestCase, CacheTestMixin): def cache(self, maxsize, ttl=0, missing=None, getsizeof=None): return TTLCache(maxsize, ttl, timer=Timer(), missing=missing, getsizeof=getsizeof) def test_lru(self): cache = self.cache(maxsize=2) 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(self): cache = self.cache(maxsize=2, ttl=1) 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.currsize) self.assertEqual(1, cache[1]) cache.timer.tick() self.assertEqual({1}, set(cache)) self.assertEqual(1, len(cache)) self.assertEqual(1, cache.currsize) self.assertEqual(1, cache[1]) cache[2] = 2 self.assertEqual({1, 2}, set(cache)) self.assertEqual(2, len(cache)) self.assertEqual(2, cache.currsize) self.assertEqual(1, cache[1]) self.assertEqual(2, cache[2]) cache.timer.tick() self.assertEqual({2}, set(cache)) self.assertEqual(1, len(cache)) self.assertEqual(1, cache.currsize) self.assertNotIn(1, cache) self.assertEqual(2, cache[2]) cache[3] = 3 self.assertEqual({2, 3}, set(cache)) self.assertEqual(2, len(cache)) self.assertEqual(2, cache.currsize) 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.assertEqual(1, cache.currsize) 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.assertEqual(0, cache.currsize) 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) def test_expire(self): cache = self.cache(maxsize=3, ttl=2) 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(3, cache.currsize) 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(3, cache.currsize) 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.assertEqual(2, cache.currsize) 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.assertEqual(1, cache.currsize) 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.assertEqual(0, cache.currsize) self.assertNotIn(1, cache) self.assertNotIn(2, cache) self.assertNotIn(3, cache) def test_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)) def test_tuple_key(self): cache = self.cache(maxsize=1, ttl=0) 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-1.1.5/tests/test_wrapper.py000066400000000000000000000111431261316001600200710ustar00rootroot00000000000000import unittest import cachetools 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.hashkey(0), cache) self.assertNotIn(cachetools.hashkey(1), cache) self.assertNotIn(cachetools.hashkey(1.0), cache) self.assertEqual(wrapper(1), 1) self.assertEqual(len(cache), 2) self.assertIn(cachetools.hashkey(0), cache) self.assertIn(cachetools.hashkey(1), cache) self.assertIn(cachetools.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) def typedkey(*args, **kwargs): key = cachetools.hashkey(*args, **kwargs) key += tuple(type(v) for v in args) key += tuple(type(v) for _, v in sorted(kwargs.items())) return key wrapper = cachetools.cached(cache, key=typedkey)(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(typedkey(0), cache) self.assertNotIn(typedkey(1), cache) self.assertNotIn(typedkey(1.0), cache) self.assertEqual(wrapper(1), 1) self.assertEqual(len(cache), 2) self.assertIn(typedkey(0), cache) self.assertIn(typedkey(1), cache) self.assertNotIn(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(typedkey(0), cache) self.assertIn(typedkey(1), cache) self.assertIn(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')))