kevinveenbirkenbachandClaude Opus 5
d7bd200da1
Three modules reimplemented what utils.cache already offers, and each paid
for it with a suppression.
test_compose_override_services_defined carried a yaml.SafeLoader subclass
whose only job was to swallow compose's own tags, plus a noqa for the
yaml.load rule it then tripped. load_yaml_any handles !override and !reset
already, so the loader and the suppression both go.
test_compose_bind_sources_exist read default.env directly and argued in a
nocheck marker that once per session is fine. Reading it through
utils.cache.files makes the argument unnecessary.
test_gpu_gate loaded the role's vars and meta files with raw yaml over
hand-assembled paths; it now uses load_yaml with ROLE_FILE_VARS_MAIN and
ROLE_FILE_META_SERVICES, the way 50a13c755b did for the playwright
multipliers.
gpu_count drops a noqa ruff no longer raises, and the development env module
an import nothing uses, which lint-python rejects.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
utils/env 📐
This directory hosts the Python implementation behind make dotenv.
For the general rules that govern READMEs in code directories see documentation.md.
For the per-variable defaults that this code consumes see default.env.
Purpose 🎯
The package converts the committed default.env plus a small runtime context into the gitignored .env at the repo root.
Every module here belongs to one of four roles: parse, resolve, orchestrate, write.
Structure 🗂️
| File | Role |
|---|---|
parser.py |
Read default.env into (values, comments) tuples. |
runtime.py |
Resolve host-context lookups (disk, RAM, hostname, GHA/Act flags, /proc/version, helper-script invocation). |
builder.py |
Thin orchestrator that defines EnvBuilder, BuildContext, and build_env(). Walks the handler registry. |
writer.py |
Serialise an EnvBuilder into a docker-compose-compatible .env on disk. |
handlers/ |
One module per dynamically-computed variable. See handlers README. |
The CLI entry point lives at __main__.py under cli/meta/env/.
Shell consumers source load.sh under scripts/meta/env/.
File Naming 🏷️
- Module names MUST stay lowercase snake_case.
- Pure passthrough or simple parser/writer helpers MUST live directly under
utils/env/. - Per-variable computation MUST live under
handlers/(see handlers README for the naming convention used there). - Test files live in tests/unit/python/utils/env/ and mirror the module name with a
test_prefix.
Machine Facts vs Run Facts 🧭
The writer a handler picks decides how long a value lives. Both kinds are registered in default.env and both are visible to the lints; they differ only in whether the generated .env remembers what the environment said.
| Writer | Meaning | On the next make dotenv |
|---|---|---|
eb.setdefault |
machine fact | a non-empty value in the process env is adopted and written back |
eb.set |
run fact | recomputed from BuildContext; whatever the process env said is discarded |
setdefault is the operator-override contract: exporting a key changes it and the change persists. That persistence is why it MUST NOT carry a value an environment declares for a single run. Makefile exports BASH_ENV, so every make recipe sources .env — a value adopted once is re-exported into every later recipe and into every container that mounts the repo, and a per-run decision has silently become a property of the machine.
A key that some environment declares per run therefore MUST be written by a dedicated handler through eb.set. The exporting shell still wins for its own run, because load.sh preserves non-empty caller values when it sources .env; the file keeps the derived default. INFINITO_RUNNING_ON_GITHUB and INFINITO_CACHE_STACK are written this way. Note the consequence: for those keys .env and the running shell can legitimately disagree, and .env is not the authority.
Import Rules 🔗
parser.py,runtime.py, andwriter.pyMUST NOT import frombuilder.pyorhandlers/.builder.pyMUST NOT import individual handler modules; it MUST go through theORDERED_HANDLERSlist exposed byhandlers/__init__.py.- Handler modules MUST NOT import each other (see handlers README).