Metadata-Version: 2.4
Name: pyzerocache
Version: 1.1.1
Summary: Redis-like in-memory cache engine for Python — zero dependencies
Project-URL: Homepage, https://github.com/Zeustakeshi/zerocache
Project-URL: Repository, https://github.com/Zeustakeshi/zerocache
Project-URL: Issues, https://github.com/Zeustakeshi/zerocache/issues
Project-URL: Changelog, https://github.com/Zeustakeshi/zerocache/blob/main/CHANGELOG.md
Author-email: ZeroCache Contributors <zerocache@example.com>
License: MIT License
        
        Copyright (c) 2024 ZeroCache Contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: async,cache,in-memory,lru,python,redis,ttl
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24; extra == 'docs'
Description-Content-Type: text/markdown

# ZeroCache 🚀

**Redis-like in-memory cache engine for Python — zero dependencies.**

[![CI](https://github.com/Zeustakeshi/zerocache/actions/workflows/ci.yml/badge.svg)](https://github.com/Zeustakeshi/zerocache/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/zero-cache)](https://pypi.org/project/zero-cache/)
[![Python](https://img.shields.io/pypi/pyversions/zero-cache)](https://pypi.org/project/zero-cache/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Coverage](https://codecov.io/gh/Zeustakeshi/zerocache/branch/main/graph/badge.svg)](https://codecov.io/gh/Zeustakeshi/zerocache)

---

## ✨ Features

| Feature | Details |
|---------|---------|
| **Zero dependencies** | Pure Python standard library only |
| **Redis-like API** | String/Hash/List/Set/SortedSet + Pipeline + Pub/Sub |
| **16-shard locking** | Per-shard RLock — parallel ops on different keys |
| **Heap-based TTL** | O(log n) expiry sweep every 100 ms |
| **Async-native** | `async_get/set/...` via `run_in_executor`, never blocks event loop |
| **Persistence** | Crash-safe atomic snapshot with zlib compression |
| **LRU eviction** | Per-shard LRU, O(1) eviction via OrderedDict |
| **`@cached` decorator** | Works with both sync and async functions |
| **FastAPI ready** | `get_cache()` as a Depends dependency |
| **Type annotations** | PEP 561 typed package, mypy strict compatible |

---

## 📦 Installation

```bash
pip install zero-cache
```

Requires Python 3.10+.

---

## ⚡ Quick Start

```python
from zerocache import ZeroCache

cache = ZeroCache()

# String
cache.set("user:name", "Alice", ttl=300)
cache.get("user:name")          # → "Alice"

# Hash
cache.hset("user:1", "name", "Alice")
cache.hget("user:1", "name")    # → "Alice"

# List
cache.rpush("queue", "task1", "task2")
cache.lpop("queue")             # → "task1"

# Set
cache.sadd("tags", "python", "cache")
cache.sismember("tags", "python")  # → True

# Sorted Set
cache.zadd("leaderboard", {"alice": 100, "bob": 85})
cache.zrange("leaderboard", 0, -1)  # → ["bob", "alice"]
```

---

## 🚀 Async Usage

```python
import asyncio
from zerocache import ZeroCache

cache = ZeroCache()

async def main():
    await cache.async_set("key", "value", ttl=60)
    result = await cache.async_get("key")
    print(result)  # → "value"

asyncio.run(main())
```

---

## 🎯 `@cached` Decorator

```python
from zerocache import cached

@cached(ttl=300)
async def get_user(user_id: int):
    return await db.fetch(user_id)

@cached(key_prefix="compute", ttl=60)
def compute_heavy(n: int) -> int:
    return n ** n
```

---

## 🔄 Pipeline

```python
results = (
    cache.pipeline()
        .set("a", 1)
        .set("b", 2)
        .incr("a")
        .get("b")
        .execute()
)
# → [True, True, 2, 2]
```

---

## 📡 Pub/Sub

```python
import asyncio
from zerocache import ZeroCache

cache = ZeroCache()

async def listener():
    queue = await cache.subscribe("events")
    msg = await queue.get()
    print(f"Received: {msg}")

async def publisher():
    await asyncio.sleep(0.1)
    await cache.publish("events", {"type": "user_login", "user_id": 42})

asyncio.run(asyncio.gather(listener(), publisher()))
```

---

## 🌐 FastAPI Integration

```python
from fastapi import FastAPI, Depends
from zerocache import ZeroCache, get_cache

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int, cache: ZeroCache = Depends(get_cache)):
    cached = cache.get(f"item:{item_id}")
    if cached:
        return cached
    result = {"id": item_id, "name": "Widget"}
    cache.set(f"item:{item_id}", result, ttl=60)
    return result
```

---

## ⚙️ Configuration

```python
cache = ZeroCache(
    maxsize=100_000,          # Total key capacity
    num_shards=16,            # Lock shard count (power of 2)
    persist_path=".cache.db", # Snapshot file
    auto_save_interval=30,    # Seconds between auto-saves
    compress=True,            # zlib compression for snapshots
    load_on_start=True,       # Resume from disk on startup
    track_hits=True,          # Count per-key hits
    intern_keys=True,         # sys.intern() for less RAM
)
```

---

## 📊 Benchmark

Approximate throughput on a modern CPU (single thread):

| Operation | ops/sec |
|-----------|---------|
| `set` | ~1,200,000 |
| `get` (hit) | ~1,500,000 |
| `hset` | ~900,000 |
| `zadd` | ~700,000 |

---

## 🤝 Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## 📄 License

MIT — see [LICENSE](LICENSE).
