belljar 🫙

Mid-execution memoization for dynamic state.

Standard caching fails when your function relies on hidden or changing state (like a database cursor or an open file). belljar solves this by letting you build the cache key while your code runs — and keep it, as a value, for later.

uv add belljar

The Difference

Usage

A Jar is a persistent store plus a cursor: it opens at a fresh identity, and include() advances it by folding runtime state in. get() and set() read and write the value at the current position (get() returns None when nothing is sealed there).

from belljar import Jar
import io

# A simulated file. The object stays the same, but its internal cursor moves.
log_file = io.StringIO("chunk1 chunk2 chunk3")

def process_chunk(file_handle) -> str:
    jar = Jar[str]()  # caches under ./.jar by default; pass any path to move it
    jar.include(process_chunk.__code__)    # fold this function's code: edits invalidate
    jar.include(file_handle.tell())        # fold the file's exact runtime cursor position

    # If we've processed from this exact position before, skip the work
    if (cached := jar.get()) is not None:
        return cached

    # Otherwise, do the heavy processing and seal the result
    print("Doing heavy work...")
    return jar.set(file_handle.read(6))

process_chunk(log_file)  # Reads "chunk1", saves to disk. (Takes time)
process_chunk(log_file)  # Reads "chunk2", saves to disk. (Takes time)

log_file.seek(0)
process_chunk(log_file)  # Cursor is back at 0 → instantly returns cached "chunk1"

No decorators, no changed return types — a cache hit is a plain if.

Identity Is Reached, Not Given

Identities are deterministic: folding the same state in the same order always arrives at the same position. So the place that seals a value and the place that retrieves it don't have to share anything but the trace — fold both functions' code on both sides and they reach the same entry:

class KVStore:
    def add(self, key: str, value: int) -> None:
        jar = Jar[int]("./cache")
        jar.include(KVStore.add.__code__)
        jar.include(KVStore.get.__code__)
        jar.include(key)
        jar.set(value)

    def get(self, key: str) -> int | None:
        jar = Jar[int]("./cache")
        jar.include(KVStore.add.__code__)
        jar.include(KVStore.get.__code__)
        jar.include(key)
        return jar.get()

Core Mechanics

• Identity is a trace. The cursor is a running hash: every include chains onto everything folded before it, in order. include(a); include(b) and include(b); include(a) are different identities — the key mirrors the path your execution took.
• Invalidation is inclusion. Fold whatever governs a value's lifetime: func.__code__ to invalidate on edit, a schema version, a mtime. If it's part of the identity, changing it is invalidation.
• Disk Persistent: Caches survive restarts. Identities are deterministic, so a fresh process folding the same state finds the same entries.
• Type Safe: Jar is generic — Jar[str]() seals and returns str, so set and get type-check end to end (Jar() alone defaults to object).
• Deep Serialization: Powered by dill (not pickle), meaning it safely handles lambdas, nested classes, and complex closures — both as folded state and as sealed values.
• Concurrency: A Jar is a lightweight cursor over a shared store — construction is just a path and a hash seed, so make one per call or task instead of sharing a cursor.