Wiring Application Configuration

Configuration bugs are quiet because every layer on the path has a fallback. A value travels defaults → user file → merge → consumer, and each hop can drop it without raising anything. The result is an application that starts cleanly, reports success, and runs on values the user did not choose.

Use a typed settings model when you can. pydantic-settings, a tagged struct, or any schema-first loader collapses most of this page into one class: unknown keys and wrong types fail at construction, and every consumer gets attribute access instead of config["a"]["b"]. Reach for the hand-rolled merge below only when you genuinely need a layered file surface the typed model doesn't cover — and then port the guarantees, don't skip them.

A config key is a contract between two files. Check both ends.

The reader indexes one section; the defaults declare another: