implemented LRU and LFU policies.

Author: bofm

README.rst

@@ -28,8 +28,9 @@ Usage
     def long_running_function(a, b, *args, c=None, **kwargs):
         pass
 
-    # Memory-based cache with limited ttl and maxsize
-    @Cache(ttl=60, maxsize=128)
+    # Memory-based cache with limited ttl and maxsize and "least recently used"
+    # cache replacement policy.
+    @Cache(ttl=60, maxsize=128, policy='LRU')
     def long_running_function(a, b, *args, c=None, **kwargs):
         pass
 
@@ -115,9 +116,9 @@ Features
 -  [x] TTL and maxsize.
 -  [x] Works with ``*args``, ``**kwargs``.
 -  [x] Works with mutable function arguments of the following types: ``dict``, ``list``, ``set``.
--  [ ] LRS (least recently stored), LRU and LFU cache.
--  [ ] Multiprocessing- and thread-safe.
+-  [x] FIFO, LRU and LFU cache replacement policies.
 -  [x] Customizable cache key function.
+-  [ ] Multiprocessing- and thread-safe.
 -  [ ] Pluggable external caching backends (see Redis example).
 
 .. |Build Status| image:: https://travis-ci.org/bofm/python-caching.svg?branch=master

caching/__init__.py

@@ -1,5 +1,7 @@
-from .cache import Cache, cache, make_key
+from .cache import Cache
 from .storage import CacheStorageBase, SQLiteStorage
 
 
-__version__ = '0.1.dev3'
+__version__ = '0.1.dev4'
+
+__all__ = (Cache, CacheStorageBase, SQLiteStorage)

caching/cache.py

@@ -1,6 +1,7 @@
 import pickle
 from collections import OrderedDict
 from functools import wraps
+from typing import Union, Callable
 
 from .storage import SQLiteStorage
 
@@ -30,20 +31,41 @@ def _function_name(fn):
 
 
 class Cache:
+    """Cache.
+
+    Can be used as a function decorator and as a dict-like key-value store.
+    """
 
     def __init__(
         self,
         *,
-        maxsize=1024,
-        ttl=-1,
-        filepath=None,
-        key=make_key,
+        maxsize: int=1024,
+        ttl: Union[float, int]=-1,
+        filepath: Union[str, None]=None,
+        policy: str='FIFO',
+        key: Callable=make_key,
         **kwargs
     ):
+        """
+        Args:
+            maxsize: maximum number of keys in cache.
+            ttl: amount of time in seconds since the item is added to cache
+                before the item is deleted from cache.
+            filepath: if a string is passed then file path where the cache
+                is stored on disk. If `None` is passed then the cache is stored
+                in memory.
+            policy: one of: FIFO, LRU, LFU.
+                Cache replacement (or eviction) policy.
+            key: a function which takes the arguments and keyword arguments of
+                the decorated by the `Cache` instance function and retuns
+                something which will be used as a key under which the function's
+                return value will be stored in cache.
+        """
         self.params = OrderedDict(
             maxsize=maxsize,
             ttl=ttl,
             filepath=filepath,
+            policy=policy,
             key=key,
             **kwargs
         )
@@ -52,6 +74,7 @@ def __init__(
             filepath=filepath or ':memory:',
             ttl=ttl,
             maxsize=maxsize,
+            policy=policy,
         )
 
     def __repr__(self):
@@ -135,6 +158,3 @@ def __exit__(self, exc_type, exc_val, exc_tb):
 
     def remove(self):
         self.storage.remove()
-
-
-cache = Cache()

caching/storage.py

@@ -1,16 +1,17 @@
 import os
 import sqlite3
 from contextlib import suppress
-from typing import Generator, Tuple, Union
+from typing import Generator, Tuple, Union, ByteString
 
 
 class CacheStorageBase:
 
-    def __init__(self, *, maxsize, ttl):
+    def __init__(self, *, maxsize: int, ttl: Union[int, float], policy: str):
         self.maxsize = maxsize
         self.ttl = ttl
+        self.policy = policy
 
-    def __setitem__(self, key, value) -> None:
+    def __setitem__(self, key: ByteString, value: ByteString) -> None:
         raise NotImplementedError  # pragma: no cover
 
     def __getitem__(self, key) -> bytes:
@@ -19,7 +20,7 @@ def __getitem__(self, key) -> bytes:
     def __delitem__(self, key) -> None:
         raise NotImplementedError  # pragma: no cover
 
-    def get(self, key, default=None) -> Union[bytes, None]:
+    def get(self, key: ByteString, default=None) -> Union[bytes, None]:
         raise NotImplementedError  # pragma: no cover
 
     def clear(self) -> None:
@@ -34,9 +35,32 @@ def items(self) -> Generator[Tuple[bytes, bytes], None, None]:
 
 class SQLiteStorage(CacheStorageBase):
     SQLITE_TIMESTAMP = "(julianday('now') - 2440587.5)*86400.0"
-
-    def __init__(self, *, filepath, ttl, maxsize):
-        super(SQLiteStorage, self).__init__(ttl=ttl, maxsize=maxsize)
+    POLICIES = {
+        'FIFO': {
+            'additional_columns': [],
+            'after_get_ok': None,
+            'additional_indexes': [],
+            'delete_order_by': 'ts',
+        },
+        'LRU': {
+            f'additional_columns': [f"used INT NOT NULL DEFAULT 0"],
+            f'additional_indexes': ['used, ts'],
+            f'after_get_ok': f"UPDATE cache SET used = (SELECT max(used) FROM cache) + 1",
+            f'delete_order_by': 'used, ts',
+        },
+        'LFU': {
+            'additional_columns': ['used INT NOT NULL DEFAULT 0'],
+            'additional_indexes': ['used, ts'],
+            'after_get_ok': "UPDATE cache SET used = used + 1",
+            f'delete_order_by': 'used, ts',
+        },
+    }
+
+    def __init__(self, *, filepath, ttl, maxsize, policy='FIFO'):
+        if policy not in self.POLICIES:
+            raise ValueError(f'Invalid policy: {policy}')
+        super(SQLiteStorage, self).__init__(
+            ttl=ttl, maxsize=maxsize, policy=policy)
         self.filepath = filepath
         self.db = sqlite3.connect(filepath, isolation_level='DEFERRED')
         self.init_db()
@@ -77,8 +101,7 @@ def __exit__(self, exc_type, exc_val, exc_tb):
     def __setitem__(self, key, value):
         with self.db as db:
             db.execute(
-                "INSERT OR REPLACE INTO cache VALUES "
-                f"(?, {self.SQLITE_TIMESTAMP}, ?)",
+                "INSERT OR REPLACE INTO cache (key, value) VALUES (?, ?)",
                 (key, value)
             )
 
@@ -95,44 +118,61 @@ def __delitem__(self, key):
             raise KeyError('Not found')
 
     def get(self, key, default=None):
-        rows = self.db.execute(
-            self.sql_select,
-            (key,),
-        ).fetchall()
-        return rows[0][0] if rows else default
+        with self.db:
+            rows = self.db.execute(
+                self.sql_select,
+                (key,),
+            ).fetchall()
+            after_get_ok = self.POLICIES[self.policy]['after_get_ok']
+            if rows:
+                if after_get_ok:
+                    self.db.execute(
+                        f'{after_get_ok} WHERE key = ?',
+                        (key,),
+                    )
+                return rows[0][0]
+            else:
+                return default
 
     def init_db(self):
+        policy_stuff = self.POLICIES[self.policy]
+
         after_insert_actions = []
         if self.ttl > 0:
-            after_insert_actions.append(
-                '  DELETE FROM cache WHERE '
-                f'({self.SQLITE_TIMESTAMP} - ts) > {self.ttl};'
-            )
+            after_insert_actions.append(f'''
+                DELETE FROM cache WHERE
+                ({self.SQLITE_TIMESTAMP} - ts) > {self.ttl};
+            ''')
         if self.maxsize > 0:
-            after_insert_actions.append(
-                '  DELETE FROM cache WHERE key in ('
-                'SELECT key FROM cache '
-                'ORDER BY ts LIMIT '
-                f'max(0, (SELECT COUNT(key) FROM cache) - {self.maxsize}));'
-            )
+            after_insert_actions.append(f'''
+                DELETE FROM cache WHERE key in (
+                    SELECT key FROM cache
+                    ORDER BY {policy_stuff['delete_order_by']}
+                    LIMIT max(0, (SELECT COUNT(key) FROM cache) - {self.maxsize})
+                );
+            ''')
 
         with self.db as db:
-            db.execute(
-                'CREATE TABLE IF NOT EXISTS cache ('
-                ' key BINARY PRIMARY KEY,'
-                ' ts REAL,'
-                ' value BLOB'
-                ') WITHOUT ROWID'
-            )
+            db.execute(f'''
+                CREATE TABLE IF NOT EXISTS cache (
+                    key BINARY PRIMARY KEY,
+                    ts REAL NOT NULL DEFAULT ({self.SQLITE_TIMESTAMP}),
+                    {''.join(f"{c}, " for c in policy_stuff['additional_columns'])}
+                    value BLOB NOT NULL
+                ) WITHOUT ROWID
+            ''')
             db.execute('CREATE INDEX IF NOT EXISTS i_cache_ts ON cache (ts)')
+
+            for i, columns in enumerate(policy_stuff['additional_indexes']):
+                db.execute(f'CREATE INDEX IF NOT EXISTS i_cache_{i} ON cache ({columns})')
+
             if after_insert_actions:
-                trigger_ddl = (
-                    'CREATE TRIGGER IF NOT EXISTS t_cache_cleanup\n'
-                    'AFTER INSERT ON cache FOR EACH ROW BEGIN\n'
-                    '%s\n'
-                    'END'
-                ) % '\n'.join(after_insert_actions)
-                db.execute(trigger_ddl)
+                db.execute(f'''
+                    CREATE TRIGGER IF NOT EXISTS t_cache_cleanup
+                    AFTER INSERT ON cache FOR EACH ROW BEGIN
+                        %s
+                    END
+                ''' % '\n'.join(after_insert_actions))
 
     def clear(self):
         with self.db as db:

tests/test_cache.py

@@ -15,8 +15,8 @@ def cache(tempdirpath, request):
 
 
 def test_repr():
-    c = Cache(maxsize=1, ttl=1, filepath=None, x='y')
-    expected = ("Cache(maxsize=1, ttl=1, filepath=None, "
+    c = Cache(maxsize=1, ttl=1, filepath=None, policy='FIFO', x='y')
+    expected = ("Cache(maxsize=1, ttl=1, filepath=None, policy='FIFO', "
                 f"key={make_key}, x='y')")
     assert repr(c) == expected
 
@@ -263,3 +263,58 @@ def test_items(cache):
     time.sleep(0.001)
     cache[2] = 'two'
     assert [(k, v) for k, v in cache.items()] == [(1, 'one'), (2, 'two')]
+
+
+@pytest.mark.parametrize('storage', ['file', 'memory'])
+def test_lru(tempdirpath, storage):
+    filepath = None if storage == 'memory' else f'{tempdirpath}/cache'
+    cache = Cache(filepath=filepath, maxsize=2, ttl=-1, policy='LRU')
+
+    @cache
+    def func(a):
+        return a
+
+    def keys():
+        return [arg for (fn_name, arg), v in cache.items()]
+
+    assert func(1) == 1
+    assert func(2) == 2
+    the_keys = keys()
+    assert len(the_keys) == 2
+    assert 1 in the_keys and 2 in the_keys
+
+    assert func(1) == 1
+    assert func(3) == 3
+    the_keys = keys()
+    assert len(the_keys) == 2
+    assert 1 in the_keys and 3 in the_keys
+    assert 2 not in the_keys
+
+
+@pytest.mark.parametrize('storage', ['file', 'memory'])
+def test_lfu(tempdirpath, storage):
+    filepath = None if storage == 'memory' else f'{tempdirpath}/cache'
+    cache = Cache(filepath=filepath, maxsize=2, ttl=-1, policy='LFU')
+
+    @cache
+    def func(a):
+        return a
+
+    def keys():
+        return [arg for (fn_name, arg), v in cache.items()]
+
+    assert func(1) == 1
+    assert func(2) == 2
+    the_keys = keys()
+    assert len(the_keys) == 2
+    assert 1 in the_keys and 2 in the_keys
+
+    assert func(1) == 1
+    assert func(1) == 1
+    assert func(2) == 2
+    assert func(2) == 2
+    assert func(3) == 3
+    the_keys = keys()
+    assert len(the_keys) == 2
+    assert 1 in the_keys and 2 in the_keys
+    assert 3 not in the_keys