In-memory cache for Python. The hot path is a PyO3 extension (cachebox._core); cachebox/ is the public package.
- Keep diffs small and match the surrounding style. Do not add a new language, framework, or packaging tool.
- After a behavior change, rebuild with maturin and run pytest.
- Do not edit
target/,*.so,__pycache__,.venv, or other build output. Do not editCargo.lockoruv.lockunless a dependency changed. - Do not read or write secrets or
.env. src/hashbrown/is vendored hashbrown (seeLICENSE-THIRD-PARTY). Change it only when the table itself must change.- v6 is the public API. A breaking change needs a note in
docs/docs/migration.mdand a matching update tocachebox/_core.pyiand the MkDocs pages. use-small-offsetis a test-only Cargo feature. Release and publish builds must not enable it.
src/policies/— eviction (Cache, FIFO, RR, LRU, LFU, TTL, VTTL).src/pyclasses/— one PyO3 class per policy, plus key/value/item iterators.src/internal/— pickle,OnceInit(__new__/__init__), linked list, hash helpers.cachebox/_cachebox.py— publicTTLCacheandVTTLCache(subclasses of the Rust types). Other classes are re-exported from_core.cachebox/utils.pyand_wrappers.py—@cached, key makers, stampede locks.tests/— pytest mixins shared across implementations. Rust#[cfg(test)]covers the vendored table only.
uv venv .venv && uv pip install --group ci
maturin develop --features use-small-offset # local tests; CI does this
pytest -v -n auto # CI also sets HYPOTHESIS_PROFILE=slow
typos --config typos.toml
zizmor .github/
mkdocs serve --config-file docs/mkdocs.ymlmaturin develop --release is the documented source install. Wheels are built only by .github/workflows/CI.yml on a tag.
rustfmt.tomlsetsimports_granularity = "Item".- Rust edition is whatever
Cargo.tomlsays. Edition 2024 deniesunsafe_op_in_unsafe_fn; the crate allows it insrc/lib.rs. - Python docstrings are Google style. MkDocs (
mkdocstrings) renders them. - Clippy warns on
dbg!andprint!. Clippy, rustfmt, and mypy are not CI jobs.