Metadata-Version: 2.4
Name: chumicro-config-experimental
Version: 0.7.2
Summary: Standardized runtime-config helpers for ChuMicro libraries — section loader + on-device runtime-config reader.
Project-URL: Homepage, https://github.com/ChuMicro/ChuMicro
Project-URL: Documentation, https://chumicro.github.io/ChuMicro/config/experimental/
Project-URL: Source, https://github.com/ChuMicro/ChuMicro/tree/main/libraries/config
Project-URL: Issues, https://github.com/ChuMicro/ChuMicro/issues
Project-URL: Bundle, https://github.com/ChuMicro/ChuMicro-Bundle-Experimental
Author: ChuMicro
License-Expression: MIT
Keywords: circuitpython,config,embedded,esp32,microcontroller,micropython,rp2040,settings
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Embedded Systems
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.11
Requires-Dist: chumicro-msgpack-experimental>=0.2.0
Provides-Extra: test
Requires-Dist: chumicro-test-harness; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# chumicro-config

<img src="https://raw.githubusercontent.com/ChuMicro/ChuMicro/main/support/docs/chumicro_tip.png"
align="left" width="64" style="margin-right: 16px; margin-bottom: 8px;">

**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.

<br clear="left">

> Part of the [ChuMicro](https://github.com/ChuMicro/ChuMicro) family — small, focused Python libraries for microcontrollers and laptops. [Browse all libraries.](https://github.com/ChuMicro/ChuMicro/tree/main/libraries)

## Install

```bash
# 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](https://github.com/ChuMicro/ChuMicro/blob/main/INSTALL.md).

## Quick example

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

```python
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`):

```python
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`](../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`](../wifi/) additionally uses the `load_section` helper here.  Other consumers: [`chumicro-mqtt`](../mqtt/), [`chumicro-ntp`](../ntp/), [`chumicro-requests`](../requests/), [`chumicro-websockets`](../websockets/), [`chumicro-http_server`](../http_server/).

## Platform support

Works on CPython, MicroPython, and CircuitPython.

## Examples

[`examples/end_to_end.py`](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](https://github.com/ChuMicro/ChuMicro) if you haven't already — the rest of the workflow assumes you're inside that workspace.

```bash
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](https://chumicro.github.io/ChuMicro/config/stable/)** · **[Experimental docs](https://chumicro.github.io/ChuMicro/config/experimental/)**

## Find this library

- **PyPI:** [chumicro-config](https://pypi.org/project/chumicro-config/)
- **Bundle:** [ChuMicro-Bundle](https://github.com/ChuMicro/ChuMicro-Bundle/tree/main/chumicro_config) (CircuitPython & MicroPython)
- **Experimental bundle:** [ChuMicro-Bundle-Experimental](https://github.com/ChuMicro/ChuMicro-Bundle-Experimental/tree/main/chumicro_config)
- **Source:** [libraries/config](https://github.com/ChuMicro/ChuMicro/tree/main/libraries/config)

## License

[MIT](https://github.com/ChuMicro/ChuMicro/blob/main/LICENSE)
