extract-python-environment-variables

name	extract-python-environment-variables
description	Scans a Python recipe to find every place an environment variable is accessed — including `os.environ.setdefault("V", "d")`, whose "d" would otherwise be a hidden default a user editing .env.example has no way to discover — then ensures all variables are declared in `.env.example`, that `load_dotenv()` is bootstrapped in the package `__init__.py`, and that `python-dotenv>=1.0.0` is listed in `pyproject.toml`. When a new entry is added to `.env.example`, the extracted default from source is written as the value (with a `# extracted-by:extract-env-vars` marker and provenance comment); values that look like stubs (`"my-project-id"`, `"changeme"`, `"<...>"`) are downgraded to the TODO placeholder but the source string is preserved in the marker comment. Also detects hardcoded model-name string literals (e.g. `"gemini-3.5-flash"` in `agent.py`) and rewrites them to an `os.getenv(...)` call. The variable name is derived from the assignment target when it names a model (`DEFAULT_EMBEDDING_MODEL` → `EMBEDDING_MODEL`), else `MODEL_NAME` (single model) or `MODEL_NAME_GENERATED_1` / `MODEL_NAME_GENERATED_2`, … (multiple models). Normally no fallback default is written into the Python source; the one exception is when no `load_dotenv()` bootstrap could be installed (no package `__init__.py`), where the original literal is kept as the fallback so the lookup cannot evaluate to `None` at runtime. The model string is written as the value in `.env.example` with a comment prompting a rename. When re-run against a recipe whose `.env.example` already has entries, the writer classifies each entry (skill-authored vs. user-authored, TODO vs. real value) and only rewrites lines it can prove it authored; user-authored lines are always preserved. A stale TODO (either skill-authored or a bare v1-era `<TODO: update-this-value>` with no inline comment) is upgraded in place when source can supply a real default. IMPORTANT — two hard rules the skill NEVER breaks: (1) USER-EDIT SAFETY. Any `.env.example` line the skill cannot prove it authored is USER_OWNED and is never modified. The rewriter fails closed on any structural ambiguity (quoted values, backslash continuation, duplicate declarations) — a stale TODO left in place is cheap; a clobbered user edit is not. (2) ADDITIVE-ONLY FOR PYTHON FILES. The skill never writes new `os.environ.setdefault(...)` bootstrap lines into any Python file. Pre-existing `os.environ.setdefault(...)` or `os.getenv("VAR", "default")` calls that the recipe author wrote by hand are LEFT UNTOUCHED — the skill's only writes to Python files are (a) the `load_dotenv()` bootstrap; (b) `# noqa: E402` on trailing relative imports that would otherwise trip Ruff; (c) hardcoded model-literal replacement. Use when the user wants to "extract env vars", "update .env.example", "add load_dotenv", "surface setdefault defaults", "upgrade stale TODOs in .env.example", "replace hardcoded model names", or "fix environment variables" in a Python recipe.
metadata	{"author":"Google","license":"Apache-2.0","version":"2.3.0"}

Extract Python Environment Variables

Use this skill to ensure a Python recipe properly declares and loads all environment variables it uses.

---

What This Skill Does

Runs scripts/extract_env_vars.py against a recipe directory. The script:

1. Scans all .py files (excluding tests/ and common cache/venv directories) for environment variable accesses:

   • os.environ["VAR"]
   • os.environ.get("VAR") / os.environ.get("VAR", "default")
   • os.getenv("VAR") / os.getenv("VAR", "default")
   • os.environ.setdefault("VAR", "default")   (v2)

   Only names matching ^[A-Z_][A-Z0-9_]*$ (UPPER_SNAKE_CASE) are captured; a lowercase name like os.getenv("my_api_key") is skipped and a [WARN] line lists any that were dropped. Rename such vars to uppercase in source, or add them to .env.example by hand.

2. Updates .env.example — appends any variables not already declared AND upgrades stale TODO entries in place. Existing user-authored lines are always preserved (see Rule 1 below).

   • Creates .env.example from scratch if it does not exist.
   • Each new/upgraded line has the shape:

     VAR=<value>  # extracted-by:extract-env-vars; <provenance>
     

   • <value> is the resolved default extracted from source when the author committed to one — with os.environ.setdefault(...) beating os.getenv("V", "d") / os.environ.get("V", "d") (setdefault is a stronger commitment: it mutates the process environment, while getenv fallback is per-read). Alphabetical file order breaks ties.
   • Values that look like stubs are downgraded to <TODO: update-this-value> — e.g. my-project-id, your-api-key, changeme, <...>, anything containing example.com. The source string is preserved in the marker comment so the maintainer sees what was found and can fix the source too.
   • When no source supplied a string-literal default, the value is with a note.