os, sys, and Environment Variables

## Two names for one lookup `os.environ` is not a live window onto the operating system's environment block; it is a `MutableMapping` object that the `os` module builds **once**, when it is first imported, by copying the environment the process was started with. `os.getenv(key, default=None)` is a thin convenience wrapper over that same mapping. So the whole difference between the two forms is the missing-key policy: * `os.environ["DB_URL"]` — mapping subscript. Missing key raises `KeyError`. * `os.getenv("DB_URL")` — returns `None` when the key is absent. * `os.getenv("DB_URL", "sqlite:///local.db")` — returns the supplied fallback when the key is absent. There is no performance difference worth naming and no difference in what gets read. The difference is entirely about what your program says it needs. ## Required versus optional is a design decision, not a style one Configuration splits cleanly in two. A **required** setting has no defensible default: the address of the datastore, the credential the service authenticates with, the ingest endpoint. A **optional** setting has one: a timeout, a batch size, a log level. Encode that split in the call you write. For required settings, let the lookup fail. The failure you want is *loud, immediate and at startup* — one message naming the variable, on `sys.stderr`, with a non-zero exit status — not a `TypeError` deep in a request path forty minutes later because something quietly became `None`. In practice teams wrap it: ```python import os import sys def required(name: str) -> str: try: return os.environ[name] except KeyError: sys.exit(f"missing required environment variable: {name}") ``` That helper is the whole pattern: subscript, catch `KeyError`, report the *name* of the variable, exit non-zero. A raw traceback also fails loudly, but the operator reading the container log gets a stack of frames instead of the one fact they need. For optional settings, `os.getenv(name, fallback)` is exactly right — and the fallback should be written as a **string**, matching what the environment would have provided, so that the coercion path is identical whether or not the variable was set. ## Everything is a string The environment is a flat `str` → `str` map. On POSIX platforms the raw bytes are decoded with the filesystem encoding and error handler; `os.environb` exposes the undecoded bytes view where the platform supports it, which `os.supports_bytes_environ` reports. Practically, this means the mapping never hands you an `int` or a `bool`: ```python timeout = float(os.getenv("COLLECTOR_TIMEOUT", "5.0")) debug = os.getenv("COLLECTOR_DEBUG", "").lower() in {"1", "true", "yes", "on"} ``` The classic bug is `bool(os.getenv("DEBUG", "false"))`, which is `True` — every non-empty string is truthy, and `"false"` is a non-empty string. Pick an explicit set of accepted truthy spellings and compare against it. For numbers, wrap the `int()` or `float()` call so a typo in a deploy manifest produces a message naming the variable rather than a bare `ValueError`. ## Set-but-empty is not unset `os.getenv("FEATURE_FLAG", "on")` returns `""`, not `"on"`, when the variable is present with an empty value — and `"FEATURE_FLAG" in os.environ` is `True`. Deployment systems produce empty values constantly: an unresolved template, a secret that failed to render, a shell that exported a variable from an empty variable. If an empty value should be treated as absent, say so explicitly (`os.getenv("X") or "on"`, or a check on the stripped value); do not assume the default covers it. This single gap accounts for a striking share of "the config default didn't apply in production" incidents. ## Reading once, at startup Both forms read the mapping at the moment they execute. Scattering `os.getenv` calls through modules that are imported at different times gives you configuration that is read at unpredictable points, cannot be seen as a whole, and is awkward to override in tests. Read every variable in one place during startup, coerce and validate there, and pass the resulting object down. That is also what makes the loud-failure guarantee real: a variable read lazily in a rarely-taken branch can only fail loudly on the day that branch runs. ## Secrets are strings like any other Values injected from a secret store arrive in the same mapping, which means they can end up in anything that renders the environment — a debug endpoint, a crash reporter that dumps process state, a helpful log line that prints the resolved config. Log the *keys* you resolved, never the values, and redact anything whose name matches a secret-ish pattern before printing a config summary.