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:
Latest release

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 expression

MIT
View SPDX License List

Requires

Python >=3.10

Provides Extra

dev

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.3.tar.gz (33.5 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.3-cp310-abi3-win_amd64.whl (174.9 kB view details)

Uploaded CPython 3.10+Windows x86-64

rust_py_cache-0.2.3-cp310-abi3-musllinux_1_2_x86_64.whl (538.2 kB view details)

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

rust_py_cache-0.2.3-cp310-abi3-musllinux_1_2_aarch64.whl (505.2 kB view details)

Uploaded CPython 3.10+musllinux: musl 1.2+ ARM64

rust_py_cache-0.2.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (328.7 kB view details)

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

rust_py_cache-0.2.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (328.7 kB view details)

Uploaded CPython 3.10+manylinux: glibc 2.17+ ARM64

rust_py_cache-0.2.3-cp310-abi3-macosx_11_0_arm64.whl (286.7 kB view details)

Uploaded CPython 3.10+macOS 11.0+ ARM64

rust_py_cache-0.2.3-cp310-abi3-macosx_10_12_x86_64.whl (290.2 kB view details)

Uploaded CPython 3.10+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: rust_py_cache-0.2.3.tar.gz
  • Upload date:
  • Size: 33.5 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.3.tar.gz
Algorithm Hash digest
SHA256 b0e529d947c9ef1509c5e7ffe4cb3ced72c51ddfdb5354d25d00f3ecd1dbf97f
MD5 ff612903068d36eef08586f505fac4d0
BLAKE2b-256 01aa40a91a28fd2b3d060c0793a46c11df1ae04cbf7e0d5af5cf0ab9bc7bc3ef

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for rust_py_cache-0.2.3-cp310-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 2b111a08c8b20f4f3bc0e1aa32852226f140f33a740f436e015353acd201617f
MD5 41b7538f4c6693169c1f746a0a79e26d
BLAKE2b-256 8a2667f79e835315e2ddb1ca1b5eb176726349da282ed69c87451709e65c21e2

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for rust_py_cache-0.2.3-cp310-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 b6536c9c1b0d51c4ce894111867f60550c60b20f646141350fd2cd833cad9536
MD5 b03500f7338f765b9aa279ce432b3def
BLAKE2b-256 0718f8d2199ce6a71ee71ce851117f6deaee7a5210578135a29a29f1934fae27

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for rust_py_cache-0.2.3-cp310-abi3-musllinux_1_2_aarch64.whl
Algorithm Hash digest
SHA256 79249e8b7c3adf423f5b7cad926078120c3223ab23de271c7eb1a037de17caea
MD5 a20fd9f0eadd51f586ac91a188f0b2c8
BLAKE2b-256 f587e19358834a66cd6bcd95106896929cbc55da7a0531cd5c69303091c78f6b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for rust_py_cache-0.2.3-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6842f722f3d319df38fb0133fd52dba0a1922b64a201c1afe58912ed6b51525b
MD5 00a53f261d30ac6acf9c343777c72c1a
BLAKE2b-256 511e3169714d38c2714eb10e92d4010300e90115eacfb61da98c880030acf3ee

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for rust_py_cache-0.2.3-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 d7a908aa8cbb249438ad65d55deb780aa19a1019405768e76e0b0b504ed27260
MD5 c197e14e9929c772c6e6b9ca2a2ee5fc
BLAKE2b-256 1c16266f465dddf5baac8ad54f4b0ce385ecda725a73501f8224b9b45821ca4b

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.3-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.3-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.3-cp310-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ddeea0981295546676988d63fccd0b1ac8a07dacad6fb6838d9b685eb11b5c65
MD5 b7eb850f3f8f2ceb2a10eace59a85391
BLAKE2b-256 6de4002b69a93807f7dc0596a2e8ae5775543cf216cbfa7344146375d65be65b

See more details on using hashes here.

Provenance

The following attestation bundles were made for rust_py_cache-0.2.3-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.3-cp310-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for rust_py_cache-0.2.3-cp310-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 e3384619340eab8c8e9726bfc0594f34b54a23295b2a5685fd37ad13115d80e2
MD5 6425e20412ba060fc4c691431211724d
BLAKE2b-256 e2d8205342415e57ea904a5cdcc8060eb5c37cc7a0b32704d0b20a637bef840d

See more details on using hashes here.

Provenance

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

This release

0.2.3 This release

8 files

0.2.2

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