zoocache 2026.2.20

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.

📖 Read the User Guide

---

✨ Key Features

• 🚀 Rust-Powered Performance: Core logic implemented in Rust for ultra-low latency and safe concurrency.
• 🧠 Semantic Invalidation: Use a PrefixTrie for hierarchical invalidation. Clear "user:*" to invalidate all keys related to a specific user instantly.
• 🛡️ 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.
• 🛡️ Hardened Safety: Strict tag validation and mutex-poisoning protection to ensure zero-crash operations.
• 📊 Observability & Telemetry: Built-in support for Logs, Prometheus, and OpenTelemetry to monitor cache performance.

---

⚡ Quick Start

Installation

Using pip:

pip install zoocache

Using uv (recommended):

uv add zoocache

Simple Usage

from zoocache import cacheable, invalidate

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

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

Complex Dependencies

from zoocache import cacheable, add_deps

@cacheable
def get_product_page(product_id: int, store_id: int):
    # This page stays cached as long as none of these change:
    add_deps([
        f"prod:{product_id}",
        f"store:{store_id}:inv",
        f"region:eu:pricing",
        "campaign:blackfriday"
    ])
    return render_page(product_id, store_id)

# Any of these will invalidate the page:
# invalidate("prod:42")
# invalidate("store:1:inv")
# invalidate("region:eu") -> Clears ALL prices in that region

---

📖 Documentation

Explore the deep dives into Zoocache's architecture and features:

• Architecture Overview - How the Rust core and Python wrapper interact.
• Hierarchical Invalidation - Deep dive into the PrefixTrie and O(D) invalidation.
• Serialization Pipeline - Efficient data handling with MsgPack and LZ4.
• Concurrency & SingleFlight - Shielding your database from traffic spikes.
• Distributed Consistency - HLC, Redis Bus, and robust consistency models.
• Django Integration - Using ZooCache with the Django ORM.
• Django User Guide - Detailed guide for Django users.
• Django Serializers Auto - Automatic caching for Django REST Framework.
• Reliability & Edge Cases - Fail-fast mechanisms and memory management.

Architectural Decisions (ADR)

• ADR 0001: Prefix-Trie Invalidation
• ADR 0007: Zero-Bridge Serialization

---

⚖️ Comparison

Feature	🐾 Zoocache	🔴 Redis (Raw)	🐶 Dogpile	diskcache
Invalidation	🧠 Semantic (Trie)	🔧 Manual	🔧 Manual	⏳ TTL
Consistency	🛡️ Causal (HLC)	❌ Eventual	❌ No	❌ No
Anti-Avalanche	✅ Native	❌ No	✅ Yes (Locks)	❌ No
Performance	🚀 Very High	🏎️ High	🐢 Medium	🐢 Medium

---

🚀 Performance

Zoocache is continuously benchmarked to ensure zero performance regressions. We track micro-latency, scaling with dependencies, and storage overhead.

---

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

---

📄 License

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