# grantjenks/python-diskcache architecture

> Architecture diagram of the GitHub repository grantjenks/python-diskcache, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grantjenks/python-diskcache
- Repository: https://github.com/grantjenks/python-diskcache

## Overview

DiskCache is a pure-Python, disk-backed caching library. A caller uses its Cache API to store or retrieve values; the cache serializes keys and values and persists cache records in SQLite, with file storage available for values. The library also provides sharded and Django-compatible cache APIs, persistent deque and mapping containers, and synchronization and memoization recipes. The README documents eviction policies, tags, and cross-process safety; the sampled excerpts support the core storage and wrapper relationships, but not every internal implementation detail.

Main entry points: [`diskcache/core.py`](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/core.py) (Cache API), [`diskcache/fanout.py`](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/fanout.py) (Fanout Cache), [`diskcache/djangocache.py`](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/djangocache.py) (Django Backend), [`diskcache/persistent.py`](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/persistent.py) (Persistent Deque)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cache["Cache and Storage"]
  node_cache_api["Cache API<br/>[core.py]"]
  node_disk_codec["Disk Serialization<br/>[core.py]"]
  node_sqlite[("SQLite Database")]
  node_file_storage[("File Storage")]
end

subgraph group_interfaces["Cache Interfaces"]
  node_fanout["Fanout Cache<br/>[fanout.py]"]
  node_django["Django Backend<br/>[djangocache.py]"]
  node_api_exports["Public Exports<br/>[__init__.py]"]
end

subgraph group_containers["Persistent Containers"]
  node_deque["Persistent Deque<br/>[persistent.py]"]
  node_index["Persistent Index<br/>[persistent.py]"]
end

subgraph group_recipes["Recipes and Coordination"]
  node_recipes["Cache Recipes<br/>[recipes.py]"]
  node_memoize["Stampede Memoization<br/>[recipes.py]"]
  node_locks["Locks and Semaphores<br/>[recipes.py]"]
  node_throttle["Request Throttling<br/>[recipes.py]"]
end

node_caller(("Application"))
node_django_framework(("Django"))

node_caller -->|"imports"| node_api_exports
node_caller -->|"uses"| node_cache_api
node_cache_api -->|"serializes"| node_disk_codec
node_cache_api -->|"reads and writes"| node_sqlite
node_cache_api -->|"stores files"| node_file_storage
node_caller -->|"uses"| node_fanout
node_fanout -->|"dispatches shards"| node_cache_api
node_django_framework -.->|"provides backend API"| node_django
node_caller -->|"uses"| node_django
node_django -->|"delegates cache calls"| node_fanout
node_caller -->|"uses"| node_deque
node_deque -->|"stores items"| node_cache_api
node_caller -->|"uses"| node_index
node_index -->|"stores mappings"| node_cache_api
node_caller -->|"uses"| node_memoize
node_memoize -->|"reads and writes results"| node_cache_api
node_caller -->|"uses"| node_locks
node_locks -->|"coordinates through"| node_cache_api
node_caller -->|"uses"| node_throttle
node_throttle -->|"tracks rate state"| node_cache_api
node_caller -->|"uses"| node_recipes
node_recipes -->|"uses cache"| node_cache_api

click node_cache_api "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/core.py"
click node_disk_codec "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/core.py"
click node_fanout "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/fanout.py"
click node_django "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/djangocache.py"
click node_deque "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/persistent.py"
click node_index "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/persistent.py"
click node_recipes "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/recipes.py"
click node_memoize "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/recipes.py"
click node_locks "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/recipes.py"
click node_throttle "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/recipes.py"
click node_api_exports "https://github.com/grantjenks/python-diskcache/blob/master/diskcache/__init__.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cache_api,node_disk_codec,node_sqlite,node_file_storage toneBlue
class node_fanout,node_django,node_api_exports toneAmber
class node_deque,node_index toneMint
class node_recipes,node_memoize,node_locks,node_throttle toneRose
class node_caller,node_django_framework toneIndigo
```

## Components

### Cache and Storage

- [Cache API](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/core.py): `diskcache/core.py`
- [Disk Serialization](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/core.py): `diskcache/core.py`
- **SQLite Database**
- **File Storage**

### Cache Interfaces

- [Fanout Cache](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/fanout.py): `diskcache/fanout.py`
- [Django Backend](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/djangocache.py): `diskcache/djangocache.py`
- [Public Exports](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/__init__.py): `diskcache/__init__.py`

### Persistent Containers

- [Persistent Deque](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/persistent.py): `diskcache/persistent.py`
- [Persistent Index](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/persistent.py): `diskcache/persistent.py`

### Recipes and Coordination

- [Cache Recipes](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/recipes.py): `diskcache/recipes.py`
- [Stampede Memoization](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/recipes.py): `diskcache/recipes.py`
- [Locks and Semaphores](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/recipes.py): `diskcache/recipes.py`
- [Request Throttling](https://github.com/grantjenks/python-diskcache/blob/master/diskcache/recipes.py): `diskcache/recipes.py`

### Other components

- **Application**
- **Django**

## Connections

- Application → Public Exports: imports
- Application → Cache API: uses
- Cache API → Disk Serialization: serializes
- Cache API → SQLite Database: reads and writes
- Cache API → File Storage: stores files
- Application → Fanout Cache: uses
- Fanout Cache → Cache API: dispatches shards
- Django → Django Backend: provides backend API
- Application → Django Backend: uses
- Django Backend → Fanout Cache: delegates cache calls
- Application → Persistent Deque: uses
- Persistent Deque → Cache API: stores items
- Application → Persistent Index: uses
- Persistent Index → Cache API: stores mappings
- Application → Stampede Memoization: uses
- Stampede Memoization → Cache API: reads and writes results
- Application → Locks and Semaphores: uses
- Locks and Semaphores → Cache API: coordinates through
- Application → Request Throttling: uses
- Request Throttling → Cache API: tracks rate state
- Application → Cache Recipes: uses
- Cache Recipes → Cache API: uses cache