Explanation¶
Why, rather than how. These pages are for reading rather than looking things up, and they are worth reading once you have used the module for something, because the reasoning lands better when you have already met the behaviour.
Much of config is deliberately counter-intuitive: it refuses writes from inside observers,
drops snapshots that a newer one superseded, and hands back a usable store alongside an
error. Each of those looks like a bug until you know why it is there. That is what this
section is for.
Start with the one rule¶
Almost every design decision falls out of a single sentence.
The Store: one component owns all configuration I/O. Nothing else reads, writes or watches a source; everything else is a view over the immutable snapshot it publishes. Read this first, because the rest of the section is consequences of it.
What follows from it¶
| Page | Explains |
|---|---|
| Precedence & merge model | How a value is resolved when several sources define it, why merging is per key rather than per file, and what happens to lists and maps. |
| Provenance | What Origin, DefinedIn and Explain can tell you about where a value came from and, as importantly, what they cannot. |
| What survives a write | Why your comments, key order, quoting and anchors are still there afterwards: the file is edited, not regenerated. |
| Hot-reload safety | Why reloading under a running process is safe: snapshots, fail-closed parsing, and reads that stay coherent across a change. |
| Backends and capabilities | What a backend is, and why being readable does not make a source writable or watchable. |
The adapter family¶
One store, many sources. These five explain how a source that is not a local YAML file joins the merge as an ordinary layer.
| Page | Explains |
|---|---|
| The adapter ecosystem | Every adapter in the family, what each reads and writes, its status and what it adds to your dependency graph. |
| How filesystem adapters work | The config.FS contract, and how an embedded filesystem, a remote host and a cloud object store all satisfy the same six methods. |
| How dynamic backends work | What every remote backend shares (watch strategies, conflict detection, sensitive layers) and where the systems legitimately differ. |
| How the Consul backend works | The reference implementation in detail: its data model, its compare-and-swap writes and its native watch. |
| Who owns the connection | The four ways an adapter gets its client, why injection stays the default, and why sharing one credential resolution is always deliberate. |
Elsewhere¶
- Tutorials: learn the behaviour first; this section reads better afterwards.
- How-to guides: the task-shaped route.
- Reference: the exact rules, when you need the edge cases rather than the reasoning.
- Feature specifications: the decision records these pages summarise, with the alternatives that were rejected.