larzcache

Caching done right, in pure Python. Zero dependencies.

An LRU + TTL in-memory cache, a durable file cache, a tiered cache that stacks fast over slow, and a @memoize decorator with TTL and stats — all thread-safe, all with hit/miss accounting, none needing Redis or any install.

from larzcache import LRUCache, memoize

cache = LRUCache(maxsize=1000, ttl=300)      # 1000 entries, 5-min default TTL
cache.set("user:42", {...})
cache.get("user:42")
cache.get_or_set("report", build_report, ttl=60)   # compute only on a miss

@memoize(ttl=30)
def price(symbol):
    ...                                       # cached 30s per symbol

Why

• Zero dependencies, thread-safe. Pure standard library, safe to share across threads, nothing to run or install.
• LRU and TTL. Bound memory by entry count (least-recently-used eviction) and/or expire entries by age — per entry or per cache.
• Durable when you want it. FileCache persists entries as JSON so they survive restarts; Tiered puts a fast memory cache in front of it and promotes hits upward.
• A better lru_cache. @memoize adds TTL, live stats, and selective invalidation (fn.invalidate(args)) on top of the familiar decorator.
• Observable. Every cache reports hits, misses, evictions, and hit rate.

Install

pip install larzcache

The caches

from larzcache import LRUCache, FileCache, Tiered

mem = LRUCache(maxsize=500, ttl=60)          # in-memory
disk = FileCache("cache/", ttl=3600)         # durable JSON files
both = Tiered(mem, disk)                      # memory in front of disk

both.set("k", {"any": "json-able value"})
both.get("k")            # checks memory, then disk (promoting on hit)
both.get_or_set("k", expensive)
"k" in both
both.delete("k")
both.clear()
mem.stats()              # {'hits':.., 'misses':.., 'evictions':.., 'hit_rate':..}

The decorator

from larzcache import memoize

@memoize(maxsize=256, ttl=60)
def fetch(user_id):
    ...

fetch.cache_info()      # hit/miss stats
fetch.invalidate(42)    # drop just fetch(42)
fetch.cache_clear()     # drop everything

Arguments must be hashable (same rule as functools.lru_cache).

Tests

python -m unittest discover -s tests -v      # 19 tests, zero deps

The Larz stack

Pure-Python, zero-dependency building blocks:

• larz — money-native web framework
• larzchain — from-scratch PoW blockchain
• larzmoney — exact, penny-perfect money
• larzcrypt — pure-Python cryptography toolkit
• larzdb — crash-safe embedded database
• larzagent — zero-dep AI agent framework
• larzchart — data to inline SVG charts
• larzmark — Markdown + SEO static sites
• larztask — durable background job queue
• larzvault — encrypted secrets manager
• larzvm — deterministic gas-metered VM
• larzcache — this library

License

MIT © larz-scripter