diskcache-community 5.7.0__py3-none-any.whl

diskcache/core.py

@@ -0,0 +1,3328 @@
+"""Core disk and file backed cache API.
+"""
+
+import codecs
+import collections as co
+import contextlib as cl
+import datetime as dt
+import decimal
+import errno
+import fractions
+import functools as ft
+import inspect
+import io
+import json
+import os
+import os.path as op
+import pathlib
+import pickle
+import pickletools
+import sqlite3
+import struct
+import tempfile
+import threading
+import time
+import uuid
+import warnings
+import weakref
+import zlib
+
+
+def full_name(func):
+    """Return full name of `func` by adding the module and function name."""
+    return func.__module__ + '.' + func.__qualname__
+
+
+class Constant(tuple):
+    """Pretty display of immutable constant."""
+
+    def __new__(cls, name):
+        return tuple.__new__(cls, (name,))
+
+    def __repr__(self):
+        return '%s' % self[0]
+
+
+DBNAME = 'cache.db'
+ENOVAL = Constant('ENOVAL')
+UNKNOWN = Constant('UNKNOWN')
+
+MODE_NONE = 0
+MODE_RAW = 1
+MODE_BINARY = 2
+MODE_TEXT = 3
+MODE_PICKLE = 4
+
+DEFAULT_SETTINGS = {
+    'statistics': 0,  # False
+    'tag_index': 0,  # False
+    'eviction_policy': 'least-recently-stored',
+    'size_limit': 2**30,  # 1gb
+    'cull_limit': 10,
+    'sqlite_auto_vacuum': 1,  # FULL
+    'sqlite_cache_size': 2**13,  # 8,192 pages
+    'sqlite_journal_mode': 'wal',
+    'sqlite_mmap_size': 2**26,  # 64mb
+    'sqlite_synchronous': 1,  # NORMAL
+    'disk_min_file_size': 2**15,  # 32kb
+    'disk_pickle_protocol': pickle.HIGHEST_PROTOCOL,
+}
+
+METADATA = {
+    'count': 0,
+    'size': 0,
+    'hits': 0,
+    'misses': 0,
+}
+
+# Triggers that keep the "count" and "size" metadata in the Settings table in
+# step with the Cache table, as (name, definition) pairs where the definition
+# is the text that follows "CREATE TRIGGER <name>". Caches written by
+# versions before 5.7.0 store these triggers with double-quoted literals,
+# which SQLite builds compiled with SQLITE_DQS=0 reject (issue #343), so
+# Cache.__init__ compares the stored trigger text with these definitions and
+# recreates the triggers when they differ.
+
+SETTINGS_TRIGGERS = (
+    (
+        'Settings_count_insert',
+        'AFTER INSERT ON Cache FOR EACH ROW BEGIN'
+        ' UPDATE Settings SET value = value + 1'
+        " WHERE key = 'count'; END",
+    ),
+    (
+        'Settings_count_delete',
+        'AFTER DELETE ON Cache FOR EACH ROW BEGIN'
+        ' UPDATE Settings SET value = value - 1'
+        " WHERE key = 'count'; END",
+    ),
+    (
+        'Settings_size_insert',
+        'AFTER INSERT ON Cache FOR EACH ROW BEGIN'
+        ' UPDATE Settings SET value = value + NEW.size'
+        " WHERE key = 'size'; END",
+    ),
+    (
+        'Settings_size_update',
+        'AFTER UPDATE ON Cache FOR EACH ROW BEGIN'
+        ' UPDATE Settings'
+        ' SET value = value + NEW.size - OLD.size'
+        " WHERE key = 'size'; END",
+    ),
+    (
+        'Settings_size_delete',
+        'AFTER DELETE ON Cache FOR EACH ROW BEGIN'
+        ' UPDATE Settings SET value = value - OLD.size'
+        " WHERE key = 'size'; END",
+    ),
+)
+
+EVICTION_POLICY = {
+    'none': {
+        'init': None,
+        'get': None,
+        'cull': None,
+    },
+    'least-recently-stored': {
+        'init': (
+            'CREATE INDEX IF NOT EXISTS Cache_store_time ON'
+            ' Cache (store_time)'
+        ),
+        'get': None,
+        'cull': 'SELECT {fields} FROM Cache ORDER BY store_time LIMIT ?',
+    },
+    'least-recently-used': {
+        'init': (
+            'CREATE INDEX IF NOT EXISTS Cache_access_time ON'
+            ' Cache (access_time)'
+        ),
+        'get': 'access_time = {now}',
+        'cull': 'SELECT {fields} FROM Cache ORDER BY access_time LIMIT ?',
+    },
+    'least-frequently-used': {
+        'init': (
+            'CREATE INDEX IF NOT EXISTS Cache_access_count ON'
+            ' Cache (access_count)'
+        ),
+        'get': 'access_count = access_count + 1',
+        'cull': 'SELECT {fields} FROM Cache ORDER BY access_count LIMIT ?',
+    },
+}
+
+
+def native_filename(filename):
+    """Return `filename` with the path separators of the current platform.
+
+    The Cache table's `filename` column stores a path relative to the cache
+    directory with the separator of the operating system that wrote the
+    value, so a cache written on Windows holds backslashes and a cache written
+    anywhere else holds slashes (upstream issue 304). Both forms are accepted:
+    on Windows, slashes become backslashes so paths compare equal to those
+    returned by `os.walk`; elsewhere, backslashes become slashes. Filenames are
+    generated by :meth:`Disk.filename`, which never uses either character
+    except as a separator, so no stored name is misread.
+
+    :param str filename: filename relative to the cache directory
+    :return: filename with native separators
+
+    """
+    if os.sep == '/':
+        return filename.replace('\\', '/')
+    return filename.replace('/', os.sep)
+
+
+def _makedirs_private(directory):
+    """Create `directory` and its missing parents with mode ``0o700``.
+
+    Unlike :func:`os.makedirs`, the mode applies to every directory created,
+    not only to the last one, so no directory the cache creates is readable
+    by other users. Directories that already exist keep their mode. Windows
+    ignores the mode bits.
+
+    """
+    parent = op.dirname(directory)
+
+    if parent and parent != directory and not op.isdir(parent):
+        _makedirs_private(parent)
+
+    with cl.suppress(FileExistsError):
+        os.mkdir(directory, 0o700)
+
+
+class Disk:
+    """Cache key and value serialization for SQLite database and files."""
+
+    def __init__(self, directory, min_file_size=0, pickle_protocol=0):
+        """Initialize disk instance.
+
+        :param str directory: directory path
+        :param int min_file_size: minimum size for file use
+        :param int pickle_protocol: pickle protocol for serialization
+
+        """
+        self._directory = directory
+        self.min_file_size = min_file_size
+        self.pickle_protocol = pickle_protocol
+
+    def hash(self, key):
+        """Compute portable hash for `key`.
+
+        :param key: key to hash
+        :return: hash value
+
+        """
+        mask = 0xFFFFFFFF
+        disk_key, _ = self.put(key)
+        type_disk_key = type(disk_key)
+
+        if type_disk_key is sqlite3.Binary:
+            return zlib.adler32(disk_key) & mask
+        elif type_disk_key is str:
+            return zlib.adler32(disk_key.encode('utf-8')) & mask  # noqa
+        elif type_disk_key is int:
+            return disk_key % mask
+        else:
+            assert type_disk_key is float
+            return zlib.adler32(struct.pack('!d', disk_key)) & mask
+
+    def put(self, key):
+        """Convert `key` to fields key and raw for Cache table.
+
+        :param key: key to convert
+        :return: (database key, raw boolean) pair
+
+        """
+        # pylint: disable=unidiomatic-typecheck
+        type_key = type(key)
+
+        if type_key is bytes:
+            return sqlite3.Binary(key), True
+        elif (
+            (type_key is str)
+            or (
+                type_key is int
+                and -9223372036854775808 <= key <= 9223372036854775807
+            )
+            or (type_key is float)
+        ):
+            return key, True
+        else:
+            data = pickle.dumps(key, protocol=self.pickle_protocol)
+            result = pickletools.optimize(data)
+            return sqlite3.Binary(result), False
+
+    def get(self, key, raw):
+        """Convert fields `key` and `raw` from Cache table to key.
+
+        :param key: database key to convert
+        :param bool raw: flag indicating raw database storage
+        :return: corresponding Python key
+
+        """
+        # pylint: disable=unidiomatic-typecheck
+        if raw:
+            return bytes(key) if type(key) is sqlite3.Binary else key
+        else:
+            return pickle.load(io.BytesIO(key))
+
+    def store(self, value, read, key=UNKNOWN):
+        """Convert `value` to fields size, mode, filename, and value for Cache
+        table.
+
+        :param value: value to convert
+        :param bool read: True when value is file-like object
+        :param key: key for item (default UNKNOWN)
+        :return: (size, mode, filename, value) tuple for Cache table
+
+        """
+        # pylint: disable=unidiomatic-typecheck
+        type_value = type(value)
+        min_file_size = self.min_file_size
+
+        if (
+            (type_value is str and len(value) < min_file_size)
+            or (
+                type_value is int
+                and -9223372036854775808 <= value <= 9223372036854775807
+            )
+            or (type_value is float)
+        ):
+            return 0, MODE_RAW, None, value
+        elif type_value is bytes:
+            if len(value) < min_file_size:
+                return 0, MODE_RAW, None, sqlite3.Binary(value)
+            else:
+                filename, full_path = self.filename(key, value)
+                self._write(full_path, value, 'xb')
+                return len(value), MODE_BINARY, filename, None
+        elif type_value is str:
+            filename, full_path = self.filename(key, value)
+            self._write(full_path, io.StringIO(value), 'x', 'UTF-8')
+            size = op.getsize(full_path)
+            return size, MODE_TEXT, filename, None
+        elif read:
+            reader = ft.partial(value.read, 2**22)
+            filename, full_path = self.filename(key, value)
+            iterator = iter(reader, b'')
+            size = self._write(full_path, iterator, 'xb')
+            return size, MODE_BINARY, filename, None
+        else:
+            result = pickle.dumps(value, protocol=self.pickle_protocol)
+
+            if len(result) < min_file_size:
+                return 0, MODE_PICKLE, None, sqlite3.Binary(result)
+            else:
+                filename, full_path = self.filename(key, value)
+                self._write(full_path, result, 'xb')
+                return len(result), MODE_PICKLE, filename, None
+
+    def _write(self, full_path, iterator_or_bytes, mode, encoding=None):
+        full_dir, _ = op.split(full_path)
+
+        for count in range(1, 11):
+            with cl.suppress(OSError):
+                _makedirs_private(full_dir)
+
+            try:
+                # Another cache may have deleted the directory before
+                # the file could be opened.
+                writer = open(full_path, mode, encoding=encoding)
+            except OSError:
+                if count == 10:
+                    # Give up after 10 tries to open the file.
+                    raise
+                continue
+
+            with writer:
+                if isinstance(iterator_or_bytes, bytes):
+                    writer.write(iterator_or_bytes)
+                    return len(iterator_or_bytes)
+                else:
+                    size = 0
+                    for chunk in iterator_or_bytes:
+                        size += len(chunk)
+                        writer.write(chunk)
+                    return size
+
+    def fetch(self, mode, filename, value, read):
+        """Convert fields `mode`, `filename`, and `value` from Cache table to
+        value.
+
+        :param int mode: value mode raw, binary, text, or pickle
+        :param str filename: filename of corresponding value, with the path
+            separators of the operating system that stored it
+        :param value: database value
+        :param bool read: when True, return an open file handle
+        :return: corresponding Python value
+        :raises: IOError if the value cannot be read
+
+        """
+        # pylint: disable=unidiomatic-typecheck,consider-using-with
+        if mode == MODE_RAW:
+            return bytes(value) if type(value) is sqlite3.Binary else value
+        elif mode == MODE_BINARY:
+            full_path = op.join(self._directory, native_filename(filename))
+            if read:
+                return open(full_path, 'rb')
+            else:
+                with open(full_path, 'rb') as reader:
+                    return reader.read()
+        elif mode == MODE_TEXT:
+            full_path = op.join(self._directory, native_filename(filename))
+            with open(full_path, 'r', encoding='UTF-8') as reader:
+                return reader.read()
+        elif mode == MODE_PICKLE:
+            if value is None:
+                full_path = op.join(self._directory, native_filename(filename))
+                with open(full_path, 'rb') as reader:
+                    return pickle.load(reader)
+            else:
+                return pickle.load(io.BytesIO(value))
+
+    def filename(self, key=UNKNOWN, value=UNKNOWN):
+        """Return filename and full-path tuple for file storage.
+
+        Filename will be a randomly generated 28 character hexadecimal string
+        with ".val" suffixed. Two levels of sub-directories will be used to
+        reduce the size of directories. On older filesystems, lookups in
+        directories with many files may be slow.
+
+        The default implementation ignores the `key` and `value` parameters.
+
+        In some scenarios, for example :meth:`Cache.push
+        <diskcache.Cache.push>`, the `key` or `value` may not be known when the
+        item is stored in the cache.
+
+        :param key: key for item (default UNKNOWN)
+        :param value: value for item (default UNKNOWN)
+
+        """
+        # pylint: disable=unused-argument
+        hex_name = codecs.encode(os.urandom(16), 'hex').decode('utf-8')
+        sub_dir = op.join(hex_name[:2], hex_name[2:4])
+        name = hex_name[4:] + '.val'
+        filename = op.join(sub_dir, name)
+        full_path = op.join(self._directory, filename)
+        return filename, full_path
+
+    def remove(self, file_path):
+        """Remove a file given by `file_path`.
+
+        This method is cross-thread and cross-process safe. If an OSError
+        occurs, it is suppressed.
+
+        :param str file_path: relative path to file, with the path separators
+            of the operating system that stored it
+
+        """
+        full_path = op.join(self._directory, native_filename(file_path))
+        full_dir, _ = op.split(full_path)
+
+        # Suppress OSError that may occur if two caches attempt to delete the
+        # same file or directory at the same time.
+
+        with cl.suppress(OSError):
+            os.remove(full_path)
+
+        with cl.suppress(OSError):
+            os.removedirs(full_dir)
+
+
+class JSONDisk(Disk):
+    """Cache key and value using JSON serialization with zlib compression."""
+
+    def __init__(self, directory, compress_level=1, **kwargs):
+        """Initialize JSON disk instance.
+
+        Keys and values are compressed using the zlib library. The
+        `compress_level` is an integer from 0 to 9 controlling the level of
+        compression; 1 is fastest and produces the least compression, 9 is
+        slowest and produces the most compression, and 0 is no compression.
+
+        :param str directory: directory path
+        :param int compress_level: zlib compression level (default 1)
+        :param kwargs: super class arguments
+
+        """
+        self.compress_level = compress_level
+        super().__init__(directory, **kwargs)
+
+    def put(self, key):
+        json_bytes = json.dumps(key).encode('utf-8')
+        data = zlib.compress(json_bytes, self.compress_level)
+        return super().put(data)
+
+    def get(self, key, raw):
+        data = super().get(key, raw)
+        return json.loads(zlib.decompress(data).decode('utf-8'))
+
+    def store(self, value, read, key=UNKNOWN):
+        if not read:
+            json_bytes = json.dumps(value).encode('utf-8')
+            value = zlib.compress(json_bytes, self.compress_level)
+        return super().store(value, read, key=key)
+
+    def fetch(self, mode, filename, value, read):
+        data = super().fetch(mode, filename, value, read)
+        if not read:
+            data = json.loads(zlib.decompress(data).decode('utf-8'))
+        return data
+
+
+# Names that SafeDisk lets pickle resolve while reading, keyed by the module
+# recorded in the pickle. Protocols 0 to 2 record the Python 2 module names
+# and use copyreg._reconstructor and _codecs.encode to rebuild objects, so
+# those spellings and helpers are included. Every entry is a standard-library
+# constructor whose call cannot run code beyond building the object itself.
+# Helpers that reach attributes, such as builtins.getattr, which pickle uses
+# for zoneinfo.ZoneInfo, are deliberately absent.
+
+_SAFE_BUILTINS = frozenset(
+    {
+        'bytearray',
+        'bytes',
+        'complex',
+        'dict',
+        'float',
+        'frozenset',
+        'int',
+        'list',
+        'object',
+        'range',
+        'set',
+        'slice',
+        'str',
+        'tuple',
+    }
+)
+
+SAFE_PICKLE_NAMES = {
+    'builtins': _SAFE_BUILTINS,
+    '__builtin__': _SAFE_BUILTINS | {'long', 'unicode', 'xrange'},
+    'collections': frozenset(
+        {'Counter', 'OrderedDict', 'defaultdict', 'deque'}
+    ),
+    'copyreg': frozenset({'_reconstructor'}),
+    'copy_reg': frozenset({'_reconstructor'}),
+    '_codecs': frozenset({'encode'}),
+    'datetime': frozenset(
+        {'date', 'datetime', 'time', 'timedelta', 'timezone'}
+    ),
+    'decimal': frozenset({'Decimal'}),
+    'fractions': frozenset({'Fraction'}),
+    'uuid': frozenset({'UUID'}),
+}
+
+# Python types that SafeDisk accepts for writing: exactly the types that the
+# names above read back. Subclasses are rejected because pickle records the
+# subclass, which the reader would refuse.
+
+SAFE_TYPES = frozenset(
+    {
+        type(None),
+        bool,
+        int,
+        float,
+        complex,
+        str,
+        bytes,
+        bytearray,
+        list,
+        tuple,
+        dict,
+        set,
+        frozenset,
+        range,
+        slice,
+        co.Counter,
+        co.OrderedDict,
+        co.defaultdict,
+        co.deque,
+        dt.date,
+        dt.datetime,
+        dt.time,
+        dt.timedelta,
+        dt.timezone,
+        decimal.Decimal,
+        fractions.Fraction,
+        uuid.UUID,
+    }
+)
+
+_SAFE_MAPPINGS = (dict, co.Counter, co.OrderedDict, co.defaultdict)
+_SAFE_SEQUENCES = (list, tuple, set, frozenset, co.deque)
+_SAFE_TZ_TYPES = (type(None), dt.timezone)
+
+
+class SafeUnpickler(pickle.Unpickler):
+    """Unpickler that resolves only the names in SAFE_PICKLE_NAMES.
+
+    Every pickle opcode that can call code (GLOBAL, STACK_GLOBAL, INST, OBJ,
+    NEWOBJ, NEWOBJ_EX and REDUCE) obtains its callable through `find_class`,
+    so restricting `find_class` to a fixed set of constructors is enough to
+    keep a crafted pickle from running code.
+
+    """
+
+    def find_class(self, module, name):
+        if name in SAFE_PICKLE_NAMES.get(module, ()):
+            return super().find_class(module, name)
+        raise pickle.UnpicklingError(
+            'SafeDisk refuses to unpickle %s.%s' % (module, name)
+        )
+
+
+class SafeDisk(Disk):
+    """Disk that reads back only an allowlist of standard-library types.
+
+    The default :class:`Disk` stores keys and values that SQLite cannot hold
+    natively as pickles and reads them back with :func:`pickle.load`, so
+    anyone who can write into the cache directory can run code in the process
+    that reads from it (CVE-2025-69872). :class:`SafeDisk` closes that path:
+
+    * Pickled keys and values are read with an unpickler that resolves only
+      the standard-library constructors in ``SAFE_PICKLE_NAMES`` and raises
+      :exc:`pickle.UnpicklingError` for anything else.
+    * Keys and values are checked before they are written, and a key or value
+      whose type the reader would refuse raises :exc:`TypeError` at write
+      time instead of failing later at read time.
+    * Paths read from the ``filename`` column are confined to the cache
+      directory, and a path that escapes it raises :exc:`ValueError`.
+
+    The on-disk format is the one :class:`Disk` writes, so a directory
+    written with :class:`SafeDisk` opens with :class:`Disk` and the reverse,
+    as long as the values are within the allowlist. Nothing about the choice
+    of disk is persisted; select it with ``Cache(directory, disk=SafeDisk)``,
+    ``FanoutCache(directory, disk=SafeDisk)``, ``Deque(disk=SafeDisk)``,
+    ``Index(disk=SafeDisk)`` or the ``DISK`` option of the Django backend.
+
+    Objects outside the allowlist, such as instances of your own classes,
+    Django model instances and responses, and the ``type`` objects that
+    ``memoize(typed=True)`` puts into keys, need the default :class:`Disk`.
+
+    """
+
+    def __init__(self, directory, min_file_size=0, pickle_protocol=0):
+        super().__init__(directory, min_file_size, pickle_protocol)
+        self._real_directory = op.realpath(directory)
+
+    def _check(self, obj, what):
+        """Raise TypeError unless every object in `obj` is in SAFE_TYPES."""
+        seen = set()
+        stack = [obj]
+
+        while stack:
+            item = stack.pop()
+            type_item = type(item)
+
+            if type_item not in SAFE_TYPES:
+                raise TypeError(
+                    'SafeDisk cannot store %s of type %s.%s'
+                    % (what, type_item.__module__, type_item.__qualname__)
+                )
+
+            if type_item in _SAFE_MAPPINGS:
+                if id(item) in seen:
+                    continue
+                seen.add(id(item))
+                if type_item is co.defaultdict:
+                    factory = item.default_factory
+                    if factory is not None and factory not in SAFE_TYPES:
+                        raise TypeError(
+                            'SafeDisk cannot store %s with defaultdict'
+                            ' factory %r' % (what, factory)
+                        )
+                stack.extend(item.keys())
+                stack.extend(item.values())
+            elif type_item in _SAFE_SEQUENCES:
+                if id(item) in seen:
+                    continue
+                seen.add(id(item))
+                stack.extend(item)
+            elif type_item in (dt.datetime, dt.time):
+                if type(item.tzinfo) not in _SAFE_TZ_TYPES:
+                    raise TypeError(
+                        'SafeDisk cannot store %s with tzinfo of type %s.%s'
+                        % (
+                            what,
+                            type(item.tzinfo).__module__,
+                            type(item.tzinfo).__qualname__,
+                        )
+                    )
+
+    def _confine(self, filename):
+        """Raise ValueError unless `filename` stays in the cache directory."""
+        normalized = str(filename).replace('\\', '/')
+
+        if (
+            normalized.startswith('/')
+            or op.isabs(normalized)
+            or op.splitdrive(normalized)[0]
+            or '..' in normalized.split('/')
+        ):
+            raise ValueError(
+                'SafeDisk refuses the path %r outside the cache directory'
+                % (filename,)
+            )
+
+        directory = self._real_directory
+        full_path = op.realpath(op.join(directory, filename))
+
+        try:
+            inside = op.commonpath((directory, full_path)) == directory
+        except ValueError:  # Different drives on Windows.
+            inside = False
+
+        if not inside:
+            raise ValueError(
+                'SafeDisk refuses the path %r outside the cache directory'
+                % (filename,)
+            )
+
+    def put(self, key):
+        # pylint: disable=unidiomatic-typecheck
+        if type(key) not in (bytes, str, int, float):
+            self._check(key, 'key')
+        return super().put(key)
+
+    def get(self, key, raw):
+        if raw:
+            return super().get(key, raw)
+        return SafeUnpickler(io.BytesIO(key)).load()
+
+    def store(self, value, read, key=UNKNOWN):
+        # pylint: disable=unidiomatic-typecheck
+        if not read and type(value) not in (bytes, str, int, float):
+            self._check(value, 'value')
+        return super().store(value, read, key=key)
+
+    def fetch(self, mode, filename, value, read):
+        if filename is not None:
+            self._confine(filename)
+
+        if mode == MODE_PICKLE:
+            if value is None:
+                value = super().fetch(MODE_BINARY, filename, None, False)
+            return SafeUnpickler(io.BytesIO(value)).load()
+
+        return super().fetch(mode, filename, value, read)
+
+    def remove(self, file_path):
+        self._confine(file_path)
+        super().remove(file_path)
+
+
+def _meta_result(value, expire_time, tag, store_time, meta=(None, None, None)):
+    """Return `value`, or a tuple of `value` and the requested metadata.
+
+    The tuple holds, after the value, the expire time when `expire_time` is
+    true, the tag when `tag` is true and the store time when `store_time` is
+    true, in that order. `meta` supplies the three database values; the
+    default is used when the key is missing.
+
+    """
+    if not (expire_time or tag or store_time):
+        return value
+    db_expire_time, db_tag, db_store_time = meta
+    result = (value,)
+    if expire_time:
+        result += (db_expire_time,)
+    if tag:
+        result += (db_tag,)
+    if store_time:
+        result += (db_store_time,)
+    return result
+
+
+class Timeout(Exception):
+    """Database timeout expired."""
+
+
+class ReadOnlyError(sqlite3.OperationalError):  # pylint: disable=R0903
+    """Write attempted on a read-only cache.
+
+    Raised by every method that would modify a cache opened read-only, either
+    explicitly with ``Cache(directory, read_only=True)`` or because the cache
+    database or its directory is not writable. A subclass of
+    :exc:`sqlite3.OperationalError`, the error SQLite itself raises for
+    writes to a read-only database, so existing handlers keep working.
+    """
+
+
+# Pragmas that are stored in the database file rather than set per
+# connection; a read-only cache leaves them as the file has them.
+_PERSISTENT_PRAGMAS = frozenset({'auto_vacuum', 'journal_mode'})
+
+# SQL condition selecting rows that have not expired, evaluated by SQLite
+# itself so it can be embedded in a statement without a parameter. Used by
+# read-only caches, which cannot delete expired rows while reading.
+_LIVE_CONDITION = (
+    '(expire_time IS NULL'
+    " OR expire_time > (julianday('now') - 2440587.5) * 86400.0)"
+)
+
+
+class UnknownFileWarning(UserWarning):
+    """Warning used by Cache.check for unknown files."""
+
+
+class EmptyDirWarning(UserWarning):
+    """Warning used by Cache.check for empty directories."""
+
+
+def args_to_key(base, args, kwargs, typed, ignore):
+    """Create cache key out of function arguments.
+
+    :param tuple base: base of key
+    :param tuple args: function arguments
+    :param dict kwargs: function keyword arguments
+    :param bool typed: include types in cache key
+    :param set ignore: positional or keyword args to ignore
+    :return: cache key tuple
+
+    """
+    args = tuple(arg for index, arg in enumerate(args) if index not in ignore)
+    key = base + args + (None,)
+
+    if kwargs:
+        kwargs = {key: val for key, val in kwargs.items() if key not in ignore}
+        sorted_items = sorted(kwargs.items())
+
+        for item in sorted_items:
+            key += item
+
+    if typed:
+        key += tuple(type(arg) for arg in args)
+
+        if kwargs:
+            key += tuple(type(value) for _, value in sorted_items)
+
+    return key
+
+
+_POSITIONAL_KINDS = (
+    inspect.Parameter.POSITIONAL_ONLY,
+    inspect.Parameter.POSITIONAL_OR_KEYWORD,
+)
+
+
+def resolve_ignore(func, ignore):
+    """Expand `ignore` with the positions of the parameters it names.
+
+    `args_to_key` drops positional arguments by index and keyword arguments by
+    name, so a name in `ignore` used to match an argument only when the caller
+    passed it by keyword (upstream issue 240). Adding the position of each
+    positional parameter with that name makes the name match the argument
+    however it is passed. Keys of calls that do not pass an ignored parameter
+    positionally are unchanged.
+
+    :param func: callable being memoized
+    :param set ignore: positional or keyword args to ignore
+    :return: `ignore`, or a frozenset of `ignore` plus the resolved positions
+
+    """
+    if not ignore:
+        return ignore
+
+    try:
+        parameters = inspect.signature(func).parameters.values()
+    except (TypeError, ValueError):  # No signature, like some builtins.
+        return ignore
+
+    positions = set()
+
+    for index, parameter in enumerate(parameters):
+        if parameter.kind not in _POSITIONAL_KINDS:
+            break
+        if parameter.name in ignore:
+            positions.add(index)
+
+    if not positions:
+        return ignore
+
+    return frozenset(ignore) | positions
+
+
+class _ThreadSentinel:  # pylint: disable=too-few-public-methods
+    """Marker kept in a Cache's thread-local state next to its connection.
+
+    Thread-local state is destroyed when its thread exits, so once a weak
+    reference to the sentinel is dead the connection's thread is gone and
+    the connection may be closed from another thread.
+    """
+
+    __slots__ = ('__weakref__',)
+
+
+class _Connections:
+    """Registry of the SQLite connections one Cache opened in this process.
+
+    Connections are opened per thread (see ``Cache._con``). The registry
+    lets ``Cache.close`` and garbage collection close the connections of
+    threads that have already exited, and lets a forked child process
+    forget the connections it inherited without closing them.
+    """
+
+    def __init__(self):
+        self._lock = threading.Lock()
+        self._items = {}
+        self.pid = os.getpid()
+
+    def add(self, ident, sentinel, con):
+        """Register `con` for thread `ident`; return connections to close.
+
+        The returned connections belong to threads that have exited, or are
+        an earlier connection of the same thread whose thread-local state
+        was lost (a foreign thread that got a new interpreter thread state).
+        """
+        with self._lock:
+            stale = self._pop_stale()
+            previous = self._items.pop(ident, None)
+            self._items[ident] = (weakref.ref(sentinel), con)
+        if previous is not None and previous[1] is not con:
+            stale.append(previous[1])
+        return stale
+
+    def pop(self, ident):
+        """Remove the connection of thread `ident` and return it with the
+        connections of threads that have exited, all to be closed."""
+        with self._lock:
+            stale = self._pop_stale()
+            item = self._items.pop(ident, None)
+        if item is not None:
+            stale.append(item[1])
+        return stale
+
+    def _pop_stale(self):
+        # The caller holds the lock.
+        stale = []
+        for ident, (ref, con) in list(self._items.items()):
+            if ref() is None:
+                del self._items[ident]
+                stale.append(con)
+        return stale
+
+    def close_all(self):
+        """Close every registered connection.
+
+        Runs when the Cache is garbage collected. In a child process the
+        connections were inherited and are discarded instead.
+        """
+        if os.getpid() != self.pid:
+            self.discard()
+            return
+        with self._lock:
+            cons = [con for _, con in self._items.values()]
+            self._items.clear()
+        for con in cons:
+            con.close()
+
+    def discard(self):
+        """Forget the connections after a fork without closing them.
+
+        SQLite forbids a child process from using, or even closing, a
+        connection the parent opened: the child inherits the parent's lock
+        state, and closing may roll back or unlock underneath the parent
+        and corrupt the database. The connections stay referenced for the
+        life of the child so garbage collection never closes them either;
+        their file descriptors leak on purpose, as SQLite recommends.
+        """
+        _INHERITED_CONNECTIONS.extend(con for _, con in self._items.values())
+        self._items = {}
+        self._lock = threading.Lock()  # The parent's lock may be held.
+        self.pid = os.getpid()
+
+
+class _ForkGate:
+    """Delay ``os.fork`` while another thread is inside a transaction.
+
+    A child process inherits the parent's SQLite state as of the fork. A
+    transaction in flight in another thread leaves the child's copy of that
+    state holding a write lock that nothing in the child ever releases, so
+    the child's own writes to that database would fail with ``Timeout``.
+    The gate holds new transactions back and makes fork wait, up to
+    `timeout` seconds, until the transactions in flight in other threads
+    finish; the held-back transactions proceed once the fork is done. The
+    forking thread's own transaction cannot be waited for and is not
+    counted; forking inside a transaction is unsupported.
+    """
+
+    timeout = 60
+
+    def __init__(self):
+        self._cond = threading.Condition(threading.Lock())
+        self._active = 0
+        self._forking = False
+        self._local = threading.local()
+
+    def __enter__(self):
+        depth = getattr(self._local, 'depth', 0)
+        if not depth:
+            with self._cond:
+                while self._forking:
+                    self._cond.wait()
+                self._active += 1
+        self._local.depth = depth + 1
+
+    def __exit__(self, *exception):
+        depth = getattr(self._local, 'depth', 0) - 1
+        if depth < 0:
+            return  # A child process reset the gate during a transaction.
+        self._local.depth = depth
+        if not depth:
+            with self._cond:
+                self._active -= 1
+                if not self._active:
+                    self._cond.notify_all()
+
+    def before_fork(self):
+        """Hold new transactions back, then wait for the active ones."""
+        own = 1 if getattr(self._local, 'depth', 0) else 0
+        deadline = time.monotonic() + self.timeout
+        with self._cond:
+            while self._forking:  # Another thread is forking.
+                self._cond.wait()
+            self._forking = True
+            while self._active > own:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    warnings.warn(
+                        'forking while a Cache transaction is in progress in'
+                        ' another thread; the child process may be unable'
+                        ' to write to that cache',
+                        RuntimeWarning,
+                        stacklevel=2,
+                    )
+                    break
+                self._cond.wait(remaining)
+
+    def after_fork_parent(self):
+        """Let transactions proceed again."""
+        with self._cond:
+            self._forking = False
+            self._cond.notify_all()
+
+    def after_fork_child(self):
+        """Start over: the child has one thread and no transactions."""
+        self._cond = threading.Condition(threading.Lock())
+        self._active = 0
+        self._forking = False
+        self._local = threading.local()
+
+
+_FORK_GATE = _ForkGate()
+
+# Every live Cache, so a child process can forget inherited connections.
+_CACHES: 'weakref.WeakSet[Cache]' = weakref.WeakSet()
+
+# Connections inherited from a parent process, kept open on purpose.
+_INHERITED_CONNECTIONS: list[sqlite3.Connection] = []
+
+
+def _before_fork():
+    # SQLite advises closing every connection before fork. The gate waits
+    # for other threads' transactions; then each cache closes the forking
+    # thread's own connection and those of exited threads, which the
+    # parent reopens on next use. Connections held by other live threads
+    # cannot be closed here and are discarded in the child.
+    _FORK_GATE.before_fork()
+    for cache in list(_CACHES):
+        cache._close_before_fork()  # pylint: disable=protected-access
+
+
+def _after_fork_in_child():
+    _FORK_GATE.after_fork_child()
+    for cache in list(_CACHES):
+        cache._discard_connections()  # pylint: disable=protected-access
+
+
+if hasattr(os, 'register_at_fork'):
+    os.register_at_fork(
+        before=_before_fork,
+        after_in_parent=_FORK_GATE.after_fork_parent,
+        after_in_child=_after_fork_in_child,
+    )
+
+
+class Cache:
+    """Disk and file backed cache."""
+
+    def __init__(
+        self,
+        directory=None,
+        timeout=60,
+        disk=Disk,
+        *,
+        read_only=False,
+        **settings
+    ):
+        """Initialize cache instance.
+
+        :param str directory: cache directory
+        :param float timeout: SQLite connection timeout
+        :param disk: Disk type or subclass for serialization
+        :param bool read_only: open the cache read-only (default False)
+        :param settings: any of DEFAULT_SETTINGS
+
+        The cache directory, any missing parents and the subdirectories that
+        hold large values are created with mode ``0o700``, so only the owner
+        can read them. A directory that already exists keeps its mode; the
+        cache never changes permissions. Windows ignores the mode bits.
+
+        Opening an existing cache writes nothing unless a setting differs
+        from the stored one. A cache whose database file or directory is not
+        writable opens read-only, as does a cache opened with `read_only`;
+        reads work and every method that would write raises
+        :exc:`ReadOnlyError`. The read-only state is not persisted and
+        `read_only` is not a setting. See the :ref:`tutorial
+        <tutorial-read-only>` for details.
+
+        """
+        try:
+            assert issubclass(disk, Disk)
+        except (TypeError, AssertionError):
+            raise ValueError('disk must subclass diskcache.Disk') from None
+
+        if directory is None:
+            directory = tempfile.mkdtemp(prefix='diskcache-')
+        directory = str(directory)
+        directory = op.expanduser(directory)
+        directory = op.expandvars(directory)
+
+        self._directory = directory
+        self._timeout = 0  # Manually handle retries during initialization.
+        self._local = threading.local()
+        self._cons = _Connections()
+        self._txn_id = None
+        _CACHES.add(self)
+        finalizer = weakref.finalize(self, self._cons.close_all)
+        finalizer.atexit = False
+
+        self._read_only = self._resolve_read_only(directory, read_only)
+
+        if not op.isdir(directory):
+            try:
+                _makedirs_private(op.abspath(directory))
+            except OSError as error:
+                if error.errno != errno.EEXIST:
+                    raise EnvironmentError(
+                        error.errno,
+                        'Cache directory "%s" does not exist'
+                        ' and could not be created' % self._directory,
+                    ) from None
+
+        sql = self._sql_retry
+
+        # Setup Settings table.
+
+        try:
+            current_settings = dict(
+                sql('SELECT key, value FROM Settings').fetchall()
+            )
+        except sqlite3.OperationalError:
+            if self._read_only:
+                raise ReadOnlyError(
+                    'read-only cache in %r has no Settings table' % directory
+                ) from None
+            current_settings = {}
+
+        sets = DEFAULT_SETTINGS.copy()
+        sets.update(current_settings)
+        sets.update(settings)
+
+        for key in METADATA:
+            sets.pop(key, None)
+
+        # Chance to set pragmas before any tables are created.
+
+        for key, value in sorted(sets.items()):
+            if key.startswith('sqlite_'):
+                self.reset(key, value, update=False)
+
+        if not self._read_only:
+            sql(
+                'CREATE TABLE IF NOT EXISTS Settings ('
+                ' key TEXT NOT NULL UNIQUE,'
+                ' value)'
+            )
+
+        # Setup Disk object (must happen after settings initialized).
+
+        kwargs = {
+            key[5:]: value
+            for key, value in sets.items()
+            if key.startswith('disk_')
+        }
+        self._disk = disk(directory, **kwargs)
+
+        self._init_settings(sql, sets, current_settings)
+
+        ((self._page_size,),) = sql('PRAGMA page_size').fetchall()
+
+        if self._read_only:
+            # The schema, triggers and tag index are whatever the writer
+            # left; reads need none of them to change.
+            self.close()
+            self._timeout = timeout
+            self._sql  # pylint: disable=pointless-statement
+            return
+
+        self._init_schema(sql)
+
+        # Close and re-open database connection with given timeout.
+
+        self.close()
+        self._timeout = timeout
+        self._sql  # pylint: disable=pointless-statement
+
+    @staticmethod
+    def _resolve_read_only(directory, read_only):
+        # A database that exists but cannot be written, or whose directory
+        # cannot be written, is opened read-only. Opening read-only on
+        # purpose needs an existing database, since nothing is created.
+        db_path = op.join(directory, DBNAME)
+        db_exists = op.isfile(db_path)
+
+        if read_only and not db_exists:
+            raise ReadOnlyError(
+                'no cache database to open read-only in %r' % directory
+            )
+
+        writable = os.access(directory, os.W_OK) and os.access(
+            db_path, os.W_OK
+        )
+        return bool(read_only) or (db_exists and not writable)
+
+    def _init_settings(self, sql, sets, current_settings):
+        # Set cached attributes: updates settings and sets pragmas. Only a
+        # setting that is missing or differs from the stored value is
+        # written, so opening an existing cache leaves the database alone.
+
+        for key, value in sets.items():
+            if (
+                not self._read_only
+                and current_settings.get(key, ENOVAL) != value
+            ):
+                query = 'INSERT OR REPLACE INTO Settings VALUES (?, ?)'
+                sql(query, (key, value))
+            self.reset(key, value, update=False)
+
+        for key, value in METADATA.items():
+            if key not in current_settings and not self._read_only:
+                query = 'INSERT OR IGNORE INTO Settings VALUES (?, ?)'
+                sql(query, (key, value))
+            self.reset(key)
+
+    def _init_schema(self, sql):
+        # Create the Cache table, its indexes and the triggers when they are
+        # missing. Every statement is a no-op on an existing database.
+
+        sql(
+            'CREATE TABLE IF NOT EXISTS Cache ('
+            ' rowid INTEGER PRIMARY KEY,'
+            ' key BLOB,'
+            ' raw INTEGER,'
+            ' store_time REAL,'
+            ' expire_time REAL,'
+            ' access_time REAL,'
+            ' access_count INTEGER DEFAULT 0,'
+            ' tag BLOB,'
+            ' size INTEGER DEFAULT 0,'
+            ' mode INTEGER DEFAULT 0,'
+            ' filename TEXT,'
+            ' value BLOB)'
+        )
+
+        sql(
+            'CREATE UNIQUE INDEX IF NOT EXISTS Cache_key_raw ON'
+            ' Cache(key, raw)'
+        )
+
+        sql(
+            'CREATE INDEX IF NOT EXISTS Cache_expire_time ON'
+            ' Cache (expire_time) WHERE expire_time IS NOT NULL'
+        )
+
+        query = EVICTION_POLICY[self.eviction_policy]['init']
+
+        if query is not None:
+            sql(query)
+
+        # Use triggers to keep Metadata updated.
+
+        for name, definition in SETTINGS_TRIGGERS:
+            sql('CREATE TRIGGER IF NOT EXISTS %s %s' % (name, definition))
+
+        self._update_triggers(sql)
+
+        # Create or drop the tag index only when the database disagrees
+        # with the setting, so a reopen does not write.
+
+        ((has_tag_index,),) = sql(
+            "SELECT COUNT(*) FROM sqlite_master WHERE type = 'index'"
+            " AND name = 'Cache_tag_rowid'"
+        ).fetchall()
+
+        if self.tag_index and not has_tag_index:  # pylint: disable=no-member
+            self.create_tag_index()
+        elif has_tag_index and not self.tag_index:  # pylint: disable=no-member
+            self.drop_tag_index()
+
+    @property
+    def directory(self):
+        """Cache directory."""
+        return self._directory
+
+    @property
+    def timeout(self):
+        """SQLite connection timeout value in seconds."""
+        return self._timeout
+
+    @property
+    def disk(self):
+        """Disk used for serialization."""
+        return self._disk
+
+    @property
+    def read_only(self):
+        """True when the cache was opened read-only."""
+        return self._read_only
+
+    def _check_writable(self):
+        if self._read_only:
+            raise ReadOnlyError('cache in %r is read-only' % self._directory)
+
+    @property
+    def _con(self):
+        # Check the process ID to support forking. If it changed, the
+        # connections were inherited from the parent process: forget them
+        # without closing them (see _Connections.discard) and open new ones.
+        # The at-fork handler normally does this before the cache is used.
+
+        if self._cons.pid != os.getpid():
+            self._discard_connections()
+
+        con = getattr(self._local, 'con', None)
+
+        if con is None:
+            con = self._connect()
+
+        return con
+
+    def _connect(self):
+        # check_same_thread=False lets close() and the connection registry
+        # close a connection from a thread other than the one that opened
+        # it, once that thread has exited. Each connection is still used by
+        # one thread at a time, which is all SQLite's multi-thread mode asks.
+
+        path = op.join(self._directory, DBNAME)
+
+        if self._read_only:
+            # mode=ro refuses writes at the SQLite level. A reader of a WAL
+            # database needs to create the -shm file next to it, so when the
+            # directory is not writable immutable=1 skips that file and all
+            # locking, which is safe only because nothing can write there.
+            path = pathlib.Path(op.abspath(path)).as_uri() + '?mode=ro'
+            if not os.access(self._directory, os.W_OK):
+                path += '&immutable=1'
+
+        con = sqlite3.connect(
+            path,
+            timeout=self._timeout,
+            isolation_level=None,
+            check_same_thread=False,
+            uri=self._read_only,
+        )
+        sentinel = _ThreadSentinel()
+        stale = self._cons.add(threading.get_ident(), sentinel, con)
+        self._local.con = con
+        self._local.sentinel = sentinel
+
+        for old in stale:
+            old.close()
+
+        # Some SQLite pragmas work on a per-connection basis so
+        # query the Settings table and reset the pragmas. The
+        # Settings table may not exist so catch and ignore the
+        # OperationalError that may occur.
+
+        try:
+            select = 'SELECT key, value FROM Settings'
+            settings = con.execute(select).fetchall()
+        except sqlite3.OperationalError:
+            pass
+        else:
+            for key, value in settings:
+                if key.startswith('sqlite_'):
+                    self.reset(key, value, update=False)
+
+        return con
+
+    def _close_before_fork(self):
+        # Called in the parent right before fork. Inside a transaction the
+        # connection cannot be closed; forking there is unsupported.
+        if self._txn_id != threading.get_ident():
+            self.close()
+
+    def _discard_connections(self):
+        # In a child process: forget the connections inherited from the
+        # parent without closing them, and start with fresh per-thread state.
+        self._cons.discard()
+        self._local = threading.local()
+        self._txn_id = None
+
+    @property
+    def _sql(self):
+        return self._con.execute
+
+    @property
+    def _sql_retry(self):
+        sql = self._sql
+
+        # 2018-11-01 GrantJ - Some SQLite builds/versions handle
+        # the SQLITE_BUSY return value and connection parameter
+        # "timeout" differently. For a more reliable duration,
+        # manually retry the statement for 60 seconds. Only used
+        # by statements which modify the database and do not use
+        # a transaction (like those in ``__init__`` or ``reset``).
+        # See Issue #85 for and tests/issue_85.py for more details.
+
+        def _execute_with_retry(statement, *args, **kwargs):
+            start = time.time()
+            while True:
+                try:
+                    return sql(statement, *args, **kwargs)
+                except sqlite3.OperationalError as exc:
+                    if str(exc) != 'database is locked':
+                        raise
+                    diff = time.time() - start
+                    if diff > 60:
+                        raise
+                    time.sleep(0.001)
+
+        return _execute_with_retry
+
+    def _triggers_stale(self, sql):
+        # Compare the trigger text stored in sqlite_master with the current
+        # definitions. SQLite stores the statement without IF NOT EXISTS,
+        # with the leading keywords in upper case and the whitespace after
+        # them collapsed, so compare whitespace-normalized text.
+
+        names = tuple(name for name, _ in SETTINGS_TRIGGERS)
+        select = (
+            'SELECT name, sql FROM sqlite_master'
+            " WHERE type = 'trigger' AND name IN (%s)"
+            % ', '.join('?' * len(names))
+        )
+        stored = dict(sql(select, names).fetchall())
+
+        for name, definition in SETTINGS_TRIGGERS:
+            expected = 'CREATE TRIGGER %s %s' % (name, definition)
+            current = ' '.join(stored.get(name, '').split())
+            if current != ' '.join(expected.split()):
+                return True
+
+        return False
+
+    def _update_triggers(self, sql):
+        # Recreate the Settings triggers only when their stored text differs
+        # from SETTINGS_TRIGGERS, as it does in caches written by versions
+        # before 5.7.0 (double-quoted literals, PR #311 and issue #343).
+        # The comparison keeps DDL off the common path: dropping or creating
+        # a trigger bumps the schema cookie, which makes every other
+        # connection re-prepare its statements, and it needs an exclusive
+        # lock on the database. All five triggers are replaced inside one
+        # IMMEDIATE transaction so no writer can observe a missing trigger.
+
+        if not self._triggers_stale(sql):
+            return
+
+        sql('BEGIN IMMEDIATE')
+
+        try:
+            if self._triggers_stale(sql):  # Another opener may have won.
+                for name, definition in SETTINGS_TRIGGERS:
+                    sql('DROP TRIGGER IF EXISTS %s' % name)
+                    sql('CREATE TRIGGER %s %s' % (name, definition))
+            sql('COMMIT')
+        except BaseException:
+            with cl.suppress(sqlite3.OperationalError):
+                sql('ROLLBACK')
+            raise
+
+    @cl.contextmanager
+    def transact(self, retry=False):
+        """Context manager to perform a transaction by locking the cache.
+
+        While the cache is locked, no other write operation is permitted.
+        Transactions should therefore be as short as possible. Read and write
+        operations performed in a transaction are atomic. Read operations may
+        occur concurrent to a transaction.
+
+        Transactions may be nested and may not be shared between threads.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        >>> cache = Cache()
+        >>> with cache.transact():  # Atomically increment two keys.
+        ...     _ = cache.incr('total', 123.4)
+        ...     _ = cache.incr('count', 1)
+        >>> with cache.transact():  # Atomically calculate average.
+        ...     average = cache['total'] / cache['count']
+        >>> average
+        123.4
+
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: context manager for use in `with` statement
+        :raises Timeout: if database timeout occurs
+
+        """
+        with self._transact(retry=retry):
+            yield
+
+    @cl.contextmanager
+    def _transact(self, retry=False, filename=None):
+        with _FORK_GATE:
+            sql = self._sql
+            filenames = []
+            _disk_remove = self._disk.remove
+            tid = threading.get_ident()
+            txn_id = self._txn_id
+
+            if tid == txn_id:
+                begin = False
+            else:
+                # A read-only cache cannot take the reserved lock that
+                # BEGIN IMMEDIATE asks for; its transactions only read.
+                begin_statement = (
+                    'BEGIN' if self._read_only else 'BEGIN IMMEDIATE'
+                )
+
+                while True:
+                    try:
+                        sql(begin_statement)
+                        begin = True
+                        self._txn_id = tid
+                        break
+                    except sqlite3.OperationalError:
+                        if retry:
+                            continue
+                        if filename is not None:
+                            _disk_remove(filename)
+                        raise Timeout from None
+
+            try:
+                yield sql, filenames.append
+            except BaseException as error:
+                if begin:
+                    assert self._txn_id == tid
+                    self._txn_id = None
+                    sql('ROLLBACK')
+                if (
+                    self._read_only
+                    and isinstance(error, sqlite3.OperationalError)
+                    and 'readonly' in str(error)
+                ):
+                    raise ReadOnlyError(
+                        'cache in %r is read-only' % self._directory
+                    ) from error
+                raise
+            else:
+                if begin:
+                    assert self._txn_id == tid
+                    self._txn_id = None
+                    sql('COMMIT')
+                for name in filenames:
+                    if name is not None:
+                        _disk_remove(name)
+
+    def set(self, key, value, expire=None, read=False, tag=None, retry=False):
+        """Set `key` and `value` item in cache.
+
+        When `read` is `True`, `value` should be a file-like object opened
+        for reading in binary mode.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param key: key for item
+        :param value: value for item
+        :param float expire: seconds until item expires
+            (default None, no expiry)
+        :param bool read: read value as bytes from file (default False)
+        :param str tag: text to associate with key (default None)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: True if item was set
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        now = time.time()
+        db_key, raw = self._disk.put(key)
+        expire_time = None if expire is None else now + expire
+        size, mode, filename, db_value = self._disk.store(value, read, key=key)
+        columns = (expire_time, tag, size, mode, filename, db_value)
+
+        # The order of SELECT, UPDATE, and INSERT is important below.
+        #
+        # Typical cache usage pattern is:
+        #
+        # value = cache.get(key)
+        # if value is None:
+        #     value = expensive_calculation()
+        #     cache.set(key, value)
+        #
+        # Cache.get does not evict expired keys to avoid writes during lookups.
+        # Commonly used/expired keys will therefore remain in the cache making
+        # an UPDATE the preferred path.
+        #
+        # The alternative is to assume the key is not present by first trying
+        # to INSERT and then handling the IntegrityError that occurs from
+        # violating the UNIQUE constraint. This optimistic approach was
+        # rejected based on the common cache usage pattern.
+        #
+        # INSERT OR REPLACE aka UPSERT is not used because the old filename may
+        # need cleanup.
+
+        with self._transact(retry, filename) as (sql, cleanup):
+            rows = sql(
+                'SELECT rowid, filename FROM Cache'
+                ' WHERE key = ? AND raw = ?',
+                (db_key, raw),
+            ).fetchall()
+
+            if rows:
+                ((rowid, old_filename),) = rows
+                cleanup(old_filename)
+                self._row_update(rowid, now, columns)
+            else:
+                self._row_insert(db_key, raw, now, columns)
+
+            self._cull(now, sql, cleanup)
+
+            return True
+
+    def __setitem__(self, key, value):
+        """Set corresponding `value` for `key` in cache.
+
+        :param key: key for item
+        :param value: value for item
+        :return: corresponding value
+        :raises KeyError: if key is not found
+
+        """
+        self.set(key, value, retry=True)
+
+    def _row_update(self, rowid, now, columns):
+        sql = self._sql
+        expire_time, tag, size, mode, filename, value = columns
+        sql(
+            'UPDATE Cache SET'
+            ' store_time = ?,'
+            ' expire_time = ?,'
+            ' access_time = ?,'
+            ' access_count = ?,'
+            ' tag = ?,'
+            ' size = ?,'
+            ' mode = ?,'
+            ' filename = ?,'
+            ' value = ?'
+            ' WHERE rowid = ?',
+            (
+                now,  # store_time
+                expire_time,
+                now,  # access_time
+                0,  # access_count
+                tag,
+                size,
+                mode,
+                filename,
+                value,
+                rowid,
+            ),
+        )
+
+    def _row_insert(self, key, raw, now, columns):
+        sql = self._sql
+        expire_time, tag, size, mode, filename, value = columns
+        sql(
+            'INSERT INTO Cache('
+            ' key, raw, store_time, expire_time, access_time,'
+            ' access_count, tag, size, mode, filename, value'
+            ') VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+            (
+                key,
+                raw,
+                now,  # store_time
+                expire_time,
+                now,  # access_time
+                0,  # access_count
+                tag,
+                size,
+                mode,
+                filename,
+                value,
+            ),
+        )
+
+    def _cull(self, now, sql, cleanup, limit=None):
+        cull_limit = self.cull_limit if limit is None else limit
+
+        if cull_limit == 0:
+            return
+
+        # Evict expired keys.
+
+        select_expired_template = (
+            'SELECT %s FROM Cache'
+            ' WHERE expire_time IS NOT NULL AND expire_time < ?'
+            ' ORDER BY expire_time LIMIT ?'
+        )
+
+        select_expired = select_expired_template % 'filename'
+        rows = sql(select_expired, (now, cull_limit)).fetchall()
+
+        if rows:
+            delete_expired = 'DELETE FROM Cache WHERE rowid IN (%s)' % (
+                select_expired_template % 'rowid'
+            )
+            sql(delete_expired, (now, cull_limit))
+
+            for (filename,) in rows:
+                cleanup(filename)
+
+            cull_limit -= len(rows)
+
+            if cull_limit == 0:
+                return
+
+        # Evict keys by policy.
+
+        select_policy = EVICTION_POLICY[self.eviction_policy]['cull']
+
+        if select_policy is None or self.volume() < self.size_limit:
+            return
+
+        select_filename = select_policy.format(fields='filename', now=now)
+        rows = sql(select_filename, (cull_limit,)).fetchall()
+
+        if rows:
+            delete = 'DELETE FROM Cache WHERE rowid IN (%s)' % (
+                select_policy.format(fields='rowid', now=now)
+            )
+            sql(delete, (cull_limit,))
+
+            for (filename,) in rows:
+                cleanup(filename)
+
+    def touch(self, key, expire=None, retry=False):
+        """Touch `key` in cache and update `expire` time.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param key: key for item
+        :param float expire: seconds until item expires
+            (default None, no expiry)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: True if key was touched
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        now = time.time()
+        db_key, raw = self._disk.put(key)
+        expire_time = None if expire is None else now + expire
+
+        with self._transact(retry) as (sql, _):
+            rows = sql(
+                'SELECT rowid, expire_time FROM Cache'
+                ' WHERE key = ? AND raw = ?',
+                (db_key, raw),
+            ).fetchall()
+
+            if rows:
+                ((rowid, old_expire_time),) = rows
+
+                if old_expire_time is None or old_expire_time > now:
+                    sql(
+                        'UPDATE Cache SET expire_time = ? WHERE rowid = ?',
+                        (expire_time, rowid),
+                    )
+                    return True
+
+        return False
+
+    def add(self, key, value, expire=None, read=False, tag=None, retry=False):
+        """Add `key` and `value` item to cache.
+
+        Similar to `set`, but only add to cache if key not present.
+
+        Operation is atomic. Only one concurrent add operation for a given key
+        will succeed.
+
+        When `read` is `True`, `value` should be a file-like object opened
+        for reading in binary mode.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param key: key for item
+        :param value: value for item
+        :param float expire: seconds until the key expires
+            (default None, no expiry)
+        :param bool read: read value as bytes from file (default False)
+        :param str tag: text to associate with key (default None)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: True if item was added
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        now = time.time()
+        db_key, raw = self._disk.put(key)
+        expire_time = None if expire is None else now + expire
+        size, mode, filename, db_value = self._disk.store(value, read, key=key)
+        columns = (expire_time, tag, size, mode, filename, db_value)
+
+        with self._transact(retry, filename) as (sql, cleanup):
+            rows = sql(
+                'SELECT rowid, filename, expire_time FROM Cache'
+                ' WHERE key = ? AND raw = ?',
+                (db_key, raw),
+            ).fetchall()
+
+            if rows:
+                ((rowid, old_filename, old_expire_time),) = rows
+
+                if old_expire_time is None or old_expire_time > now:
+                    cleanup(filename)
+                    return False
+
+                cleanup(old_filename)
+                self._row_update(rowid, now, columns)
+            else:
+                self._row_insert(db_key, raw, now, columns)
+
+            self._cull(now, sql, cleanup)
+
+            return True
+
+    def incr(self, key, delta=1, default=0, retry=False):
+        """Increment value by delta for item with key.
+
+        If key is missing and default is None then raise KeyError. Else if key
+        is missing and default is not None then use default for value.
+
+        Operation is atomic. All concurrent increment operations will be
+        counted individually.
+
+        Assumes value may be stored in a SQLite column. Most builds that target
+        machines with 64-bit pointer widths will support 64-bit signed
+        integers.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param key: key for item
+        :param int delta: amount to increment (default 1)
+        :param int default: value if key is missing (default 0)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: new value for item
+        :raises KeyError: if key is not found and default is None
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        now = time.time()
+        db_key, raw = self._disk.put(key)
+        select = (
+            'SELECT rowid, expire_time, filename, value FROM Cache'
+            ' WHERE key = ? AND raw = ?'
+        )
+
+        with self._transact(retry) as (sql, cleanup):
+            rows = sql(select, (db_key, raw)).fetchall()
+
+            if not rows:
+                if default is None:
+                    raise KeyError(key)
+
+                value = default + delta
+                columns = (None, None) + self._disk.store(
+                    value, False, key=key
+                )
+                self._row_insert(db_key, raw, now, columns)
+                self._cull(now, sql, cleanup)
+                return value
+
+            ((rowid, expire_time, filename, value),) = rows
+
+            if expire_time is not None and expire_time < now:
+                if default is None:
+                    raise KeyError(key)
+
+                value = default + delta
+                columns = (None, None) + self._disk.store(
+                    value, False, key=key
+                )
+                self._row_update(rowid, now, columns)
+                self._cull(now, sql, cleanup)
+                cleanup(filename)
+                return value
+
+            value += delta
+
+            columns = 'store_time = ?, value = ?'
+            update_column = EVICTION_POLICY[self.eviction_policy]['get']
+
+            if update_column is not None:
+                columns += ', ' + update_column.format(now=now)
+
+            update = 'UPDATE Cache SET %s WHERE rowid = ?' % columns
+            sql(update, (now, value, rowid))
+
+            return value
+
+    def decr(self, key, delta=1, default=0, retry=False):
+        """Decrement value by delta for item with key.
+
+        If key is missing and default is None then raise KeyError. Else if key
+        is missing and default is not None then use default for value.
+
+        Operation is atomic. All concurrent decrement operations will be
+        counted individually.
+
+        Unlike Memcached, negative values are supported. Value may be
+        decremented below zero.
+
+        Assumes value may be stored in a SQLite column. Most builds that target
+        machines with 64-bit pointer widths will support 64-bit signed
+        integers.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param key: key for item
+        :param int delta: amount to decrement (default 1)
+        :param int default: value if key is missing (default 0)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: new value for item
+        :raises KeyError: if key is not found and default is None
+        :raises Timeout: if database timeout occurs
+
+        """
+        return self.incr(key, -delta, default, retry)
+
+    def get(
+        self,
+        key,
+        default=None,
+        read=False,
+        expire_time=False,
+        tag=False,
+        retry=False,
+        store_time=False,
+    ):
+        """Retrieve value from cache. If `key` is missing, return `default`.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        When `expire_time`, `tag` or `store_time` is true, the result is a
+        tuple of the value followed by the requested metadata in that order:
+        the expire time and store time as seconds since the epoch, the tag as
+        stored. Metadata is `None` when the key is missing.
+
+        :param key: key for item
+        :param default: value to return if key is missing (default None)
+        :param bool read: if True, return file handle to value
+            (default False)
+        :param bool expire_time: if True, return expire_time in tuple
+            (default False)
+        :param bool tag: if True, return tag in tuple (default False)
+        :param bool retry: retry if database timeout occurs (default False)
+        :param bool store_time: if True, return store_time in tuple
+            (default False)
+        :return: value for item or default if key not found
+        :raises Timeout: if database timeout occurs
+
+        """
+        db_key, raw = self._disk.put(key)
+        update_column = EVICTION_POLICY[self.eviction_policy]['get']
+        statistics = self.statistics
+
+        if self._read_only:
+            # Hits, misses and access times cannot be recorded, so take
+            # the path that does not write.
+            update_column = None
+            statistics = False
+        select = (
+            'SELECT rowid, expire_time, tag, mode, filename, value, store_time'
+            ' FROM Cache WHERE key = ? AND raw = ?'
+            ' AND (expire_time IS NULL OR expire_time > ?)'
+        )
+
+        default = _meta_result(default, expire_time, tag, store_time)
+
+        if not statistics and update_column is None:
+            # Fast path, no transaction necessary.
+
+            rows = self._sql(select, (db_key, raw, time.time())).fetchall()
+
+            if not rows:
+                return default
+
+            (
+                (
+                    rowid,
+                    db_expire_time,
+                    db_tag,
+                    mode,
+                    filename,
+                    db_value,
+                    db_store_time,
+                ),
+            ) = rows
+
+            try:
+                value = self._disk.fetch(mode, filename, db_value, read)
+            except IOError:
+                # Key was deleted before we could retrieve result.
+                return default
+
+        else:  # Slow path, transaction required.
+            cache_hit = (
+                "UPDATE Settings SET value = value + 1 WHERE key = 'hits'"
+            )
+            cache_miss = (
+                "UPDATE Settings SET value = value + 1 WHERE key = 'misses'"
+            )
+
+            with self._transact(retry) as (sql, _):
+                rows = sql(select, (db_key, raw, time.time())).fetchall()
+
+                if not rows:
+                    if statistics:
+                        sql(cache_miss)
+                    return default
+
+                (
+                    (
+                        rowid,
+                        db_expire_time,
+                        db_tag,
+                        mode,
+                        filename,
+                        db_value,
+                        db_store_time,
+                    ),
+                ) = rows
+
+                try:
+                    value = self._disk.fetch(mode, filename, db_value, read)
+                except IOError:
+                    # Key was deleted before we could retrieve result.
+                    if statistics:
+                        sql(cache_miss)
+                    return default
+
+                if statistics:
+                    sql(cache_hit)
+
+                now = time.time()
+                update = 'UPDATE Cache SET %s WHERE rowid = ?'
+
+                if update_column is not None:
+                    sql(update % update_column.format(now=now), (rowid,))
+
+        meta = (db_expire_time, db_tag, db_store_time)
+        return _meta_result(value, expire_time, tag, store_time, meta)
+
+    def __getitem__(self, key):
+        """Return corresponding value for `key` from cache.
+
+        :param key: key matching item
+        :return: corresponding value
+        :raises KeyError: if key is not found
+
+        """
+        value = self.get(key, default=ENOVAL, retry=True)
+        if value is ENOVAL:
+            raise KeyError(key)
+        return value
+
+    def read(self, key, retry=False):
+        """Return file handle value corresponding to `key` from cache.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param key: key matching item
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: file open for reading in binary mode
+        :raises KeyError: if key is not found
+        :raises Timeout: if database timeout occurs
+
+        """
+        handle = self.get(key, default=ENOVAL, read=True, retry=retry)
+        if handle is ENOVAL:
+            raise KeyError(key)
+        return handle
+
+    def __contains__(self, key):
+        """Return `True` if `key` matching item is found in cache.
+
+        :param key: key matching item
+        :return: True if key matching item
+
+        """
+        sql = self._sql
+        db_key, raw = self._disk.put(key)
+        select = (
+            'SELECT rowid FROM Cache'
+            ' WHERE key = ? AND raw = ?'
+            ' AND (expire_time IS NULL OR expire_time > ?)'
+        )
+
+        rows = sql(select, (db_key, raw, time.time())).fetchall()
+
+        return bool(rows)
+
+    def pop(
+        self, key, default=None, expire_time=False, tag=False, retry=False
+    ):  # noqa: E501
+        """Remove corresponding item for `key` from cache and return value.
+
+        If `key` is missing, return `default`.
+
+        Operation is atomic. Concurrent operations will be serialized.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param key: key for item
+        :param default: value to return if key is missing (default None)
+        :param bool expire_time: if True, return expire_time in tuple
+            (default False)
+        :param bool tag: if True, return tag in tuple (default False)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: value for item or default if key not found
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        db_key, raw = self._disk.put(key)
+        select = (
+            'SELECT rowid, expire_time, tag, mode, filename, value'
+            ' FROM Cache WHERE key = ? AND raw = ?'
+            ' AND (expire_time IS NULL OR expire_time > ?)'
+        )
+
+        if expire_time and tag:
+            default = default, None, None
+        elif expire_time or tag:
+            default = default, None
+
+        with self._transact(retry) as (sql, _):
+            rows = sql(select, (db_key, raw, time.time())).fetchall()
+
+            if not rows:
+                return default
+
+            ((rowid, db_expire_time, db_tag, mode, filename, db_value),) = rows
+
+            sql('DELETE FROM Cache WHERE rowid = ?', (rowid,))
+
+        try:
+            value = self._disk.fetch(mode, filename, db_value, False)
+        except IOError:
+            # Key was deleted before we could retrieve result.
+            return default
+        finally:
+            if filename is not None:
+                self._disk.remove(filename)
+
+        if expire_time and tag:
+            return value, db_expire_time, db_tag
+        elif expire_time:
+            return value, db_expire_time
+        elif tag:
+            return value, db_tag
+        else:
+            return value
+
+    def __delitem__(self, key, retry=True):
+        """Delete corresponding item for `key` from cache.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default `True`).
+
+        :param key: key matching item
+        :param bool retry: retry if database timeout occurs (default True)
+        :raises KeyError: if key is not found
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        db_key, raw = self._disk.put(key)
+
+        with self._transact(retry) as (sql, cleanup):
+            rows = sql(
+                'SELECT rowid, filename FROM Cache'
+                ' WHERE key = ? AND raw = ?'
+                ' AND (expire_time IS NULL OR expire_time > ?)',
+                (db_key, raw, time.time()),
+            ).fetchall()
+
+            if not rows:
+                raise KeyError(key)
+
+            ((rowid, filename),) = rows
+            sql('DELETE FROM Cache WHERE rowid = ?', (rowid,))
+            cleanup(filename)
+
+            return True
+
+    def delete(self, key, retry=False):
+        """Delete corresponding item for `key` from cache.
+
+        Missing keys are ignored.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param key: key matching item
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: True if item was deleted
+        :raises Timeout: if database timeout occurs
+
+        """
+        # pylint: disable=unnecessary-dunder-call
+        try:
+            return self.__delitem__(key, retry=retry)
+        except KeyError:
+            return False
+
+    def push(
+        self,
+        value,
+        prefix=None,
+        side='back',
+        expire=None,
+        read=False,
+        tag=None,
+        retry=False,
+    ):
+        """Push `value` onto `side` of queue identified by `prefix` in cache.
+
+        When prefix is None, integer keys are used. Otherwise, string keys are
+        used in the format "prefix-integer". Integer starts at 500 trillion.
+
+        Defaults to pushing value on back of queue. Set side to 'front' to push
+        value on front of queue. Side must be one of 'back' or 'front'.
+
+        Operation is atomic. Concurrent operations will be serialized.
+
+        When `read` is `True`, `value` should be a file-like object opened
+        for reading in binary mode.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        See also `Cache.pull`.
+
+        >>> cache = Cache()
+        >>> print(cache.push('first value'))
+        500000000000000
+        >>> cache.get(500000000000000)
+        'first value'
+        >>> print(cache.push('second value'))
+        500000000000001
+        >>> print(cache.push('third value', side='front'))
+        499999999999999
+        >>> cache.push(1234, prefix='userids')
+        'userids-500000000000000'
+
+        :param value: value for item
+        :param str prefix: key prefix (default None, key is integer)
+        :param str side: either 'back' or 'front' (default 'back')
+        :param float expire: seconds until the key expires
+            (default None, no expiry)
+        :param bool read: read value as bytes from file (default False)
+        :param str tag: text to associate with key (default None)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: key for item in cache
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        if prefix is None:
+            min_key = 0
+            max_key = 999999999999999
+        else:
+            min_key = prefix + '-000000000000000'
+            max_key = prefix + '-999999999999999'
+
+        now = time.time()
+        raw = True
+        expire_time = None if expire is None else now + expire
+        size, mode, filename, db_value = self._disk.store(value, read)
+        columns = (expire_time, tag, size, mode, filename, db_value)
+        order = {'back': 'DESC', 'front': 'ASC'}
+        select = (
+            'SELECT key FROM Cache'
+            ' WHERE ? < key AND key < ? AND raw = ?'
+            ' ORDER BY key %s LIMIT 1'
+        ) % order[side]
+
+        with self._transact(retry, filename) as (sql, cleanup):
+            rows = sql(select, (min_key, max_key, raw)).fetchall()
+
+            if rows:
+                ((key,),) = rows
+
+                if prefix is not None:
+                    num = int(key[(key.rfind('-') + 1) :])
+                else:
+                    num = key
+
+                if side == 'back':
+                    num += 1
+                else:
+                    assert side == 'front'
+                    num -= 1
+            else:
+                num = 500000000000000
+
+            if prefix is not None:
+                db_key = '{0}-{1:015d}'.format(prefix, num)
+            else:
+                db_key = num
+
+            self._row_insert(db_key, raw, now, columns)
+            self._cull(now, sql, cleanup)
+
+            return db_key
+
+    def pull(
+        self,
+        prefix=None,
+        default=(None, None),
+        side='front',
+        expire_time=False,
+        tag=False,
+        retry=False,
+    ):
+        """Pull key and value item pair from `side` of queue in cache.
+
+        When prefix is None, integer keys are used. Otherwise, string keys are
+        used in the format "prefix-integer". Integer starts at 500 trillion.
+
+        If queue is empty, return default.
+
+        Defaults to pulling key and value item pairs from front of queue. Set
+        side to 'back' to pull from back of queue. Side must be one of 'front'
+        or 'back'.
+
+        Operation is atomic. Concurrent operations will be serialized.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        See also `Cache.push` and `Cache.get`.
+
+        >>> cache = Cache()
+        >>> cache.pull()
+        (None, None)
+        >>> for letter in 'abc':
+        ...     print(cache.push(letter))
+        500000000000000
+        500000000000001
+        500000000000002
+        >>> key, value = cache.pull()
+        >>> print(key)
+        500000000000000
+        >>> value
+        'a'
+        >>> _, value = cache.pull(side='back')
+        >>> value
+        'c'
+        >>> cache.push(1234, 'userids')
+        'userids-500000000000000'
+        >>> _, value = cache.pull('userids')
+        >>> value
+        1234
+
+        :param str prefix: key prefix (default None, key is integer)
+        :param default: value to return if key is missing
+            (default (None, None))
+        :param str side: either 'front' or 'back' (default 'front')
+        :param bool expire_time: if True, return expire_time in tuple
+            (default False)
+        :param bool tag: if True, return tag in tuple (default False)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: key and value item pair or default if queue is empty
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        # Caution: Nearly identical code exists in Cache.peek
+        if prefix is None:
+            min_key = 0
+            max_key = 999999999999999
+        else:
+            min_key = prefix + '-000000000000000'
+            max_key = prefix + '-999999999999999'
+
+        order = {'front': 'ASC', 'back': 'DESC'}
+        select = (
+            'SELECT rowid, key, expire_time, tag, mode, filename, value'
+            ' FROM Cache WHERE ? < key AND key < ? AND raw = 1'
+            ' ORDER BY key %s LIMIT 1'
+        ) % order[side]
+
+        if expire_time and tag:
+            default = default, None, None
+        elif expire_time or tag:
+            default = default, None
+
+        while True:
+            while True:
+                with self._transact(retry) as (sql, cleanup):
+                    rows = sql(select, (min_key, max_key)).fetchall()
+
+                    if not rows:
+                        return default
+
+                    (
+                        (rowid, key, db_expire, db_tag, mode, name, db_value),
+                    ) = rows
+
+                    sql('DELETE FROM Cache WHERE rowid = ?', (rowid,))
+
+                    if db_expire is not None and db_expire < time.time():
+                        cleanup(name)
+                    else:
+                        break
+
+            try:
+                value = self._disk.fetch(mode, name, db_value, False)
+            except IOError:
+                # Key was deleted before we could retrieve result.
+                continue
+            finally:
+                if name is not None:
+                    self._disk.remove(name)
+            break
+
+        if expire_time and tag:
+            return (key, value), db_expire, db_tag
+        elif expire_time:
+            return (key, value), db_expire
+        elif tag:
+            return (key, value), db_tag
+        else:
+            return key, value
+
+    def peek(
+        self,
+        prefix=None,
+        default=(None, None),
+        side='front',
+        expire_time=False,
+        tag=False,
+        retry=False,
+    ):
+        """Peek at key and value item pair from `side` of queue in cache.
+
+        When prefix is None, integer keys are used. Otherwise, string keys are
+        used in the format "prefix-integer". Integer starts at 500 trillion.
+
+        If queue is empty, return default.
+
+        Defaults to peeking at key and value item pairs from front of queue.
+        Set side to 'back' to pull from back of queue. Side must be one of
+        'front' or 'back'.
+
+        Expired items are deleted from cache. Operation is atomic. Concurrent
+        operations will be serialized.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        See also `Cache.pull` and `Cache.push`.
+
+        >>> cache = Cache()
+        >>> for letter in 'abc':
+        ...     print(cache.push(letter))
+        500000000000000
+        500000000000001
+        500000000000002
+        >>> key, value = cache.peek()
+        >>> print(key)
+        500000000000000
+        >>> value
+        'a'
+        >>> key, value = cache.peek(side='back')
+        >>> print(key)
+        500000000000002
+        >>> value
+        'c'
+
+        :param str prefix: key prefix (default None, key is integer)
+        :param default: value to return if key is missing
+            (default (None, None))
+        :param str side: either 'front' or 'back' (default 'front')
+        :param bool expire_time: if True, return expire_time in tuple
+            (default False)
+        :param bool tag: if True, return tag in tuple (default False)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: key and value item pair or default if queue is empty
+        :raises Timeout: if database timeout occurs
+
+        """
+        # Caution: Nearly identical code exists in Cache.pull
+        if prefix is None:
+            min_key = 0
+            max_key = 999999999999999
+        else:
+            min_key = prefix + '-000000000000000'
+            max_key = prefix + '-999999999999999'
+
+        order = {'front': 'ASC', 'back': 'DESC'}
+        live = ' AND ' + _LIVE_CONDITION if self._read_only else ''
+        select = (
+            'SELECT rowid, key, expire_time, tag, mode, filename, value'
+            ' FROM Cache WHERE ? < key AND key < ? AND raw = 1%s'
+            ' ORDER BY key %s LIMIT 1'
+        ) % (live, order[side])
+
+        if expire_time and tag:
+            default = default, None, None
+        elif expire_time or tag:
+            default = default, None
+
+        while True:
+            while True:
+                with self._transact(retry) as (sql, cleanup):
+                    rows = sql(select, (min_key, max_key)).fetchall()
+
+                    if not rows:
+                        return default
+
+                    (
+                        (rowid, key, db_expire, db_tag, mode, name, db_value),
+                    ) = rows
+
+                    expired = db_expire is not None and db_expire < time.time()
+
+                    if expired and not self._read_only:
+                        sql('DELETE FROM Cache WHERE rowid = ?', (rowid,))
+                        cleanup(name)
+                    else:
+                        break
+
+            try:
+                value = self._disk.fetch(mode, name, db_value, False)
+            except IOError:
+                # Key was deleted before we could retrieve result.
+                continue
+            break
+
+        if expire_time and tag:
+            return (key, value), db_expire, db_tag
+        elif expire_time:
+            return (key, value), db_expire
+        elif tag:
+            return (key, value), db_tag
+        else:
+            return key, value
+
+    def peekitem(self, last=True, expire_time=False, tag=False, retry=False):
+        """Peek at key and value item pair in cache based on iteration order.
+
+        Expired items are deleted from cache. Operation is atomic. Concurrent
+        operations will be serialized.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        >>> cache = Cache()
+        >>> for num, letter in enumerate('abc'):
+        ...     cache[letter] = num
+        >>> cache.peekitem()
+        ('c', 2)
+        >>> cache.peekitem(last=False)
+        ('a', 0)
+
+        :param bool last: last item in iteration order (default True)
+        :param bool expire_time: if True, return expire_time in tuple
+            (default False)
+        :param bool tag: if True, return tag in tuple (default False)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: key and value item pair
+        :raises KeyError: if cache is empty
+        :raises Timeout: if database timeout occurs
+
+        """
+        order = ('ASC', 'DESC')
+        live = ' WHERE ' + _LIVE_CONDITION if self._read_only else ''
+        select = (
+            'SELECT rowid, key, raw, expire_time, tag, mode, filename, value'
+            ' FROM Cache%s ORDER BY rowid %s LIMIT 1'
+        ) % (live, order[last])
+
+        while True:
+            while True:
+                with self._transact(retry) as (sql, cleanup):
+                    rows = sql(select).fetchall()
+
+                    if not rows:
+                        raise KeyError('dictionary is empty')
+
+                    (
+                        (
+                            rowid,
+                            db_key,
+                            raw,
+                            db_expire,
+                            db_tag,
+                            mode,
+                            name,
+                            db_value,
+                        ),
+                    ) = rows
+
+                    expired = db_expire is not None and db_expire < time.time()
+
+                    if expired and not self._read_only:
+                        sql('DELETE FROM Cache WHERE rowid = ?', (rowid,))
+                        cleanup(name)
+                    else:
+                        break
+
+            key = self._disk.get(db_key, raw)
+
+            try:
+                value = self._disk.fetch(mode, name, db_value, False)
+            except IOError:
+                # Key was deleted before we could retrieve result.
+                continue
+            break
+
+        if expire_time and tag:
+            return (key, value), db_expire, db_tag
+        elif expire_time:
+            return (key, value), db_expire
+        elif tag:
+            return (key, value), db_tag
+        else:
+            return key, value
+
+    def memoize(
+        self, name=None, typed=False, expire=None, tag=None, ignore=()
+    ):
+        """Memoizing cache decorator.
+
+        Decorator to wrap callable with memoizing function using cache.
+        Repeated calls with the same arguments will lookup result in cache and
+        avoid function evaluation.
+
+        If name is set to None (default), the callable name will be determined
+        automatically.
+
+        When expire is set to zero, function results will not be set in the
+        cache. Cache lookups still occur, however. Read
+        :doc:`case-study-landing-page-caching` for example usage.
+
+        If typed is set to True, function arguments of different types will be
+        cached separately. For example, f(3) and f(3.0) will be treated as
+        distinct calls with distinct results.
+
+        The original underlying function is accessible through the __wrapped__
+        attribute. This is useful for introspection, for bypassing the cache,
+        or for rewrapping the function with a different cache.
+
+        >>> from diskcache import Cache
+        >>> cache = Cache()
+        >>> @cache.memoize(expire=1, tag='fib')
+        ... def fibonacci(number):
+        ...     if number == 0:
+        ...         return 0
+        ...     elif number == 1:
+        ...         return 1
+        ...     else:
+        ...         return fibonacci(number - 1) + fibonacci(number - 2)
+        >>> print(fibonacci(100))
+        354224848179261915075
+
+        An additional `__cache_key__` attribute can be used to generate the
+        cache key used for the given arguments.
+
+        >>> key = fibonacci.__cache_key__(100)
+        >>> print(cache[key])
+        354224848179261915075
+
+        Remember to call memoize when decorating a callable. If you forget,
+        then a TypeError will occur. Note the lack of parenthenses after
+        memoize below:
+
+        >>> @cache.memoize
+        ... def test():
+        ...     pass
+        Traceback (most recent call last):
+            ...
+        TypeError: name cannot be callable
+
+        :param cache: cache to store callable arguments and return values
+        :param str name: name given for callable (default None, automatic)
+        :param bool typed: cache different types separately (default False)
+        :param float expire: seconds until arguments expire
+            (default None, no expiry)
+        :param str tag: text to associate with arguments (default None)
+        :param set ignore: positional or keyword args to ignore (default ());
+            an int ignores the argument at that position, a str ignores
+            the parameter with that name however it is passed
+        :return: callable decorator
+
+        """
+        # Caution: Nearly identical code exists in DjangoCache.memoize
+        if callable(name):
+            raise TypeError('name cannot be callable')
+
+        def decorator(func):
+            """Decorator created by memoize() for callable `func`."""
+            base = (full_name(func),) if name is None else (name,)
+            ignored = resolve_ignore(func, ignore)
+
+            @ft.wraps(func)
+            def wrapper(*args, **kwargs):
+                """Wrapper for callable to cache arguments and return values."""
+                key = wrapper.__cache_key__(*args, **kwargs)
+                result = self.get(key, default=ENOVAL, retry=True)
+
+                if result is ENOVAL:
+                    result = func(*args, **kwargs)
+                    if expire is None or expire > 0:
+                        self.set(key, result, expire, tag=tag, retry=True)
+
+                return result
+
+            def __cache_key__(*args, **kwargs):
+                """Make key for cache given function arguments."""
+                return args_to_key(base, args, kwargs, typed, ignored)
+
+            wrapper.__cache_key__ = __cache_key__
+            return wrapper
+
+        return decorator
+
+    def check(self, fix=False, retry=False):
+        """Check database and file system consistency.
+
+        Intended for use in testing and post-mortem error analysis.
+
+        While checking the Cache table for consistency, a writer lock is held
+        on the database. The lock blocks other cache clients from writing to
+        the database. For caches with many file references, the lock may be
+        held for a long time. For example, local benchmarking shows that a
+        cache with 1,000 file references takes ~60ms to check.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param bool fix: correct inconsistencies
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: list of warnings
+        :raises Timeout: if database timeout occurs
+
+        """
+        if fix:
+            self._check_writable()
+        # pylint: disable=access-member-before-definition,W0201
+        with warnings.catch_warnings(record=True) as warns:
+            sql = self._sql
+
+            # Check integrity of database.
+
+            rows = sql('PRAGMA integrity_check').fetchall()
+
+            if len(rows) != 1 or rows[0][0] != 'ok':
+                for (message,) in rows:
+                    warnings.warn(message)
+
+            if fix:
+                sql('VACUUM')
+
+            with self._transact(retry) as (sql, _):
+
+                # Check Cache.filename against file system.
+
+                filenames = set()
+                select = (
+                    'SELECT rowid, size, filename FROM Cache'
+                    ' WHERE filename IS NOT NULL'
+                )
+
+                rows = sql(select).fetchall()
+
+                for rowid, size, filename in rows:
+                    full_path = op.join(
+                        self._directory, native_filename(filename)
+                    )
+                    filenames.add(full_path)
+
+                    if op.exists(full_path):
+                        real_size = op.getsize(full_path)
+
+                        if size != real_size:
+                            message = 'wrong file size: %s, %d != %d'
+                            args = full_path, real_size, size
+                            warnings.warn(message % args)
+
+                            if fix:
+                                sql(
+                                    'UPDATE Cache SET size = ?'
+                                    ' WHERE rowid = ?',
+                                    (real_size, rowid),
+                                )
+
+                        continue
+
+                    warnings.warn('file not found: %s' % full_path)
+
+                    if fix:
+                        sql('DELETE FROM Cache WHERE rowid = ?', (rowid,))
+
+                # Check file system against Cache.filename.
+
+                for dirpath, _, files in os.walk(self._directory):
+                    paths = [op.join(dirpath, filename) for filename in files]
+                    error = set(paths) - filenames
+
+                    for full_path in error:
+                        if DBNAME in full_path:
+                            continue
+
+                        message = 'unknown file: %s' % full_path
+                        warnings.warn(message, UnknownFileWarning)
+
+                        if fix:
+                            os.remove(full_path)
+
+                # Check for empty directories.
+
+                for dirpath, dirs, files in os.walk(self._directory):
+                    if not (dirs or files):
+                        message = 'empty directory: %s' % dirpath
+                        warnings.warn(message, EmptyDirWarning)
+
+                        if fix:
+                            os.rmdir(dirpath)
+
+                # Check Settings.count against count of Cache rows.
+
+                self.reset('count')
+                ((count,),) = sql('SELECT COUNT(key) FROM Cache').fetchall()
+
+                if self.count != count:
+                    message = 'Settings.count != COUNT(Cache.key); %d != %d'
+                    warnings.warn(message % (self.count, count))
+
+                    if fix:
+                        sql(
+                            'UPDATE Settings SET value = ? WHERE key = ?',
+                            (count, 'count'),
+                        )
+
+                # Check Settings.size against sum of Cache.size column.
+
+                self.reset('size')
+                select_size = 'SELECT COALESCE(SUM(size), 0) FROM Cache'
+                ((size,),) = sql(select_size).fetchall()
+
+                if self.size != size:
+                    message = 'Settings.size != SUM(Cache.size); %d != %d'
+                    warnings.warn(message % (self.size, size))
+
+                    if fix:
+                        sql(
+                            'UPDATE Settings SET value = ? WHERE key =?',
+                            (size, 'size'),
+                        )
+
+            return warns
+
+    def create_tag_index(self):
+        """Create tag index on cache database.
+
+        It is better to initialize cache with `tag_index=True` than use this.
+
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        sql = self._sql
+        sql(
+            'CREATE INDEX IF NOT EXISTS Cache_tag_rowid ON Cache(tag, rowid) '
+            'WHERE tag IS NOT NULL'
+        )
+        self.reset('tag_index', 1)
+
+    def drop_tag_index(self):
+        """Drop tag index on cache database.
+
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        sql = self._sql
+        sql('DROP INDEX IF EXISTS Cache_tag_rowid')
+        self.reset('tag_index', 0)
+
+    def evict(self, tag, retry=False):
+        """Remove items with matching `tag` from cache.
+
+        Removing items is an iterative process. In each iteration, a subset of
+        items is removed. Concurrent writes may occur between iterations.
+
+        If a :exc:`Timeout` occurs, the first element of the exception's
+        `args` attribute will be the number of items removed before the
+        exception occurred.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param str tag: tag identifying items
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: count of rows removed
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        select = (
+            'SELECT rowid, filename FROM Cache'
+            ' WHERE tag = ? AND rowid > ?'
+            ' ORDER BY rowid LIMIT ?'
+        )
+        args = [tag, 0, 100]
+        return self._select_delete(select, args, arg_index=1, retry=retry)
+
+    def expire(self, now=None, retry=False):
+        """Remove expired items from cache.
+
+        Removing items is an iterative process. In each iteration, a subset of
+        items is removed. Concurrent writes may occur between iterations.
+
+        If a :exc:`Timeout` occurs, the first element of the exception's
+        `args` attribute will be the number of items removed before the
+        exception occurred.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param float now: current time (default None, ``time.time()`` used)
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: count of items removed
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        select = (
+            'SELECT rowid, expire_time, filename FROM Cache'
+            ' WHERE ? < expire_time AND expire_time < ?'
+            ' ORDER BY expire_time LIMIT ?'
+        )
+        args = [0, now or time.time(), 100]
+        return self._select_delete(select, args, row_index=1, retry=retry)
+
+    def cull(self, retry=False):
+        """Cull items from cache until volume is less than size limit.
+
+        Removing items is an iterative process. In each iteration, a subset of
+        items is removed. Concurrent writes may occur between iterations.
+
+        If a :exc:`Timeout` occurs, the first element of the exception's
+        `args` attribute will be the number of items removed before the
+        exception occurred.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: count of items removed
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        now = time.time()
+
+        # Remove expired items.
+
+        count = self.expire(now)
+
+        # Remove items by policy.
+
+        select_policy = EVICTION_POLICY[self.eviction_policy]['cull']
+
+        if select_policy is None:
+            return 0
+
+        select_filename = select_policy.format(fields='filename', now=now)
+
+        try:
+            while self.volume() > self.size_limit:
+                with self._transact(retry) as (sql, cleanup):
+                    rows = sql(select_filename, (10,)).fetchall()
+
+                    if not rows:
+                        break
+
+                    count += len(rows)
+                    delete = (
+                        'DELETE FROM Cache WHERE rowid IN (%s)'
+                        % select_policy.format(fields='rowid', now=now)
+                    )
+                    sql(delete, (10,))
+
+                    for (filename,) in rows:
+                        cleanup(filename)
+        except Timeout:
+            raise Timeout(count) from None
+
+        return count
+
+    def clear(self, retry=False):
+        """Remove all items from cache.
+
+        Removing items is an iterative process. In each iteration, a subset of
+        items is removed. Concurrent writes may occur between iterations.
+
+        If a :exc:`Timeout` occurs, the first element of the exception's
+        `args` attribute will be the number of items removed before the
+        exception occurred.
+
+        Raises :exc:`Timeout` error when database timeout occurs and `retry` is
+        `False` (default).
+
+        :param bool retry: retry if database timeout occurs (default False)
+        :return: count of rows removed
+        :raises Timeout: if database timeout occurs
+
+        """
+        self._check_writable()
+        select = (
+            'SELECT rowid, filename FROM Cache'
+            ' WHERE rowid > ?'
+            ' ORDER BY rowid LIMIT ?'
+        )
+        args = [0, 100]
+        return self._select_delete(select, args, retry=retry)
+
+    def _select_delete(
+        self, select, args, row_index=0, arg_index=0, retry=False
+    ):
+        count = 0
+        delete = 'DELETE FROM Cache WHERE rowid IN (%s)'
+
+        try:
+            while True:
+                with self._transact(retry) as (sql, cleanup):
+                    rows = sql(select, args).fetchall()
+
+                    if not rows:
+                        break
+
+                    count += len(rows)
+                    sql(delete % ','.join(str(row[0]) for row in rows))
+
+                    for row in rows:
+                        args[arg_index] = row[row_index]
+                        cleanup(row[-1])
+
+        except Timeout:
+            raise Timeout(count) from None
+
+        return count
+
+    def iterkeys(self, reverse=False, tag=ENOVAL):
+        """Iterate Cache keys in database sort order.
+
+        >>> cache = Cache()
+        >>> for key in [4, 1, 3, 0, 2]:
+        ...     cache[key] = key
+        >>> list(cache.iterkeys())
+        [0, 1, 2, 3, 4]
+        >>> list(cache.iterkeys(reverse=True))
+        [4, 3, 2, 1, 0]
+
+        If `tag` is given, only keys with a matching tag are returned. Use
+        ``tag=None`` to iterate untagged keys. Omitting `tag` returns all keys.
+        Iteration includes expired items and does not read cached values.
+
+        :param bool reverse: reverse sort order (default False)
+        :param tag: tag to match (default ENOVAL, matching all tags)
+        :return: iterator of Cache keys
+
+        """
+        sql = self._sql
+        limit = 100
+        _disk_get = self._disk.get
+        select = 'SELECT key, raw FROM Cache'
+        args = ()
+
+        if tag is None:
+            select += ' WHERE tag IS NULL'
+        elif tag is not ENOVAL:
+            select += ' WHERE tag = ?'
+            args = (tag,)
+
+        iterate = select + (' WHERE (' if tag is ENOVAL else ' AND (')
+
+        if reverse:
+            iterate += 'key = ? AND raw < ? OR key < ?)'
+            order = ' ORDER BY key DESC, raw DESC'
+        else:
+            iterate += 'key = ? AND raw > ? OR key > ?)'
+            order = ' ORDER BY key ASC, raw ASC'
+
+        select += order + ' LIMIT 1'
+        iterate += order + ' LIMIT ?'
+        row = sql(select, args).fetchall()
+
+        if row:
+            ((key, raw),) = row
+        else:
+            return
+
+        yield _disk_get(key, raw)
+
+        while True:
+            rows = sql(iterate, args + (key, raw, key, limit)).fetchall()
+
+            if not rows:
+                break
+
+            for key, raw in rows:
+                yield _disk_get(key, raw)
+
+    def _iter(self, ascending=True):
+        sql = self._sql
+        rows = sql('SELECT MAX(rowid) FROM Cache').fetchall()
+        ((max_rowid,),) = rows
+        yield  # Signal ready.
+
+        if max_rowid is None:
+            return
+
+        bound = max_rowid + 1
+        limit = 100
+        _disk_get = self._disk.get
+        rowid = 0 if ascending else bound
+        select = (
+            'SELECT rowid, key, raw FROM Cache'
+            ' WHERE ? < rowid AND rowid < ?'
+            ' ORDER BY rowid %s LIMIT ?'
+        ) % ('ASC' if ascending else 'DESC')
+
+        while True:
+            if ascending:
+                args = (rowid, bound, limit)
+            else:
+                args = (0, rowid, limit)
+
+            rows = sql(select, args).fetchall()
+
+            if not rows:
+                break
+
+            for rowid, key, raw in rows:
+                yield _disk_get(key, raw)
+
+    def __iter__(self):
+        """Iterate keys in cache including expired items."""
+        iterator = self._iter()
+        next(iterator)
+        return iterator
+
+    def __reversed__(self):
+        """Reverse iterate keys in cache including expired items."""
+        iterator = self._iter(ascending=False)
+        next(iterator)
+        return iterator
+
+    def stats(self, enable=True, reset=False):
+        """Return cache statistics hits and misses.
+
+        :param bool enable: enable collecting statistics (default True)
+        :param bool reset: reset hits and misses to 0 (default False)
+        :return: (hits, misses)
+
+        """
+        # pylint: disable=E0203,W0201
+        result = (self.reset('hits'), self.reset('misses'))
+
+        if self._read_only:
+            # Counters cannot be reset or enabled on a read-only cache.
+            return result
+
+        if reset:
+            self.reset('hits', 0)
+            self.reset('misses', 0)
+
+        self.reset('statistics', enable)
+
+        return result
+
+    def volume(self):
+        """Return estimated total size of cache on disk.
+
+        :return: size in bytes
+
+        """
+        ((page_count,),) = self._sql('PRAGMA page_count').fetchall()
+        total_size = self._page_size * page_count + self.reset('size')
+        return total_size
+
+    def close(self):
+        """Close database connection.
+
+        Closes the connection opened by the calling thread and the
+        connections of threads that have exited. Connections that other
+        live threads use stay open. The cache reconnects on next use.
+
+        """
+        if self._cons.pid != os.getpid():
+            self._discard_connections()
+            return
+
+        local = self._local
+        con = getattr(local, 'con', None)
+        cons = self._cons.pop(threading.get_ident())
+
+        if con is not None and con not in cons:
+            cons.append(con)
+
+        for name in ('con', 'sentinel'):
+            try:
+                delattr(local, name)
+            except AttributeError:
+                pass
+
+        for con in cons:
+            con.close()
+
+    def __enter__(self):
+        # Create connection in thread.
+        # pylint: disable=unused-variable
+        connection = self._con  # noqa
+        return self
+
+    def __exit__(self, *exception):
+        self.close()
+
+    def __len__(self):
+        """Count of items in cache including expired items."""
+        return self.reset('count')
+
+    def __getstate__(self):
+        return (self.directory, self.timeout, type(self.disk))
+
+    def __setstate__(self, state):
+        self.__init__(*state)
+
+    def reset(self, key, value=ENOVAL, update=True):
+        """Reset `key` and `value` item from Settings table.
+
+        Use `reset` to update the value of Cache settings correctly. Cache
+        settings are stored in the Settings table of the SQLite database. If
+        `update` is ``False`` then no attempt is made to update the database.
+
+        If `value` is not given, it is reloaded from the Settings
+        table. Otherwise, the Settings table is updated.
+
+        Settings with the ``disk_`` prefix correspond to Disk
+        attributes. Updating the value will change the unprefixed attribute on
+        the associated Disk instance.
+
+        Settings with the ``sqlite_`` prefix correspond to SQLite
+        pragmas. Updating the value will execute the corresponding PRAGMA
+        statement.
+
+        SQLite PRAGMA statements may be executed before the Settings table
+        exists in the database by setting `update` to ``False``.
+
+        :param str key: Settings key for item
+        :param value: value for item (optional)
+        :param bool update: update database Settings table (default True)
+        :return: updated value for item
+        :raises Timeout: if database timeout occurs
+
+        """
+        sql = self._sql
+        sql_retry = self._sql_retry
+
+        if value is ENOVAL:
+            select = 'SELECT value FROM Settings WHERE key = ?'
+            rows = sql_retry(select, (key,)).fetchall()
+            if not rows and self._read_only and key in METADATA:
+                value = METADATA[key]  # A snapshot without counters.
+            else:
+                ((value,),) = rows
+            setattr(self, key, value)
+            return value
+
+        if update:
+            self._check_writable()
+            statement = 'UPDATE Settings SET value = ? WHERE key = ?'
+            sql_retry(statement, (value, key))
+
+        if key.startswith('sqlite_'):
+            pragma = key[7:]
+
+            if self._read_only and pragma in _PERSISTENT_PRAGMAS:
+                # Stored in the file; a read-only cache takes what is there.
+                setattr(self, key, value)
+                return value
+
+            # 2016-02-17 GrantJ - PRAGMA and isolation_level=None
+            # don't always play nicely together. Retry setting the
+            # PRAGMA. I think some PRAGMA statements expect to
+            # immediately take an EXCLUSIVE lock on the database. I
+            # can't find any documentation for this but without the
+            # retry, stress will intermittently fail with multiple
+            # processes.
+
+            # 2018-11-05 GrantJ - Avoid setting pragma values that
+            # are already set. Pragma settings like auto_vacuum and
+            # journal_mode can take a long time or may not work after
+            # tables have been created.
+
+            start = time.time()
+            while True:
+                try:
+                    try:
+                        ((old_value,),) = sql(
+                            'PRAGMA %s' % (pragma)
+                        ).fetchall()
+                        update = old_value != value
+                    except ValueError:
+                        update = True
+                    if update:
+                        sql('PRAGMA %s = %s' % (pragma, value)).fetchall()
+                    break
+                except sqlite3.OperationalError as exc:
+                    if str(exc) != 'database is locked':
+                        raise
+                    diff = time.time() - start
+                    if diff > 60:
+                        raise
+                    time.sleep(0.001)
+        elif key.startswith('disk_'):
+            attr = key[5:]
+            setattr(self._disk, attr, value)
+
+        setattr(self, key, value)
+        return value