zoocache 2026.3.11

Cache that invalidates when your data changes, not when a timer expires. Rust-powered semantic invalidation for Python.

ZooCache is a high-performance caching library with a Rust core, designed for applications where data consistency and read performance are critical.

---

Quick Start

# Install
uv add zoocache

# Use
from zoocache import cacheable, invalidate, configure, add_deps

configure()  # Configure first!

@cacheable()
def get_user(uid):
    add_deps([f"user:{uid}"])  # Register dependencies inside
    return db.fetch_user(uid)  # Runs once

get_user(1)  # Database
get_user(1)  # Cache - instant

invalidate("user:1")  # Invalidate instantly

---

Why ZooCache?

Traditional caches use TTL (Time To Live), which causes stale data and cache thrashing. ZooCache uses Semantic Invalidation with a PrefixTrie to invalidate exactly what changed — instantly.

Feature	🐾 ZooCache	🔴 Redis	🐶 Dogpile	diskcache
Semantic Invalidation	Trie-based	Manual	Manual	TTL only
Smart Serialization	MsgPack+LZ4	No	No	No
Distributed Sync	Redis Bus	Pub/Sub	No	No
Observability	Full	Basic	No	No

---

Key Features

• 🧠 Semantic Invalidation: Use a PrefixTrie for hierarchical invalidation. Clear "user:*" to invalidate all keys related to a specific user instantly.
• 💾 Flexible Storage Backends: Choose between in-memory, LMDB for persistence, or Redis for distributed caching.
• 🛡️ Causal Consistency: Built-in support for Hybrid Logical Clocks (HLC) ensures consistency even in distributed systems.
• ⚡ Anti-Avalanche (SingleFlight): Protects your backend from "thundering herd" effects by coalescing concurrent identical requests.
• 📦 Smart Serialization: Transparently handles MsgPack and LZ4 compression for maximum throughput and minimum storage.
• 🔄 Self-Healing Distributed Cache: Automatic synchronization via Redis Bus with robust error recovery.
• 📊 Observability: Built-in support for Logs, Prometheus, and OpenTelemetry.

---

Installation

# Using uv (recommended)
uv add zoocache

# Using pip
pip install zoocache

Optional Extras

# CLI & TUI for monitoring
uv add "zoocache[cli]"

# FastAPI integration
uv add "zoocache[fastapi]"

# Django integration
uv add "zoocache[django]"

# Litestar integration
uv add "zoocache[litestar]"

# All integrations
uv add "zoocache[cli,fastapi,django,litestar]"

# Full telemetry (Prometheus + OpenTelemetry)
uv add "zoocache[telemetry]"

---

Quick Start

1. Basic Caching

from zoocache import cacheable, invalidate, add_deps

@cacheable()
def get_user(user_id: int):
    add_deps([f"user:{user_id}"])
    return db.fetch_user(user_id)

# First call: executes the function
user = get_user(42)

# Second call: returns cached result instantly
user = get_user(42)

2. Invalidation

def update_user(user_id: int, data: dict):
    db.save(user_id, data)
    invalidate(f"user:{user_id}")  # All cached 'get_user' calls for this ID die instantly

3. Hierarchical Dependencies

from zoocache import cacheable, add_deps

@cacheable()
def get_product(pid):
    add_deps([f"product:{pid}"])
    return db.get_product(pid)

@cacheable()
def get_reviews(pid):
    add_deps([f"product:{pid}:reviews"])
    return db.get_reviews(pid)

# Invalidate product AND its reviews
invalidate("product:42")

# Invalidate only reviews
invalidate("product:42:reviews")

4. Dynamic Dependencies

@cacheable()
def get_dashboard(user_id: int):
    user = db.get_user(user_id)
    add_deps([f"user:{user_id}"])
    
    if user.is_admin:
        reports = db.get_admin_reports()
        add_deps(["reports:admin"])
        return {"user": user, "reports": reports}
    
    return {"user": user}

5. Distributed Mode

from zoocache import configure

# Configure for distributed caching
configure(
    storage_url="redis://localhost:6379",
    bus_url="redis://localhost:6379",
    prefix="myapp_prod",
    default_ttl=3600,
)

---

Optional CLI & TUI

ZooCache includes an optional CLI for real-time monitoring and cache management:

uv run zoocache cli

---

Performance

Zoocache is continuously benchmarked to ensure zero performance regressions.

Note: Benchmark scale: 5,000 operations. Redis running on localhost to eliminate network latency.

---

When to Use ZooCache

✅ Good Fit

• Complex Data Relationships: Use dependencies to invalidate groups of data.
• High Read/Write Ratio: Where TTL causes stale data or unnecessary cache churn.
• Distributed Systems: Native Redis Pub/Sub invalidation and HLC consistency.
• Strict Consistency: When users must see updates immediately (e.g., pricing, inventory).

❌ Not Ideal

• Pure Time-Based Expiry: If you only need simple TTL for session tokens.
• Simple Key-Value: If you don't need dependencies or hierarchical invalidation.
• Minimal Dependencies: For small, local-only apps where basic lru_cache suffices.

---

Documentation

🚀 Getting Started

• Quick Start & Installation — Install and run your first cached function

🔌 Integrations

• FastAPI Integration — Out-of-box caching for FastAPI endpoints
• Django Integration — Transparent caching for Django ORM
• Litestar Integration — Out-of-box caching for Litestar endpoints

💡 Concepts & Deep Dives

• Core Concepts — Dependencies, hierarchical tags, and dynamic dependencies
• Semantic Invalidation — Deep dive into PrefixTrie and O(D) invalidation
• Distributed Consistency — HLC, Redis Bus, and consistency models
• Concurrency & SingleFlight — Shielding your database from traffic spikes
• Architecture Overview — How the Rust core and Python wrapper interact

⚙️ Configuration

• General Configuration — Configure storage, TTL, serialization
• Storage Backends — Memory, Redis, LMDB options

🛠️ How-to Guides

• CLI / TUI Usage — Monitor and manage your cache
• Telemetry & Observability — Prometheus, OpenTelemetry

📚 Reference

• API Reference — Detailed API documentation
• Reliability & Edge Cases — Fail-fast mechanisms and error handling

---

Architectural Decisions (ADR)

• ADR 0001: Prefix-Trie Invalidation
• ADR 0002: Rust Core Python Wrapper
• ADR 0003: HLC Distributed Consistency
• ADR 0004: Serialization Strategy
• ADR 0005: Singleflight Pattern
• ADR 0006: Trie Performance Optimizations
• ADR 0007: Zero-Bridge Serialization
• ADR 0008: Redis Bus Connection Pooling
• ADR 0009: Robust Sync and Error Handling

---

License

This project is licensed under the MIT License — see the LICENSE file for details.