zoocache 2026.1.20__cp310-abi3-macosx_11_0_arm64.whl

zoocache/__init__.py

@@ -0,0 +1,13 @@
+from .core import cacheable, invalidate, version, clear, configure, prune, _reset
+from .context import add_deps
+
+__all__ = [
+    "cacheable",
+    "invalidate",
+    "version",
+    "add_deps",
+    "clear",
+    "configure",
+    "prune",
+    "_reset",
+]

zoocache/context.py

@@ -0,0 +1,33 @@
+from contextvars import ContextVar
+from typing import Set, Optional
+
+_DEPS_CONTEXT: ContextVar[Optional[Set[str]]] = ContextVar(
+    "_DEPS_CONTEXT", default=None
+)
+
+
+def add_deps(deps: list[str]) -> None:
+    """Register dynamic dependencies for the current @cacheable call."""
+    ctx = _DEPS_CONTEXT.get()
+    if ctx is not None:
+        ctx.update(deps)
+
+
+def get_current_deps() -> Optional[Set[str]]:
+    """Get the dependency set for the current context."""
+    return _DEPS_CONTEXT.get()
+
+
+class DepsTracker:
+    """Context manager to track dynamic dependencies."""
+
+    def __init__(self):
+        self.deps: Set[str] = set()
+        self.token = None
+
+    def __enter__(self):
+        self.token = _DEPS_CONTEXT.set(self.deps)
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        _DEPS_CONTEXT.reset(self.token)

zoocache/core.py

@@ -0,0 +1,158 @@
+import functools
+import asyncio
+import inspect
+from typing import Any, Callable, Optional, Dict
+from ._zoocache import Core
+from .context import DepsTracker, get_current_deps
+
+
+_core: Optional[Core] = None
+_config: Dict[str, Any] = {}
+_op_counter: int = 0
+
+
+def _reset() -> None:
+    """Internal use only: reset the global state for testing."""
+    global _core, _config, _op_counter
+    _core = None
+    _config = {}
+    _op_counter = 0
+
+
+def configure(
+    storage_url: Optional[str] = None,
+    bus_url: Optional[str] = None,
+    prefix: Optional[str] = None,
+    prune_after: Optional[int] = None,
+    default_ttl: Optional[int] = None,
+    read_extend_ttl: bool = True,
+    max_entries: Optional[int] = None,
+) -> None:
+    global _core, _config
+    if _core is not None:
+        raise RuntimeError(
+            "zoocache already initialized, call configure() before any cache operation"
+        )
+    _config = {
+        "storage_url": storage_url,
+        "bus_url": bus_url,
+        "prefix": prefix,
+        "prune_after": prune_after,
+        "default_ttl": default_ttl,
+        "read_extend_ttl": read_extend_ttl,
+        "max_entries": max_entries,
+    }
+
+
+def _get_core() -> Core:
+    global _core
+    if _core is None:
+        # Filter config for Rust Core.__init__
+        core_args = {k: v for k, v in _config.items() if k != "prune_after"}
+        _core = Core(**core_args)
+    return _core
+
+
+def _maybe_prune() -> None:
+    global _op_counter
+    _op_counter += 1
+    if _op_counter >= 1000:
+        _op_counter = 0
+        if age := _config.get("prune_after"):
+            prune(age)
+
+
+def prune(max_age_secs: int = 3600) -> None:
+    """Manually trigger pruning of the PrefixTrie."""
+    _get_core().prune(max_age_secs)
+
+
+def _generate_key(
+    func: Callable, namespace: Optional[str], args: tuple, kwargs: dict
+) -> str:
+    from ._zoocache import hash_key
+
+    obj = (func.__module__, func.__qualname__, args, sorted(kwargs.items()))
+    prefix = f"{namespace}:{func.__name__}" if namespace else func.__name__
+    return hash_key(obj, prefix)
+
+
+def clear() -> None:
+    _get_core().clear()
+
+
+def _collect_deps(deps: Any, args: tuple, kwargs: dict) -> list[str]:
+    base = list(get_current_deps() or [])
+    extra = (deps(*args, **kwargs) if callable(deps) else deps) if deps else []
+    return list(set(base + list(extra)))
+
+
+def invalidate(tag: str) -> None:
+    _get_core().invalidate(tag)
+
+
+def cacheable(
+    namespace: Optional[str] = None, deps: Any = None, ttl: Optional[int] = None
+):
+    def decorator(func: Callable):
+        @functools.wraps(func)
+        async def async_wrapper(*args, **kwargs):
+            key = _generate_key(func, namespace, args, kwargs)
+            _maybe_prune()
+
+            val, is_leader, fut = _get_core().get_or_entry_async(key)
+            if val is not None:
+                return val
+
+            if is_leader:
+                leader_fut = asyncio.get_running_loop().create_future()
+                _get_core().register_flight_future(key, leader_fut)
+                try:
+                    res = await execute(key, args, kwargs)
+                    _get_core().finish_flight(key, False, res)
+                    leader_fut.set_result(res)
+                    return res
+                except Exception as e:
+                    _get_core().finish_flight(key, True, None)
+                    leader_fut.set_exception(e)
+                    raise
+
+            if fut is not None:
+                return await fut
+
+            # Fallback if flight was already finished before we could wait
+            return await execute(key, args, kwargs)
+
+        async def execute(key, args, kwargs):
+            with DepsTracker():
+                res = await func(*args, **kwargs)
+                _get_core().set(key, res, _collect_deps(deps, args, kwargs), ttl=ttl)
+            return res
+
+        @functools.wraps(func)
+        def sync_wrapper(*args, **kwargs):
+            key = _generate_key(func, namespace, args, kwargs)
+            _maybe_prune()
+            val, is_leader = _get_core().get_or_entry(key)
+            if not is_leader:
+                return val
+            try:
+                with DepsTracker():
+                    res = func(*args, **kwargs)
+                    _get_core().set(
+                        key, res, _collect_deps(deps, args, kwargs), ttl=ttl
+                    )
+                _get_core().finish_flight(key, False, res)
+                return res
+            except Exception:
+                _get_core().finish_flight(key, True, None)
+                raise
+
+        return async_wrapper if inspect.iscoroutinefunction(func) else sync_wrapper
+
+    return decorator
+
+
+def version() -> str:
+    """Return the version of the Rust core."""
+    return _get_core().version()

zoocache-2026.1.20.dist-info/METADATA

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: zoocache
+Version: 2026.1.20
+Summary: Cache that invalidates when your data changes, not when a timer expires. Rust-powered semantic invalidation for Python.
+Author-email: Alberto Daniel Badia <alberto_badia@enlacepatagonia.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="docs/assets/logo-light.svg">
+    <img alt="ZooCache Logo" src="docs/assets/logo-light.svg" width="600">
+  </picture>
+</p>
+
+<p align="center">
+  Zoocache is a high-performance caching library with a Rust core, designed for applications where data consistency and read performance are critical.
+</p>
+<p align="center">
+  <a href="https://www.python.org/downloads/"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10+-blue.svg"></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green.svg"></a>
+  <img alt="PyPI" src="https://img.shields.io/pypi/v/zoocache">
+  <img alt="Downloads" src="https://img.shields.io/pypi/dm/zoocache">
+</p>
+
+---
+
+## ✨ 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.
+
+---
+
+## ⚡ Quick Start
+
+### Installation
+
+Using `pip`:
+```bash
+pip install zoocache
+```
+
+Using `uv` (recommended):
+```bash
+uv add zoocache
+```
+
+### Simple Usage
+
+```python
+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
+
+```python
+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**](docs/architecture.md) - How the Rust core and Python wrapper interact.
+- [**Hierarchical Invalidation**](docs/invalidation.md) - Deep dive into the PrefixTrie and O(D) invalidation.
+- [**Serialization Pipeline**](docs/serialization.md) - Efficient data handling with MsgPack and LZ4.
+- [**Concurrency & SingleFlight**](docs/concurrency.md) - Shielding your database from traffic spikes.
+- [**Distributed Consistency**](docs/consistency.md) - HLC, Redis Bus, and robust consistency models.
+- [**Reliability & Edge Cases**](docs/reliability.md) - Fail-fast mechanisms and memory management.
+
+---
+
+## ⚖️ 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 |
+
+---
+
+## ❓ 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](LICENSE) file for details.
+

zoocache-2026.1.20.dist-info/RECORD

@@ -0,0 +1,7 @@
+zoocache/__init__.py,sha256=sK8m3_oTFNhBgqNDH2Scoo3aNoPtKVQHPRdONCKa5OQ,250
+zoocache/_zoocache.abi3.so,sha256=whMickXZxrELSHzYxkmtwSp9OIzb7TQE1-KtBJf8X9s,1952976
+zoocache/context.py,sha256=qQakwfhwSauP9ZKTRy1oQnj-fPFjZZ34sIaeQgCuo6Q,848
+zoocache/core.py,sha256=uQvoqn2jicXOkFb-ZfPmUVqmibr4nk_15rXUSvNVgyI,4775
+zoocache-2026.1.20.dist-info/METADATA,sha256=3AXOXytuOtwkBWrZFo8XeMdXFCSz1q0MbF5JRSne6WI,5100
+zoocache-2026.1.20.dist-info/WHEEL,sha256=vZ12AMAE5CVtd8oYbYGrz3omfHuIZCNO_3P50V00s00,104
+zoocache-2026.1.20.dist-info/RECORD,,

zoocache-2026.1.20.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.11.5)
+Root-Is-Purelib: false
+Tag: cp310-abi3-macosx_11_0_arm64