DiskCache

Warnings

• breaking Major version changes (e.g., 5.x.x to 6.x.x) are intended for significant new features and may introduce backward incompatibilities. It is recommended to pin at least the major version (e.g., `diskcache~=5.0`) in production to avoid unexpected issues during upgrades.
  Fix: Pin your dependency to `diskcache~=X.0` or `diskcache==X.Y.Z` and review the release notes for breaking changes before upgrading major versions.
• gotcha By default, DiskCache uses Python's `pickle` module for serialization of both keys and values. This can lead to two issues: (1) Inconsistencies for container types (like tuples) used as keys, as `pickle` might serialize equal objects differently. (2) A significant security vulnerability (CVE-2025-69872) where an attacker with write access to the cache directory could execute arbitrary code upon deserialization.
  Fix: For consistent and secure serialization, especially for keys, consider using `JSONDisk` or implementing a custom `Disk` type. For example, `cache = Cache(cache_dir, disk=JSONDisk)`.
• gotcha While DiskCache provides a dictionary-like interface, it does NOT use Python's standard `__hash__` and `__eq__` methods for key lookups. Instead, key equality is determined by the configured serialization method's byte representation. This can lead to unexpected behavior for complex objects or large integers that might be considered equal in Python but serialize differently.
  Fix: Be mindful of how complex objects are serialized when using them as keys. For critical applications, test key behavior carefully or use primitive types/strings as keys, or custom `Disk` implementations that guarantee consistent key serialization.
• gotcha Using 'least-recently-used' (LRU) or 'least-frequently-used' (LFU) eviction policies causes every cache access to be a read *and* a write operation (to update access time/count). This can significantly slow down read-heavy workloads compared to the default 'least-recently-stored' (LRS) policy, which only involves a write on item storage.
  Fix: Evaluate if LRU/LFU is truly necessary for your use case. The default LRS policy often provides sufficient performance for large caches. If you need LRU/LFU, be aware of the performance impact.
• gotcha The cache directory and its contents are NOT automatically removed when the `Cache` object is closed or garbage collected. This means cached data will persist across application restarts.
  Fix: Manually clear the cache directory if you need to delete cached data (e.g., `cache.clear()` or `shutil.rmtree(cache_dir)`). For temporary caches, consider using `tempfile.TemporaryDirectory` for the `cache_dir`.
• gotcha While `diskcache.Cache` is thread-safe and process-safe, for applications with many concurrent *writers*, a single `Cache` instance can become a bottleneck due to SQLite's writer-locks.
  Fix: For high-concurrency write scenarios, use `diskcache.FanoutCache` instead of `diskcache.Cache`. `FanoutCache` shards data across multiple SQLite files, reducing contention for writers. You can configure the number of shards.

Install

• pip install diskcache Install latest version

Imports

• Cache

  from diskcache import Cache

  The primary class for a disk-backed cache.
• FanoutCache

  from diskcache import FanoutCache

  For high-concurrency scenarios, shards data across multiple SQLite files to reduce writer contention.
• DjangoCache

  from diskcache import DjangoCache

  Provides a Django-compatible cache interface.
• Index

  from diskcache import Index

  Uses a Cache to provide a mutable mapping and ordered dictionary interface, where items are never evicted or expired.
• Deque

  from diskcache import Deque

  Provides a persistent double-ended queue for cross-process communication or simple job queues.
• JSONDisk

  from diskcache import JSONDisk

  An alternative Disk type for serializing keys and values using JSON, which can be safer and more consistent than default pickle serialization for certain data types.

Quickstart

This quickstart demonstrates the basic usage of `diskcache.Cache`, including setting and getting values, using expiration, checking key existence, and deleting items. It also shows the important step of closing the cache and cleaning up the cache directory for a runnable example.

import os
from diskcache import Cache

# Create a cache in a local directory (will be created if it doesn't exist)
# For production, specify a persistent path; for examples, a temporary path is fine.
cache_dir = os.path.join(os.getcwd(), 'my_diskcache_data')
cache = Cache(cache_dir)

try:
    # Set items in the cache
    cache['my_key'] = 'Hello, DiskCache!'
    cache.set('another_key', {'data': [1, 2, 3]}, expire=300) # expires in 5 minutes

    # Retrieve items from the cache
    value1 = cache['my_key']
    value2 = cache.get('another_key')
    value3 = cache.get('non_existent_key', 'default_value') # with a default

    print(f"Value for 'my_key': {value1}")
    print(f"Value for 'another_key': {value2}")
    print(f"Value for 'non_existent_key': {value3}")

    # Check if a key exists
    if 'my_key' in cache:
        print("'my_key' is in the cache.")

    # Delete an item
    del cache['my_key']
    print(f"'my_key' after deletion: {cache.get('my_key', 'DELETED')}")

finally:
    # It's crucial to close the cache for proper shutdown and resource release.
    cache.close()
    # For examples, clean up the created directory. In production, you would not typically delete it.
    if os.path.exists(cache_dir):
        import shutil
        shutil.rmtree(cache_dir)
        print(f"Cleaned up cache directory: {cache_dir}")