chumicro-kvstore-experimental 0.3.0

Tiny mutable key-value store for persisted runtime state — counters, timestamps, tokens — across CircuitPython, MicroPython, and CPython.

chumicro-kvstore

A persistent dict for counters, timestamps, and tokens that need to survive a reboot.

A dict-shaped store with commit() semantics. Auto-detects the right backend per runtime (NVM on CircuitPython, NVS on ESP32 MicroPython, LittleFS elsewhere, in-memory for tests), bounds writes with commit_if_changed() so unchanged state doesn't wear the flash, and surfaces capacity and corruption honestly. Not a config system — for declarative settings see chumicro-config.

Part of the ChuMicro family — small, focused Python libraries for microcontrollers and laptops. Browse all libraries.

Install

# CircuitPython (after `circup bundle-add ChuMicro/ChuMicro-Bundle`)
circup install chumicro-kvstore

# MicroPython
mpremote mip install github:ChuMicro/ChuMicro-Bundle/chumicro_kvstore

# CPython
pip install chumicro-kvstore

For bundle setup, pre-compiled .mpy bundles, the experimental channel, and details on PyPI naming, see the chumicro INSTALL guide.

Quick example

Boot counter that survives reboot:

from chumicro_kvstore import KVStore

store = KVStore(backend="auto")
store["boot_count"] = store.get("boot_count", 0) + 1
store.commit_if_changed()              # no flash write if value unchanged
print(store["boot_count"])             # → 1, 2, 3, … across power cycles

What's included

Symbol	What it does
KVStore(backend="auto")	Mapping-shaped store; auto-detect picks NVM (CP), NVS (MP-ESP32), LittleFS (MP non-NVS), or memory (CPython)
store[key] / store[key] = v / del store[key]	Standard dict semantics
store.commit()	Encode + persist current state
store.commit_if_changed()	Skip write when payload is unchanged (wear defense)
store.reload()	Discard in-memory state, reread from backend
store.capacity / bytes_used / is_corrupt / backend_name	Honest substrate introspection
KVStoreFull / KVStoreCorrupt	Targeted exceptions (catch KVStoreError for both)
chumicro_kvstore.testing.FakeKVStore	Drop-in for downstream tests with capacity + corruption hooks

Where this fits

Leaf — no upstream ChuMicro deps. Used directly in app code; no other ChuMicro library depends on it.

Platform support

Works on CPython, MicroPython, and CircuitPython.

Examples

Example	What it shows
boot_counter.py	Boot counter persisted across reboots; auto-detect picks the right backend per runtime

Contributing

Working on chumicro-kvstore itself? Clone the mono-repo if you haven't already — the rest of the workflow assumes you're inside that workspace.

pip install -e .[test]
pytest tests/                  # host-side tests
pytest functional_tests/       # on-device tests (needs a board registered in devices.yml)

Register a board before running functional tests: chumicro-workspace add-device <id> --address <port>.

Docs

📖 Stable docs · Experimental docs

Find this library

• PyPI: chumicro-kvstore
• Bundle: ChuMicro-Bundle (CircuitPython & MicroPython)
• Experimental bundle: ChuMicro-Bundle-Experimental
• Source: libraries/kvstore

License

MIT