Python Environment Variables and Configuration

Every environment variable is a string. os.environ behaves like a dictionary of them:

import os
os.environ["WORKSHOP_NAME"]                      # KeyError if missing
os.environ.get("WORKSHOP_NAME", "Canal Workshop")
os.getenv("WORKSHOP_NAME", "Canal Workshop")     # same as .get()
"WORKSHOP_NAME" in os.environ                    # True or False

Use os.environ["NAME"] when the setting is required and a missing value is an error; use os.getenv("NAME", default) for optional settings.

Variables are set outside Python: export STOCK_BATCH=50 in macOS and Linux shells, $env:STOCK_BATCH = "50" in PowerShell, set STOCK_BATCH=50 in Command Prompt, or through your hosting platform's dashboard. A running program sees only the environment it was started with; changing a variable in another terminal has no effect. Assigning to os.environ inside Python affects the current process and any child processes it starts, which is handy in tests.

Because values are text, convert them once, at start-up, and validate the result:

import os

def env_int(name, default, low=None, high=None):
    raw = os.getenv(name, str(default))
    try:
        value = int(raw)
    except ValueError:
        raise ValueError(f"{name} must be a whole number, got {raw!r}") from None
    if low is not None and value < low:
        raise ValueError(f"{name} must be at least {low}")
    if high is not None and value > high:
        raise ValueError(f"{name} must be at most {high}")
    return value

def env_bool(name, default=False):
    raw = os.getenv(name)
    if raw is None:
        return default
    return raw.strip().lower() in ("1", "true", "yes", "on")

bool(os.getenv("DEBUG")) is a trap: any non-empty string, including "false" and "0", is truthy. Parse booleans by comparing words, as above. Converting everything up front means the rest of the program works with proper int, bool and Path values, and a misconfiguration stops the program immediately with a clear message rather than failing an hour later.

A setting the program can't run without should produce an actionable error at start-up: say which variable is missing and what it should contain.

import os, sys

missing = [name for name in ("DATABASE_URL", "STOCK_API_KEY") if not os.getenv(name)]
if missing:
    sys.exit(f"Missing required settings: {', '.join(missing)}. See README for setup.")

Collecting all missing names before exiting saves the person deploying the program from fixing them one restart at a time. Some settings are only required when a feature is enabled: check DATABASE_URL only if USE_DATABASE is true.

Be careful with fallbacks for important settings. A default such as os.getenv("DATABASE_URL", "postgres://localhost/prod") can silently connect a test run to the wrong database. Defaults are fine for harmless values like a display name or batch size; required connections and credentials should fail loudly when missing.

API keys, passwords and tokens must not be written in source code, because code is shared, copied and pushed to repositories where history keeps every version. Read them from the environment or a secrets manager instead, and keep them out of output:

token = os.environ["STOCK_API_KEY"]
print(f"Using API key ending ...{token[-4:]}")   # never print the full value

During development, many projects keep variables in a .env file:

WORKSHOP_NAME=Canal Workshop
STOCK_API_KEY=sk_test_abc123

Python doesn't read .env files by itself. The python-dotenv package loads one with from dotenv import load_dotenv; load_dotenv(). The file must be listed in .gitignore so it's never committed; share a .env.example with placeholder values instead. In production, use the platform's secret settings rather than a file. If a key is ever committed, treat it as leaked: revoke it and create a new one, because deleting the line doesn't remove it from history.

Code that reads os.environ directly is awkward to test, because each test would need to change the real environment. Two techniques keep tests simple:

• Pass the environment in as a mapping, as Settings.from_env(env) does below, so tests can hand over a plain dictionary.
• In pytest, use the monkeypatch fixture to set or delete variables for a single test; it restores the original values afterwards.

def test_missing_key_stops_startup(monkeypatch):
    monkeypatch.delenv("STOCK_API_KEY", raising=False)
    monkeypatch.setenv("STOCK_BATCH", "10")
    ...

Test the unhappy paths too: a missing required setting, a non-numeric batch size and an out-of-range value should each produce the clear start-up error you designed.

Task: define required and optional workshop settings and validate them before processing stock.

import os

def load_settings(env):
    if "STOCK_API_KEY" not in env:
        raise SystemExit("Set STOCK_API_KEY before running the stock import")
    batch = int(env.get("STOCK_BATCH", "25"))
    if batch < 1:
        raise SystemExit("STOCK_BATCH must be at least 1")
    return {"name": env.get("WORKSHOP_NAME", "Canal Workshop"), "batch": batch}

print(load_settings({"STOCK_API_KEY": "x", "STOCK_BATCH": "40"}))
# {'name': 'Canal Workshop', 'batch': 40}

Passing a dictionary instead of os.environ makes the function easy to test with different inputs. For the worked check, os.getenv() returns a str when it finds a value; any other type must come from your own conversion.

The documentation describes os.environ and os.getenv; The Twelve-Factor App explains why configuration belongs in the environment. Continue with pip and virtual environments and API authentication. Practise with the Python exercises and Python quiz.