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-Experimental`)
circup install chumicro_kvstore

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

# CPython
pip install chumicro-kvstore-experimental

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

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

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