API Reference

The public API of diskcache-oxide: Cache, FanoutCache, NullCache, the CacheLike, TransactionalCacheLike and ShardedCacheLike protocols, the Caches registry, exceptions, and SQLite utilities.

Cache

Disk-backed cache backed by SQLite, shared safely across threads and processes.

Cache: A disk cache backed by SQLite, shared safely across threads and processes.

Cache Methods

Methods for the Cache class

Cache.directory: The cache directory, as given to the constructor.
Cache.timeout: Seconds a call waits for a lock or a pending fork before raising Timeout.
Cache.size_limit: The disk budget in bytes. A set() that finds the cache over it evicts entries.
Cache.cull_limit: The most entries a single set() evicts when the cache is over size_limit.
Cache.enabled: Always True for a real cache; False for a NullCache.
Cache.set(): Store value under key, replacing any existing value.
Cache.add(): Store value only if key is missing or expired.
Cache.delete(): Remove key.
Cache.pop(): Remove key and return its value, delivering it to exactly one caller.
Cache.touch(): Change the expiry of an existing entry without rewriting its value.
Cache.incr(): Add delta to the number stored under key, atomically, and return the result.
Cache.decr(): Subtract delta from the number stored under key, atomically. See incr().
Cache.iterkeys(): Iterate over keys in sorted order, optionally only those starting with prefix.
Cache.expire(): Remove every expired entry, and its value file.
Cache.clear(): Remove every entry that existed when the call started.
Cache.cull(): Remove expired entries, then evict the least recently stored until under size_limit.
Cache.volume(): The cache’s size on disk in bytes: the database plus value files.
Cache.checkpoint(): Copy the write-ahead log into the database and truncate it to zero.
Cache.close(): Close this handle and return its connections.
Cache.transact(): A write transaction, for with cache.transact() as tx:.
Cache.__getitem__(): cache[key]: the value, or KeyError if it’s missing or expired, or the read failed under
Cache.__setitem__(): cache[key] = value: store a value that never expires, like set(). Under durable=True a failed write is
Cache.__delitem__(): del cache[key]: remove the entry, or raise KeyError if it’s missing or expired, or the delete failed
Cache.__contains__(): key in cache: True if the key holds a live (unexpired) value. False if the check failed under
Cache.__len__(): The number of entries, including expired entries not yet removed.
Cache.__bool__(): Always True, even when empty, so if cache: means “caching is on”.
Cache.__iter__(): Iterate over keys in insertion order. An overwrite keeps its key’s place.
Cache.__enter__(): Return the cache, for with Cache(...) as cache:.
Cache.__exit__(): Close the cache, as close() does.
Cache.get(): Return the value stored for key, or default if it’s missing or expired.

FanoutCache

A cache sharded over several SQLite databases, so writers in many processes stop queueing on one write lock.

FanoutCache: A disk cache split over several SQLite databases (shards), so reads and writes on different keys

FanoutCache Methods

Methods for the FanoutCache class

FanoutCache.directory: The root directory, as given to the constructor.
FanoutCache.timeout: Seconds a call waits for a lock or a pending fork before raising Timeout.
FanoutCache.shards: How many shards the root has.
FanoutCache.size_limit: The disk budget in bytes: the sum of every shard’s.
FanoutCache.cull_limit: The most entries a single set() evicts from its shard when that shard is over its share.
FanoutCache.enabled: Always True for a real cache; False for a NullCache.
FanoutCache.shard_of(): The shard key lives in, from 0 to shards - 1: the same in every process and release.
FanoutCache.transact(): A write transaction on the shard key lives in, for with cache.transact(key='total') as tx:.
FanoutCache.set(): As Cache.set, on the key’s shard.
FanoutCache.add(): As Cache.add, on the key’s shard: atomic across threads and processes.
FanoutCache.delete(): As Cache.delete, on the key’s shard.
FanoutCache.pop(): As Cache.pop, on the key’s shard.
FanoutCache.touch(): As Cache.touch, on the key’s shard.
FanoutCache.incr(): As Cache.incr, on the key’s shard: atomic across threads and processes.
FanoutCache.decr(): As Cache.decr, on the key’s shard.
FanoutCache.volume(): The total disk use in bytes of every shard (databases plus value files).
FanoutCache.expire(): Remove every expired entry from every shard, and its value file, as Cache.expire does.
FanoutCache.clear(): Remove every entry that existed when the call started, from every shard.
FanoutCache.cull(): Remove expired entries, then evict the least recently stored from each shard until it’s
FanoutCache.checkpoint(): Checkpoint every shard’s write-ahead log and truncate it to zero, as Cache.checkpoint does.
FanoutCache.iterkeys(): Iterate over keys in sorted order, optionally only those starting with prefix.
FanoutCache.__iter__(): Iterate over every key once: shard 0’s in insertion order, then shard 1’s, and so on.
FanoutCache.close(): Close this handle on every shard, as Cache.close() does for one.
FanoutCache.__getitem__(): cache[key], as on Cache.
FanoutCache.__setitem__(): cache[key] = value, as on Cache.
FanoutCache.__delitem__(): del cache[key], as on Cache.
FanoutCache.__contains__(): key in cache, as on Cache.
FanoutCache.__len__(): The number of entries in every shard, including expired entries not yet removed.
FanoutCache.__bool__(): Always True, even when empty, so if cache: means “caching is on”.
FanoutCache.__enter__(): Return the cache, for with FanoutCache(...) as cache:.
FanoutCache.__exit__(): Close the cache, as close() does.
FanoutCache.get(): As Cache.get, on the key’s shard.

NullCache

Switched-off cache behaving as if every entry expires instantly.

NullCache: A switched-off cache, so app code needs no if cache is None checks.
CacheLike: What application code can rely on from a Cache, a FanoutCache or a NullCache.
TransactionalCacheLike: A CacheLike with transact(), which Cache and NullCache both have.
ShardedCacheLike: A CacheLike with a sharded cache’s transact(*, key, retry=False), which FanoutCache and

NullCache Methods

Methods for the NullCache class

NullCache.__repr__(): Shows the directory and any invalidate= cache.
NullCache.directory: The directory passed to the constructor, or None. Nothing is created there.
NullCache.timeout: The timeout passed to the constructor (default 60). Unused.
NullCache.size_limit: The size limit passed to the constructor (default 1 GiB). Unused.
NullCache.cull_limit: The cull limit passed to the constructor (default 10). Unused.
NullCache.enabled: Always False: caching is off.
NullCache.get(): Return default, as every entry has already expired. With expire_time=True, (default, None).
NullCache.__getitem__(): Always raises KeyError, as every entry has already expired.
NullCache.__contains__(): Always False.
NullCache.__len__(): Always 0.
NullCache.__bool__(): Always False, so if cache: means “caching is on”.
NullCache.__iter__(): Yields nothing.
NullCache.volume(): Always 0: a NullCache uses no disk.
NullCache.checkpoint(): Always True: there is no write-ahead log to reset.
NullCache.set(): Return True without storing anything: the write succeeds, then expires instantly.
NullCache.__setitem__(): Store nothing, as set() does.
NullCache.add(): Return True without storing anything: the key is always absent, so the add succeeds.
NullCache.touch(): Always False: the key never exists.
NullCache.incr(): Return default + delta, since every count starts again from default.
NullCache.decr(): Return default - delta. See incr().
NullCache.delete(): False, or with invalidate=, delete the key from that cache and return its result.
NullCache.__delitem__(): Raise KeyError, or with invalidate=, delete the key from that cache.
NullCache.pop(): Return default. With invalidate=, also delete the key from that cache.
NullCache.clear(): 0, or with invalidate=, clear that cache (passing timeout on) and return its count.
NullCache.iterkeys(): Yield nothing, or with invalidate=, that cache’s keys, so list-then-delete still works.
NullCache.transact(): A no-op context manager that yields this NullCache.
NullCache.expire(): Always 0.
NullCache.cull(): Always 0.
NullCache.close(): Do nothing. An invalidate= cache is never closed: it belongs to whoever created it.
NullCache.__enter__(): Return the cache, for with NullCache() as cache:.
NullCache.__exit__(): Do nothing, as close() does.

CacheLike Methods

Methods for the CacheLike class

CacheLike.directory: The cache directory (None for a NullCache created without one).
CacheLike.timeout: Seconds a write waits for another process’s lock before raising Timeout.
CacheLike.size_limit: The disk budget in bytes.
CacheLike.cull_limit: The most entries one set() evicts when over size_limit.
CacheLike.enabled: True if caching is on (Cache), False if it’s off (NullCache).
CacheLike.get(): Return the value for key, or default if it’s missing or expired.
CacheLike.set(): Store value under key, with an optional expiry in seconds.
CacheLike.add(): Store value only if key is missing or expired. True if it was stored.
CacheLike.delete(): Remove key. True if a live entry was removed.
CacheLike.pop(): Remove key and return its value, or default.
CacheLike.touch(): Change an existing entry’s expiry. True if the entry existed.
CacheLike.incr(): Add delta to the number under key, atomically, and return the result.
CacheLike.decr(): Subtract delta from the number under key, atomically, and return the result.
CacheLike.iterkeys(): Iterate over keys in sorted order, optionally only those starting with prefix.
CacheLike.expire(): Remove every expired entry. Returns how many were removed.
CacheLike.clear(): Remove every entry that existed when the call started. Returns how many.
CacheLike.cull(): Remove expired entries, then evict until under size_limit. Returns how many.
CacheLike.volume(): The size on disk in bytes.
CacheLike.checkpoint(): Empty the write-ahead log. True if it was reset, False if other processes kept it busy.
CacheLike.close(): Close this handle and return its connections.
CacheLike.__getitem__(): cache[key]: the value, or KeyError if it’s missing or expired.
CacheLike.__setitem__(): cache[key] = value: store a value that never expires.
CacheLike.__delitem__(): del cache[key]: remove the entry, or raise KeyError.
CacheLike.__contains__(): key in cache: True if the key holds a live value.
CacheLike.__len__(): The number of entries.
CacheLike.__bool__(): True if caching is on, so if cache: reads naturally.
CacheLike.__iter__(): Iterate over every key once. A Cache yields them in insertion order.
CacheLike.__enter__(): Return the cache, for use in a with block.
CacheLike.__exit__(): Close the cache.

Caches

A registry of named caches under one base directory.

Caches: A registry of named caches under one base directory.
CacheStats: One cache’s numbers, for an admin page. error says why it couldn’t be read, if it couldn’t.

Caches Methods

Methods for the Caches class

Caches.__repr__(): Shows the base directory and the registered names.
Caches.register(): Register a cache. Nothing opens until its first lookup.
Caches.__contains__(): Whether name is registered.
Caches.__iter__(): The registered names, in registration order.
Caches.__len__(): How many caches are registered.
Caches.directory(): Where the named cache lives.
Caches.__getitem__(): The named plain cache: opened on first use, then the same object every time.
Caches.fanout(): The named sharded cache (one registered with shards=), looked up as caches[name] is.
Caches.disable(): Later lookups of these caches return NullCache(invalidate=real).
Caches.enable(): Later lookups of these caches return the real cache again.
Caches.enabled(): Whether lookups of this cache return the real one (it may still fail to open).
Caches.stats(): Count and volume for every registered cache, opening each one. Never raises for a cache
Caches.clear(): Clear the real cache, even while it’s disabled. Returns how many entries were removed.
Caches.expire_all(): Remove expired entries from every cache. Returns how many each removed, or None for a
Caches.close_all(): Close every opened cache and forget it; a later lookup opens it again.
Caches.__enter__(): Return the registry, for with Caches(...) as caches:.
Caches.__exit__(): Close every opened cache, as close_all() does.

Errors

Exceptions raised by cache operations.

Timeout: A lock stayed held, or a fork stayed pending, for longer than the cache’s timeout.
TransactionBusy: A thread holding one cache’s transaction couldn’t begin another’s, because another thread holds its write
UnsafeValueError: A pickle=False cache read a value that was stored with pickle.
CorruptValueError: A stored value couldn’t be decoded: an unknown mode, or bytes that don’t parse.
ForeignValueError: A stored value this build can’t read but another might: an unknown mode, tag or extension (a newer version wrote
FormatMismatchError: The cache directory holds a database in a format this version doesn’t support.
LayoutMismatchError: The directory’s layout doesn’t match how it was opened: a plain Cache on a FanoutCache root or shard, a

SQLite and System

Information about the bundled SQLite and environment.

sqlite_version(): The SQLite version reported at runtime by sqlite3_libversion().
sqlite_compile_options(): The compile-time options of the linked SQLite (PRAGMA compile_options).
BUNDLED_SQLITE_VERSION: The SQLite version the bundled library was compiled from (the SQLITE_VERSION macro).