Skip to main content

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 <= 0ValueError. 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

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.2.tar.gz (30.2 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.2-cp310-abi3-win_amd64.whl (174.0 kB view details)

Uploaded CPython 3.10+Windows x86-64

rust_py_cache-0.2.2-cp310-abi3-musllinux_1_2_x86_64.whl (537.5 kB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ x86-64

rust_py_cache-0.2.2-cp310-abi3-musllinux_1_2_aarch64.whl (504.2 kB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

rust_py_cache-0.2.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (327.9 kB view details)

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

rust_py_cache-0.2.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (328.0 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

rust_py_cache-0.2.2-cp310-abi3-macosx_11_0_arm64.whl (285.9 kB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

rust_py_cache-0.2.2-cp310-abi3-macosx_10_12_x86_64.whl (289.4 kB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: rust_py_cache-0.2.2.tar.gz
  • Upload date:
  • Size: 30.2 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.2.tar.gz
Algorithm Hash digest
SHA256 73faea13ea76a50161818cc016748de39e9e2be5770a2c56aeca159af1cd3062
MD5 d9fff90bf7605a6566de37bf11b3292d
BLAKE2b-256 dfd806e485c4983682c716b2c6013fd97e987fed6eb320f8b3ea0c80b81eb5d0

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.2.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.2-cp310-abi3-win_amd64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.2-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 8f0392ed3bcfc9cd7fff19173240b6862a08de73468bbe0f9a31b3bb4a671207
MD5 aca1a881cc1a692ba899794ff5db9488
BLAKE2b-256 b776ab414b823e11330c7e7dd44233f3ace0eef92924077f6600cd4dcb79d482

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.2-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.2-cp310-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.2-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 c43a907ef6a55b2bcb6e0e2569790714bc806850c5e245b7a147f662e1f12f5b
MD5 bae1563180a11bdbe1614e47fa323ff9
BLAKE2b-256 0888d4dc72eca82ec5e6ab2eafc71a8b90a9ef720c3a9df7ef35c89eb2f6fbf1

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.2-cp310-abi3-musllinux_1_2_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.2-cp310-abi3-musllinux_1_2_aarch64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.2-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 4a25855f87c508b3849701f04444ba7b12db6f81db6eac921eec86c759dd0a17
MD5 a7aa9bc6b6aa2f4e8cd983c4309ed6cc
BLAKE2b-256 f8b8601725185b7dfddcd53ef76a96359fb66f5a4997f50707fe2cbc9c8b942d

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.2-cp310-abi3-musllinux_1_2_aarch64.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.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 968069446944980a03b4cfa2bc7111c7fb457ebdd62739427fe8617803a13aaf
MD5 05ca273437739351262739f0f02edd55
BLAKE2b-256 57ae20e6260bcca1552b8120f31f5084cc167beac68c497fef2fd92683f17a32

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.2-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_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.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 7e684770cb229819b3779757ca999c0af8f40c4de410e084fbaafbfbe0ddfa52
MD5 cf16c69a19a17022cef64484642081c4
BLAKE2b-256 7424602762916f5ceea890529742da23cb121d37c47d60b8b8ccf07fb0ee3fe5

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.2-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.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.2-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.2-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6014544f0aef9bf2fc1c147d89ea464fd491964a3d13524fb68026badfdeaaa5
MD5 b7aceb3c2dc48ddccd404f922d257171
BLAKE2b-256 8a409a86a8d0b9e0bd45c2541f6148e525a244b4e39ae6ea6e9efd10010bbb2c

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.2-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.

File details

Details for the file rust_py_cache-0.2.2-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.2-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 27f6fd239f2d9b1d72531fbeaf9dd1eba3534742a59813bcfc068f1ac1ce6fc2
MD5 0d736d22f8ef997e28dc46fc8721ccc8
BLAKE2b-256 02e3ec98bbf897e8f090278f572155b9efe96795e02f34b4099ef16577144822

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.2-cp310-abi3-macosx_10_12_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.

Release history Release notifications | RSS feed

0.2.3

8 files

This release

0.2.2 This release

8 files

0.2.1

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