lib_layered_config

lib_layered_config

Config is annoying

Here is the odd thing about configuration bugs: hardly any of them are about the value. They are about authorship. By the time a setting reaches your program it has passed through as many as six hands - the defaults you shipped, a file in /etc, a per-host tweak, something in the user's home directory, a .env, and an environment variable a colleague exported months ago and forgot - and any hand along the way may have changed it. The number you finally read is the last whisper in a long game of telephone, and the library you read it with took no notes. So when the value is wrong, you are not debugging code. You are interviewing witnesses.

The sensible-looking shortcuts are exactly the ones that turn on you:

• Read os.environ.get("TIMEOUT", 30) in one module and a config.toml in another, and the real timeout is settled by whichever line ran first. Nobody wins the argument; nobody is even told there was one.
• Hard-code /etc/myapp/ because that is plainly where config lives - on Linux. On the macOS and Windows machines that make up most of your users, it lives somewhere else entirely.
• Trust "false" from a file as a boolean; a non-empty string is truthy, so you have just shipped with the safety switched off.
• Let a password rest in the config file, let the config file drift into git, and you have handed a secret a permanent home address.
• Assign to the shared settings dict from three call-frames deep, and "the configuration" now means different things depending on what ran when.

None of these are hard to fix once. They are hard to fix forever, because the single fact you need the moment it breaks - who set this value, and from where - was thrown away at the door.

Configuration, with a paper trail

lib_layered_config begins with the part every other approach discards: the paperwork. It deep-merges the six layers - defaults -> app -> host -> user -> dotenv -> env - into one immutable object, in a precedence that never shifts, and it keeps the receipt. Ask for a value and it answers; ask where the value came from and it names the exact layer and file. The witness interview collapses into a lookup.

What that buys you:

• One frozen object. read_config(...) returns a Config nothing downstream can mutate, so your program cannot quietly begin to disagree with itself.
• Every value carries its origin. config.origin("service.timeout") reports the layer and the path it came from. Debugging stops being a seance.
• The paths are already sorted. Linux (XDG), macOS, and Windows locations are resolved for you, so you never bake someone else's /etc into your code.
• One name switches the whole environment. Profiles keep test, staging, and production in separate trees; ask for profile="production" and you get production's config, not a hand-merged guess at it.
• Secrets sit above the file, not inside it. Environment variables and .env outrank the committed config, which therefore holds shape rather than passwords - and the CLI can redact on the way out.

Same engine from either side: from lib_layered_config import read_config as a library, or a lib_layered_config command that reads, deploys, and scaffolds configuration without a line of Python.