kettle
A tiny, dependency-free HTTP response cache for Python. Roughly 400 lines, RFC 9111 freshness and revalidation, pluggable storage, and no background threads doing things behind your back.
Installation
pip install kettle-cache
There are no runtime dependencies. The test suite needs pytest and
hypothesis; everything else is standard library.
Quick start
Wrap any callable that returns a response. kettle does not care whether it came
from urllib, httpx or a socket you opened yourself — it
only reads the status line and headers.
from kettle import Cache, MemoryStore
cache = Cache(store=MemoryStore(max_bytes=32 * 1024 * 1024))
@cache.wrap
def fetch(url: str) -> Response:
return session.get(url)
r1 = fetch("https://example.org/data.json") # MISS — stored
r2 = fetch("https://example.org/data.json") # HIT — served from store
print(r2.from_cache, r2.age) # True 0.4
By default kettle honours Cache-Control, Expires,
ETag and Last-Modified. A response with
no-store is never written; a response with private is
written only if you constructed the cache with shared=False.
Storage backends
A store is any object with four methods. The bundled ones are:
| Store | Persistence | Eviction | Notes |
|---|---|---|---|
MemoryStore | process | LRU by bytes | thread-safe, default |
FileStore | disk | LRU by mtime | one file per entry, atomic rename |
SQLiteStore | disk | LRU by bytes | single file, WAL mode |
NullStore | none | — | for disabling the cache in tests |
Writing your own is four methods:
class MyStore:
def get(self, key: str) -> Entry | None: ...
def set(self, key: str, entry: Entry) -> None: ...
def delete(self, key: str) -> None: ...
def clear(self) -> None: ...
Revalidation
When an entry is stale but carries a validator, kettle issues a conditional
request and upgrades a 304 back into the stored body, merging the
new headers per RFC 9111 §4.3.4.
cache = Cache(
store=FileStore("~/.cache/myapp"),
stale_if_error=300, # serve stale for 5 min if origin 5xx
stale_while_revalidate=0 # synchronous only; no threads
)
stale_while_revalidate is accepted for
compatibility but a non-zero value raises unless you pass an explicit executor.
kettle will not spawn threads on your behalf.
API reference
Cache(store, *, shared=True, stale_if_error=0, key_fn=None)
The main entry point. key_fn receives the request and returns a
cache key string; the default hashes method, URI and any header named in the
response's Vary.
Cache.wrap(fn)
Decorator form. Equivalent to calling Cache.run(fn, *args).
Cache.invalidate(url, method="GET")
Drops every variant stored for that URI. Returns the number of entries removed.
Entry
A frozen dataclass: status, headers,
body, stored_at, validators. Safe to
pickle; the on-disk format is versioned and refuses to read a newer version.
Known limitations
- No
Vary: *support — such responses are simply not stored. - Range requests are passed straight through; partial content is never cached.
FileStoreeviction is best-effort and runs on write, so a process that only reads will never evict.- No async API yet. The synchronous core is deliberate; see issue #31 for the discussion of where an async wrapper would sit.
Changelog
- 0.7.2 — 2026-08-30
- Fix
Agecomputation when the origin sends aDateheader in the future. Reported by @tmk. - 0.7.0 — 2026-06-14
- Add
SQLiteStore. Entry format bumped to v3 (old entries are ignored, not migrated). - 0.6.1 — 2026-04-02
- Correctly treat
must-revalidateon a stale entry when the origin is unreachable. - 0.6.0 — 2026-02-18
- Drop Python 3.8. Add
stale_if_error.