chumicro-config-experimental 0.7.2

Standardized runtime-config helpers for ChuMicro libraries — section loader + on-device runtime-config reader.

chumicro-config

Runtime config from one shared dotted-key shape (wifi.ssid, mqtt.broker.host).

Each library exposes a <Name>Config.from_config() factory that reads its own dotted-prefix section from a shared dict (wifi.*, mqtt.broker.*, etc.) and returns typed configuration. Apps load one runtime_config.msgpack at boot; libraries pull their slice out. No global registry, no hand-written if "key" in config: walls.

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-config

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

# CPython
pip install chumicro-config

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

Quick example

User-app pattern (the 2-line bring-up):

from chumicro_config import load_runtime_config
from chumicro_wifi import WifiConfig, WifiService

config = load_runtime_config()                          # reads /runtime_config.msgpack
wifi = WifiService(WifiConfig.from_config(config))      # reads + types the wifi.* keys

Library-side pattern (load_section builds a typed config from the flat-key payload — used today by chumicro-wifi):

from chumicro_config import load_section

class WifiConfig:
    def __init__(self, ssid, password, hostname=None, connect_timeout_ms=15_000): ...

    @classmethod
    def from_config(cls, config):
        return load_section(
            cls, config,
            prefix="wifi",
            required=("ssid", "password"),
            optional={"hostname": None, "connect_timeout_ms": 15_000},
        )

What's included

Symbol	What it does
load_runtime_config(path=…)	Read + decode /runtime_config.msgpack into a flat-key RuntimeConfig (dict-shaped)
config	Lazily-loaded module attribute — the deployed RuntimeConfig, or None when the file is absent. First attribute access reads the file once and caches the result
RuntimeConfig	Lookup wrapper over the flat-key payload — get(key[, default]), [key] / require(key), in check
load_section(cls, config, *, prefix, required=…, optional=…)	Build cls(**kwargs) by reading flat-prefix keys. Used today by chumicro-wifi's WifiConfig.from_config; available to any library whose constructor signature maps 1:1 to its config subkeys
try_load_section(...)	Soft variant — returns None instead of raising when config is None, the wrong type, or missing a required key
MissingConfigKey / InvalidConfigType / ConfigError	Targeted exceptions — single-inheritance from ConfigError (MicroPython forbids multi-parent layouts)

Where this fits

Depends on chumicro-msgpack for decode. Most ChuMicro libraries with a <Name>Config.from_config() factory read their slice off the shared RuntimeConfig via config.get(...); chumicro-wifi additionally uses the load_section helper here. Other consumers: chumicro-mqtt, chumicro-ntp, chumicro-requests, chumicro-websockets, chumicro-http_server.

Platform support

Works on CPython, MicroPython, and CircuitPython.

Examples

examples/end_to_end.py shows the full read → load_section → typed-config flow on CPython; see any consumer library (starting with chumicro-wifi) for the integrated usage shape.

Contributing

Working on chumicro-config 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-config
• Bundle: ChuMicro-Bundle (CircuitPython & MicroPython)
• Experimental bundle: ChuMicro-Bundle-Experimental
• Source: libraries/config

License

MIT