Metadata-Version: 2.4
Name: larzcache
Version: 0.1.0
Summary: Caching in pure Python: LRU + TTL, durable file cache, tiered cache, and a memoize decorator. Thread-safe, zero dependencies.
Author: larz-scripter
License: MIT
Project-URL: Homepage, https://github.com/larz-scripter/larzcache
Project-URL: Repository, https://github.com/larz-scripter/larzcache
Project-URL: Documentation, https://github.com/larz-scripter/larzcache#readme
Project-URL: Issues, https://github.com/larz-scripter/larzcache/issues
Keywords: cache,caching,lru,ttl,memoize,lru-cache,file-cache,tiered-cache,thread-safe,zero-dependency,pure-python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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.

```python
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

```bash
pip install larzcache
```

## The caches

```python
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

```python
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

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

## The Larz stack

Pure-Python, zero-dependency building blocks:

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

## License

MIT © larz-scripter
