rust-py-cache 0.1.1__cp310-abi3-win_amd64.whl

rust_py_cache/__init__.py

@@ -0,0 +1,22 @@
+"""rust-py-cache — An ultra-fast local cache for Python, powered by Rust."""
+
+# O módulo nativo (_rust_py_cache) é compilado pelo Rust/maturin e fica DENTRO
+# deste pacote. O core (set/get/delete/exists/keys/stats/cleanup_expired) vem do
+# Rust; aqui só adicionamos açúcar Python — o decorator `cached` — via subclasse.
+from ._rust_py_cache import Cache as _RustCache, hello
+from .decorators import cached as _cached
+
+
+class Cache(_RustCache):
+    """Cache local em memória (core em Rust) + decorator `cached` em Python.
+
+    Herda todos os métodos do core nativo e adiciona `@cache.cached(...)`. A
+    herança só é possível porque o `#[pyclass(subclass)]` libera o tipo nativo
+    para ser estendido no Python.
+    """
+
+    cached = _cached
+
+
+__all__ = ["Cache", "hello"]
+__version__ = "0.1.1"

rust_py_cache/decorators.py

@@ -0,0 +1,64 @@
+"""Decorator de memoização — Etapa 17.
+
+Fornece `Cache.cached`, um decorator que guarda o retorno de uma função no cache.
+Fica em Python (não no core Rust) porque mexe com `*args/**kwargs`, geração de
+chave e `functools.wraps` — tudo muito mais natural aqui.
+"""
+
+import functools
+
+# Sentinela para distinguir "ausente no cache" de "valor None legítimo".
+# `cache.get(key, _MISSING)` devolve `_MISSING` só quando a chave não existe.
+_MISSING = object()
+
+
+def _default_key(func, args, kwargs):
+    """Chave determinística a partir da função e dos argumentos.
+
+    Usa `repr` dos argumentos — simples e legível. Pressupõe argumentos
+    repr-áveis e estáveis (o caso comum: números, strings, tuplas). Para casos
+    exóticos, o usuário pode passar `key=...` explícito.
+    """
+    parts = [func.__module__ or "", func.__qualname__, repr(args)]
+    if kwargs:
+        parts.append(repr(sorted(kwargs.items())))
+    return "|".join(parts)
+
+
+def cached(self, ttl=None, key=None):
+    """Decorator: memoiza o retorno da função neste cache.
+
+    Parâmetros:
+        ttl: validade em segundos (igual a `set`); `None` = sem expiração.
+        key: opcional. String fixa, ou callable `key(*args, **kwargs) -> str`.
+             Se omitido, a chave é derivada de função + argumentos.
+
+    Uso:
+        @cache.cached(ttl=60)
+        def soma(a, b):
+            return a + b
+    """
+
+    def decorator(func):
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            if key is None:
+                cache_key = _default_key(func, args, kwargs)
+            elif callable(key):
+                cache_key = key(*args, **kwargs)
+            else:
+                cache_key = key
+
+            hit = self.get(cache_key, _MISSING)
+            if hit is not _MISSING:
+                return hit
+
+            result = func(*args, **kwargs)
+            self.set(cache_key, result, ttl=ttl)
+            return result
+
+        # Expõe a chave-base para inspeção/invalidação manual em testes.
+        wrapper.__wrapped__ = func
+        return wrapper
+
+    return decorator

rust_py_cache-0.1.1.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: rust-py-cache
+Version: 0.1.1
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Classifier: Topic :: System :: Distributed Computing
+Summary: An ultra-fast local cache for Python, powered by Rust.
+Keywords: cache,rust,pyo3,ttl,performance
+Author-email: Roberto Lima <robertolima.izphera@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/robertolima/rust-py-cache
+
+# rust-py-cache
+
+> **An ultra-fast local cache for Python, powered by Rust.**
+
+A local, in-memory, thread-safe cache with TTL, lazy expiration, and metrics. The
+core is written in Rust (PyO3 + maturin) on top of a concurrent `DashMap`; the
+Python API is minimal. Think of it as a "mini Redis" living **inside** your Python
+process.
+
+[![PyPI](https://img.shields.io/pypi/v/rust-py-cache)](https://pypi.org/project/rust-py-cache/)
+[![Python](https://img.shields.io/pypi/pyversions/rust-py-cache)](https://pypi.org/project/rust-py-cache/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](./LICENSE)
+
+## Installation
+
+```bash
+pip install rust-py-cache
+```
+
+To work on it locally (requires Rust + maturin):
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install maturin pytest
+maturin develop          # compiles the Rust core and installs into the venv
+pytest                   # runs the tests
+```
+
+## Usage
+
+```python
+from rust_py_cache import Cache
+
+cache = Cache()
+
+cache.set("user:1", {"name": "Roberto"}, ttl=60)   # ttl in seconds
+user = cache.get("user:1")                          # {"name": "Roberto"}
+cache.get("missing", default=0)                     # 0
+
+cache.exists("user:1")        # True (honors TTL)
+cache.delete("user:1")        # True if removed, False if absent
+cache.len()                   # approximate size
+cache.keys()                  # list of keys
+cache.cleanup_expired()       # remove expired entries; returns the count
+cache.clear()                 # remove everything (keeps counters)
+cache.stats()                 # {'hits', 'misses', 'sets', 'deletes', 'expired', 'size'}
+```
+
+### Memoization decorator
+
+```python
+@cache.cached(ttl=60)
+def add(a, b):
+    return a + b
+
+add(2, 3)   # runs and caches
+add(2, 3)   # served from cache
+
+# custom key (fixed string or callable):
+@cache.cached(ttl=300, key=lambda user_id: f"user:{user_id}")
+def load_user(user_id):
+    ...
+```
+
+See full examples under [`examples/`](./examples) (FastAPI and Django).
+
+## API
+
+| Method | Description |
+|---|---|
+| `set(key, value, ttl=None)` | Store a value. `ttl` in seconds (`int`/`float`); `None` = no expiration; `ttl <= 0` → `ValueError`. Overwrites. |
+| `get(key, default=None)` | The value, or `default` if missing/expired (expired entries are removed). |
+| `delete(key)` | `True` if removed, `False` if it didn't exist. |
+| `exists(key)` | `True`/`False`, honoring TTL. |
+| `keys()` | List of keys (may include expired-but-not-yet-collected ones). |
+| `len()` / `len(cache)` | Approximate size. |
+| `clear()` | Remove everything (does not reset counters). |
+| `cleanup_expired()` | Remove expired entries; returns how many. |
+| `stats()` | `dict` with `hits, misses, sets, deletes, expired, size`. |
+| `@cache.cached(ttl=None, key=None)` | Memoization decorator. |
+
+## How it works
+
+- **Serialization:** in the MVP, values are serialized with `pickle` (on the Python
+  side, via PyO3) and stored as opaque bytes (`Vec<u8>`) in the Rust core.
+- **Concurrency:** `DashMap` (a HashMap with per-shard locks) plus `AtomicU64`
+  counters, with no global lock on the hot path. Thread-safe, no busy loop.
+- **TTL:** expiration is **lazy** — an expired key is removed when accessed
+  (`get`/`exists`) or via `cleanup_expired()`. There is no background thread in the MVP.
+
+## Limitations
+
+- The cache is **process-local**: multiple workers = multiple independent caches.
+- It does **not** replace Redis for distributed caching.
+- Data is **lost** when the process restarts.
+- `pickle` must **not** be used to deserialize untrusted data.
+- Lazy TTL: expired items may linger until accessed or until `cleanup_expired()`.
+
+## Development
+
+```bash
+cargo test          # Rust core tests
+maturin develop     # rebuild and install
+pytest              # Python tests
+```
+
+> If `maturin develop` complains about both `VIRTUAL_ENV` and `CONDA_PREFIX` being
+> set, run `conda deactivate` first, or use `env -u CONDA_PREFIX maturin develop`.
+
+## Roadmap
+
+Stages and next steps (LRU/LFU eviction, background expiration, configurable
+serializer, namespaces, etc.) are in [ROADMAP.md](./ROADMAP.md).
+
+## License
+
+MIT
+

rust_py_cache-0.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+rust_py_cache/__init__.py,sha256=ik8zJVOuYg8BrHSP2psDcyOJc6vqUyTLfaflD2UQ9l0,834
+rust_py_cache/_rust_py_cache.pyd,sha256=0L6i6vgdBVDi-10ZsIo3cuG7MyrqK6tYCPFekQ6JAvE,331264
+rust_py_cache/decorators.py,sha256=fqH-JQTwSilH-m7te4n9GvPQUZgVoGYZh--ne3_GU_E,2174
+rust_py_cache-0.1.1.dist-info/METADATA,sha256=jHZu9sabDZ6heDUaB-SmAFI1OUACESNJmO65YL1EutA,5028
+rust_py_cache-0.1.1.dist-info/WHEEL,sha256=_qjkWZs5yrFgc7wGyX42BWq6PiACrY0XI82VSrZ_57E,96
+rust_py_cache-0.1.1.dist-info/sboms/rust_py_cache.cyclonedx.json,sha256=W1bqYnXOSg9GnNzf65_nwMPvsJKmgB_iuTANf58XjhA,36745
+rust_py_cache-0.1.1.dist-info/RECORD,,

rust_py_cache-0.1.1.dist-info/WHEEL

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