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 Python License: MIT

🌐 Website: rust-py-cache.vercel.app

Installation

pip install rust-py-cache

To work on it locally (requires Rust + maturin):

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

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','evicted','size'}

Bounded cache with LRU eviction

# Cap the number of keys. When full and a new key arrives, evict the
# least-recently-used entry instead of rejecting the write.
cache = Cache(max_size=1000, eviction_policy="lru")
cache.eviction_policy            # "lru"

# Default policy is "reject": set() returns False when full (and the key is new).
cache = Cache(max_size=1000)     # eviction_policy="reject"
cache.set("a", 1)                # True / False

Background expiration

# A background thread reclaims expired entries every N seconds, so you don't
# have to call cleanup_expired() yourself. It stops when the cache is collected.
cache = Cache(cleanup_interval=30)   # seconds (int/float)

Memoization decorator

@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/ (FastAPI and Django).

API

Constructor: Cache(max_size=None, eviction_policy="reject", cleanup_interval=None). eviction_policy must be "reject" or "lru" (any other value raises ValueError). cleanup_interval (seconds, > 0) enables the background sweeper.

Method Description
set(key, value, ttl=None) Store a value. ttl in seconds (int/float); None = no expiration; ttl <= 0 → ValueError. Overwrites. Returns True, or False when full under eviction_policy="reject" and the key is new.
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.
eviction_policy (property) The active policy: "reject" or "lru".
stats() dict with hits, misses, sets, deletes, expired, evicted, 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 by default — an expired key is removed when accessed (get/exists) or via cleanup_expired(). Pass cleanup_interval to also run a background sweeper thread that reclaims expired keys on its own.
  • Eviction: with max_size + eviction_policy="lru", a full cache evicts the least-recently-used entry (recency updated on every get hit) to admit a new key.

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 by default: without cleanup_interval, expired items may linger until accessed or until cleanup_expired() runs.

Development

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.

License

MIT

Project links

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.2.3)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for robertolima_dev from gravatar.com robertolima_dev

Credits

PyPI data
Data sourced directly from PyPI's database.

Author: Roberto Lima

License

MIT License (MIT)

Requires

Python >=3.10

Tags

cache rust pyo3 ttl performance

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rust_py_cache-0.2.1.tar.gz (25.3 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

rust_py_cache-0.2.1-cp310-abi3-win_amd64.whl (174.6 kB view details)

Uploaded CPython 3.10+Windows x86-64

rust_py_cache-0.2.1-cp310-abi3-manylinux_2_34_x86_64.whl (328.2 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.34+ x86-64

rust_py_cache-0.2.1-cp310-abi3-macosx_11_0_arm64.whl (286.4 kB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

File details

Details for the file rust_py_cache-0.2.1.tar.gz.

File metadata

  • Download URL: rust_py_cache-0.2.1.tar.gz
  • Upload date:
  • Size: 25.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for rust_py_cache-0.2.1.tar.gz
Algorithm Hash digest
SHA256 a5990192dd53baa1dbcce67d1a46941e45b111be14808bc504e84966726ba529
MD5 17876af8c7a8f22b7f6662d1b198e543
BLAKE2b-256 f98f1d418e061fb92f1ad1e0e1d10ed40d607bf0159b06bc740a364bbe8ae55f

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.1.tar.gz:

Publisher: release.yml on robertolima-dev/rust-py-cache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rust_py_cache-0.2.1-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.1-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 8540a932d6acb8e502e6385ebf6f94a2d570482412beeeddad5c6effb854cd01
MD5 7fc42127b8d7a4ac739764569a6875e4
BLAKE2b-256 6d0a48016907c387f7b24a71595c8a1c4164420eab9d5fe74466be7fe416ff1a

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.1-cp310-abi3-win_amd64.whl:

Publisher: release.yml on robertolima-dev/rust-py-cache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rust_py_cache-0.2.1-cp310-abi3-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.1-cp310-abi3-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 05cfaf841e2ed324645829e6714bf29c405a4f33d4ada3bff35989e9b066b905
MD5 19ddd5386dafead53a736c1d73c5e667
BLAKE2b-256 879294efe0cc85ab0bda87ab86b9411618f737f6a62a567d22914227cfe2a10c

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.1-cp310-abi3-manylinux_2_34_x86_64.whl:

Publisher: release.yml on robertolima-dev/rust-py-cache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file rust_py_cache-0.2.1-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.1-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ae37611b2d960907b422b4db971ae2b7b6bc27fee43c7432e70387eafecb8bb4
MD5 2809904f93fa586818aa415520e921c7
BLAKE2b-256 4bac884cc5c2f58f043caabc670839e56f5d98437881fa773e529f03e8172344

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.1-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on robertolima-dev/rust-py-cache

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.2.3

8 files

0.2.2

8 files

This release

0.2.1 This release

4 files

0.2.0

4 files

0.1.3

4 files

0.1.2

4 files

0.1.1

4 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page