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.

pure python 3.9 – 3.13 no deps MIT

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:

StorePersistenceEvictionNotes
MemoryStoreprocessLRU by bytesthread-safe, default
FileStorediskLRU by mtimeone file per entry, atomic rename
SQLiteStorediskLRU by bytessingle file, WAL mode
NullStorenone—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
)
Note. 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

Changelog

0.7.2 — 2026-08-30
Fix Age computation when the origin sends a Date header 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-revalidate on a stale entry when the origin is unreachable.
0.6.0 — 2026-02-18
Drop Python 3.8. Add stale_if_error.