# -*- coding: utf-8 -*-
# pylint: disable=not-context-manager
# NOTE: The pylint not-content-manager warning is disabled pending the fix of
# a bug in pylint: https://github.com/PyCQA/pylint/issues/782
"""This module contains the classes underlying SoCo's caching system."""
from __future__ import unicode_literals
import threading
from time import time
from . import config
from .compat import dumps
[docs]class _BaseCache(object):
"""An abstract base class for the cache."""
# pylint: disable=no-self-use, unused-argument
def __init__(self, *args, **kwargs):
super(_BaseCache, self).__init__()
self._cache = {}
#: `bool`: whether the cache is enabled
self.enabled = True
[docs] def put(self, item, *args, **kwargs):
"""Put an item into the cache."""
raise NotImplementedError
[docs] def get(self, *args, **kwargs):
"""Get an item from the cache."""
raise NotImplementedError
[docs] def delete(self, *args, **kwargs):
"""Delete an item from the cache."""
raise NotImplementedError
[docs] def clear(self):
"""Empty the whole cache."""
raise NotImplementedError
[docs]class NullCache(_BaseCache):
"""A cache which does nothing.
Useful for debugging.
"""
[docs] def put(self, item, *args, **kwargs):
"""Put an item into the cache."""
pass
[docs] def get(self, *args, **kwargs):
"""Get an item from the cache."""
return None
[docs] def delete(self, *args, **kwargs):
"""Delete an item from the cache."""
pass
[docs] def clear(self):
"""Empty the whole cache."""
pass
[docs]class TimedCache(_BaseCache):
"""A simple thread-safe cache for caching method return values.
The cache key is generated by from the given ``*args`` and ``**kwargs``.
Items are expired from the cache after a given period of time.
Example:
>>> from time import sleep
>>> cache = TimedCache()
>>> cache.put("item", 'some', kw='args', timeout=3)
>>> # Fetch the item again, by providing the same args and kwargs.
>>> assert cache.get('some', kw='args') == "item"
>>> # Providing different args or kwargs will not return the item.
>>> assert not cache.get('some', 'otherargs') == "item"
>>> # Waiting for less than the provided timeout does not cause the
>>> # item to expire.
>>> sleep(2)
>>> assert cache.get('some', kw='args') == "item"
>>> # But waiting for longer does.
>>> sleep(2)
>>> assert not cache.get('some', kw='args') == "item"
Warning:
At present, the cache can theoretically grow and grow, since entries
are not automatically purged, though in practice this is unlikely
since there are not that many different combinations of arguments in
the places where it is used in SoCo, so not that many different
cache entries will be created. If this becomes a problem,
use a thread and timer to purge the cache, or rewrite this to use
LRU logic!
"""
def __init__(self, default_timeout=0):
"""
Args:
default_timeout (int): The default number of seconds after
which items will be expired.
"""
super(TimedCache, self).__init__()
#: `int`: The default caching expiry interval in seconds.
self.default_timeout = default_timeout
# A thread lock for the cache
self._cache_lock = threading.Lock()
[docs] def get(self, *args, **kwargs):
"""Get an item from the cache for this combination of args and kwargs.
Args:
*args: any arguments.
**kwargs: any keyword arguments.
Returns:
object: The object which has been found in the cache, or `None` if
no unexpired item is found. This means that there is no point
storing an item in the cache if it is `None`.
"""
if not self.enabled:
return None
# Look in the cache to see if there is an unexpired item. If there is
# we can just return the cached result.
cache_key = self.make_key(args, kwargs)
# Lock and load
with self._cache_lock:
if cache_key in self._cache:
expirytime, item = self._cache[cache_key]
if expirytime >= time():
return item
else:
# An expired item is present - delete it
del self._cache[cache_key]
# Nothing found
return None
[docs] def put(self, item, *args, **kwargs):
"""Put an item into the cache, for this combination of args and kwargs.
Args:
*args: any arguments.
**kwargs: any keyword arguments. If ``timeout`` is specified as one
of the keyword arguments, the item will remain available
for retrieval for ``timeout`` seconds. If ``timeout`` is
`None` or not specified, the ``default_timeout`` for this
cache will be used. Specify a ``timeout`` of 0 (or ensure that
the ``default_timeout`` for this cache is 0) if this item is
not to be cached.
"""
if not self.enabled:
return
# Check for a timeout keyword, store and remove it.
timeout = kwargs.pop('timeout', None)
if timeout is None:
timeout = self.default_timeout
cache_key = self.make_key(args, kwargs)
# Store the item, along with the time at which it will expire
with self._cache_lock:
self._cache[cache_key] = (time() + timeout, item)
[docs] def delete(self, *args, **kwargs):
"""Delete an item from the cache for this combination of args and
kwargs."""
cache_key = self.make_key(args, kwargs)
with self._cache_lock:
try:
del self._cache[cache_key]
except KeyError:
pass
[docs] def clear(self):
"""Empty the whole cache."""
with self._cache_lock:
self._cache.clear()
[docs] @staticmethod
def make_key(*args, **kwargs):
"""Generate a unique, hashable, representation of the args and kwargs.
Args:
*args: any arguments.
**kwargs: any keyword arguments.
Returns:
str: the key.
"""
# This is not entirely straightforward, since args and kwargs may
# contain mutable items and unicode. Possibilities include using
# __repr__, frozensets, and code from Py3's LRU cache. But pickle
# works, and although it is not as fast as some methods, it is good
# enough at the moment
cache_key = dumps((args, kwargs))
return cache_key
[docs]class Cache(NullCache):
"""A factory class which returns an instance of a cache subclass.
A `TimedCache` is returned, unless `config.CACHE_ENABLED` is `False`,
in which case a `NullCache` will be returned.
"""
def __new__(cls, *args, **kwargs):
if config.CACHE_ENABLED:
new_cls = TimedCache
else:
new_cls = NullCache
instance = super(Cache, cls).__new__(new_cls)
instance.__init__(*args, **kwargs)
return instance