349 lines
14 KiB
Python
349 lines
14 KiB
Python
"""Parsing `.env` and its precedence chain.
|
|
|
|
The chain rests on one rule: **`load_dotenv` does not overwrite existing
|
|
environment variables**. argparse defaults then read from `os.environ`, so
|
|
|
|
command line > shell environment > .env.local > .env > built-in default
|
|
|
|
follows for free, with no need to ask "did the user give this explicitly" -- which
|
|
is exactly the kind of judgement a config layer gets wrong.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import importlib.util
|
|
import os
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
|
|
from mjrl.dotenv import env_choice, env_default, env_flag, load_dotenv, parse_dotenv
|
|
|
|
REPO = Path(__file__).resolve().parents[1]
|
|
|
|
|
|
# ── Parsing ───────────────────────────────────────────────────────────────
|
|
|
|
|
|
def test_basic_key_value() -> None:
|
|
assert parse_dotenv("A=1\nB=two\n") == {"A": "1", "B": "two"}
|
|
|
|
|
|
def test_comments_and_blank_lines_ignored() -> None:
|
|
text = "# a comment\n\n \nA=1\n # an indented comment\n"
|
|
assert parse_dotenv(text) == {"A": "1"}
|
|
|
|
|
|
def test_export_prefix_accepted() -> None:
|
|
assert parse_dotenv("export A=1\n") == {"A": "1"}
|
|
|
|
|
|
def test_inline_comment_stripped() -> None:
|
|
assert parse_dotenv("A=1 # explanation\n") == {"A": "1"}
|
|
|
|
|
|
def test_quoted_value_keeps_spaces_and_hash() -> None:
|
|
"""A `#` inside quotes is not a comment. A path containing one is rare, but
|
|
silent truncation would be very hard to trace."""
|
|
assert parse_dotenv('A="a b # c"\n') == {"A": "a b # c"}
|
|
assert parse_dotenv("A='x y'\n") == {"A": "x y"}
|
|
|
|
|
|
def test_empty_value_is_kept_as_empty_string() -> None:
|
|
assert parse_dotenv("A=\n") == {"A": ""}
|
|
|
|
|
|
def test_line_without_equals_is_ignored() -> None:
|
|
"""Tolerate stray prose, so one line of notes does not stop every entry point
|
|
from starting."""
|
|
assert parse_dotenv("this is a sentence\nA=1\n") == {"A": "1"}
|
|
|
|
|
|
def test_value_containing_equals_is_not_split_again() -> None:
|
|
assert parse_dotenv("A=k=v\n") == {"A": "k=v"}
|
|
|
|
|
|
# ── Precedence ────────────────────────────────────────────────────────────
|
|
|
|
|
|
def test_existing_env_var_is_not_overwritten(
|
|
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
|
|
) -> None:
|
|
"""A value exported explicitly in the shell must beat .env -- the whole
|
|
precedence chain rests on this."""
|
|
monkeypatch.setenv("MJRL_TEST_KEY", "from_shell")
|
|
env = tmp_path / ".env"
|
|
env.write_text("MJRL_TEST_KEY=from_file\n", encoding="utf-8")
|
|
applied = load_dotenv(env)
|
|
assert "MJRL_TEST_KEY" not in applied
|
|
assert os.environ["MJRL_TEST_KEY"] == "from_shell"
|
|
|
|
|
|
def test_later_file_wins(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
|
|
""".env.local comes after .env and therefore overrides it."""
|
|
monkeypatch.delenv("MJRL_TEST_KEY", raising=False)
|
|
(tmp_path / ".env").write_text("MJRL_TEST_KEY=base\n", encoding="utf-8")
|
|
(tmp_path / ".env.local").write_text("MJRL_TEST_KEY=local\n", encoding="utf-8")
|
|
load_dotenv(tmp_path / ".env", tmp_path / ".env.local")
|
|
assert os.environ["MJRL_TEST_KEY"] == "local"
|
|
|
|
|
|
def test_missing_file_is_not_an_error(tmp_path: Path) -> None:
|
|
""".env.local usually does not exist, and a missing file must not crash an
|
|
entry point."""
|
|
assert load_dotenv(tmp_path / "nope.env") == {}
|
|
|
|
|
|
def test_empty_value_counts_as_unset(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
"""`MJRL_MODEL=` in `.env` means "leave it empty, use the built-in default",
|
|
not the empty string as a value."""
|
|
monkeypatch.setenv("MJRL_TEST_KEY", " ")
|
|
assert env_default("MJRL_TEST_KEY") is None
|
|
assert env_default("MJRL_TEST_KEY", "fallback") == "fallback"
|
|
|
|
|
|
# ── Switches ──────────────────────────────────────────────────────────────
|
|
|
|
|
|
@pytest.mark.parametrize("raw", ["on", "ON", "On", "true", "TRUE", "yes", "1", " on "])
|
|
def test_every_spelling_of_on(raw: str, monkeypatch: pytest.MonkeyPatch) -> None:
|
|
monkeypatch.setenv("MJRL_TEST_FLAG", raw)
|
|
assert env_flag("MJRL_TEST_FLAG", fallback=False) is True
|
|
|
|
|
|
@pytest.mark.parametrize("raw", ["off", "OFF", "Off", "false", "FALSE", "no", "0", " off "])
|
|
def test_every_spelling_of_off(raw: str, monkeypatch: pytest.MonkeyPatch) -> None:
|
|
"""`MJRL_TENSORBOARD=OFF` must turn it off.
|
|
|
|
This was the whole bug: the test was `!= "off"`, so every spelling but the
|
|
lowercase one left the feature **on** -- and there is nothing in the output to
|
|
say the setting was ignored, so it reads as a switch that does not work.
|
|
"""
|
|
monkeypatch.setenv("MJRL_TEST_FLAG", raw)
|
|
assert env_flag("MJRL_TEST_FLAG", fallback=True) is False
|
|
|
|
|
|
def test_unset_or_empty_takes_the_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
"""`MJRL_TENSORBOARD=` in `.env` means "use the built-in default", exactly as
|
|
an empty `MJRL_MODEL` does."""
|
|
monkeypatch.delenv("MJRL_TEST_FLAG", raising=False)
|
|
assert env_flag("MJRL_TEST_FLAG", fallback=True) is True
|
|
monkeypatch.setenv("MJRL_TEST_FLAG", " ")
|
|
assert env_flag("MJRL_TEST_FLAG", fallback=False) is False
|
|
|
|
|
|
@pytest.mark.parametrize("raw", ["of", "nope", "onn", "2", "-"])
|
|
def test_anything_else_raises_rather_than_falling_back(
|
|
raw: str, monkeypatch: pytest.MonkeyPatch
|
|
) -> None:
|
|
"""A value that is not a switch must not quietly become the default.
|
|
|
|
`MJRL_TENSORBOARD=of` reading as "on" is invisible: the feature behaves
|
|
normally and nothing mentions the setting. Erroring names the value, the way
|
|
a non-integer `MJRL_NUM_ENVS` does.
|
|
"""
|
|
monkeypatch.setenv("MJRL_TEST_FLAG", raw)
|
|
with pytest.raises(ValueError, match="MJRL_TEST_FLAG"):
|
|
env_flag("MJRL_TEST_FLAG", fallback=True)
|
|
|
|
|
|
# ── One of a fixed set of values ──────────────────────────────────────────
|
|
|
|
|
|
def test_a_choice_is_matched_case_insensitively(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
"""And comes back in the spelling the choices use, so callers can compare it."""
|
|
monkeypatch.setenv("MJRL_TEST_CHOICE", "OFF")
|
|
assert env_choice("MJRL_TEST_CHOICE", ("auto", "on", "off"), "auto") == "off"
|
|
monkeypatch.setenv("MJRL_TEST_CHOICE", " Auto ")
|
|
assert env_choice("MJRL_TEST_CHOICE", ("auto", "on", "off"), "auto") == "auto"
|
|
|
|
|
|
def test_a_choice_outside_the_set_raises(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
"""The value must not travel on to whatever consumes the argument.
|
|
|
|
`MJRL_STRIP_VISUAL=gpu` reaching the backend is not a config error any more --
|
|
it is a `KeyError` or a wrong run, somewhere with no mention of `.env`.
|
|
"""
|
|
monkeypatch.setenv("MJRL_TEST_CHOICE", "gpu")
|
|
with pytest.raises(ValueError, match="auto, on, off"):
|
|
env_choice("MJRL_TEST_CHOICE", ("auto", "on", "off"), "auto")
|
|
|
|
|
|
def test_an_unset_choice_takes_the_fallback(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
monkeypatch.delenv("MJRL_TEST_CHOICE", raising=False)
|
|
assert env_choice("MJRL_TEST_CHOICE", ("auto", "on"), "auto") == "auto"
|
|
|
|
|
|
# ── Reaching argparse: where these defaults actually land ─────────────────
|
|
|
|
|
|
def _parse(
|
|
argv: list[str],
|
|
env: dict[str, str],
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
*,
|
|
replay: bool = False,
|
|
):
|
|
"""Parse arguments the way an entry point does, and hand back `_cli` with them.
|
|
|
|
`replay` builds play's parser rather than train's.
|
|
|
|
`scripts/` is not a package and no test may put it on `sys.path`
|
|
(`test_no_sys_path_mutation` in test_layout.py), so `_cli` is loaded from its
|
|
file. Going through the real parser is the point: **argparse checks `choices`
|
|
only for values typed on the command line, never for a default**, so a bad
|
|
value in `.env` is caught here or not at all.
|
|
"""
|
|
for key, value in env.items():
|
|
monkeypatch.setenv(key, value)
|
|
spec = importlib.util.spec_from_file_location("_cli_under_test", REPO / "scripts" / "_cli.py")
|
|
assert spec and spec.loader
|
|
cli = importlib.util.module_from_spec(spec)
|
|
spec.loader.exec_module(cli)
|
|
prog = "play.py" if replay else "train.py"
|
|
return cli, cli.build_parser(prog, "", replay=replay).parse_args(argv)
|
|
|
|
|
|
def test_a_choice_from_dotenv_is_normalised(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
"""`MJRL_STRIP_VISUAL=OFF` used to reach `resolve_all` verbatim and die there
|
|
as `KeyError: 'OFF'`, with `.env` nowhere in the traceback."""
|
|
cli, args = _parse([], {"MJRL_STRIP_VISUAL": "OFF", "MJRL_BACKEND": "WARP"}, monkeypatch)
|
|
assert args.strip_visual == "off"
|
|
assert args.backend == "warp"
|
|
# The value has to be usable by what consumes it, which is the lookup table.
|
|
assert cli.STRIP_VISUAL[args.strip_visual] is False
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"env", [{"MJRL_STRIP_VISUAL": "nope"}, {"MJRL_BACKEND": "gpu"}]
|
|
)
|
|
def test_a_bad_choice_in_dotenv_stops_the_run(
|
|
env: dict, monkeypatch: pytest.MonkeyPatch
|
|
) -> None:
|
|
with pytest.raises(SystemExit):
|
|
_parse([], env, monkeypatch)
|
|
|
|
|
|
def test_the_command_line_still_wins(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
_, args = _parse(["--strip-visual", "on"], {"MJRL_STRIP_VISUAL": "OFF"}, monkeypatch)
|
|
assert args.strip_visual == "on"
|
|
|
|
|
|
def test_the_choices_and_the_lookup_table_are_one_definition(
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""What argparse accepts and what `resolve` is handed must not drift apart.
|
|
|
|
They were two separate literals, so a fourth `--strip-visual` state added to
|
|
the argument alone would pass the parser and be a `KeyError` in `resolve_all`.
|
|
"""
|
|
cli, _ = _parse([], {}, monkeypatch)
|
|
action = next(a for a in cli.build_parser("t", "")._actions if a.dest == "strip_visual")
|
|
assert set(action.choices) == set(cli.STRIP_VISUAL)
|
|
|
|
|
|
# ── Two counts under one flag ─────────────────────────────────────────────
|
|
|
|
|
|
def test_play_does_not_take_trainings_batch_size(monkeypatch: pytest.MonkeyPatch) -> None:
|
|
"""`MJRL_NUM_ENVS` is PPO's batch size, and a replay does not read it.
|
|
|
|
Sharing one key, the repository's 4096 built 4096 native CPU environments to
|
|
replay an app's controller that reads one, and never got past building them.
|
|
`MJRL_PLAY_NUM_ENVS` is set empty so that this pins the built-in 1 rather than
|
|
whatever `.env` says. Train, parsed from the same environment, is the
|
|
control: it still gets 4096, so the key was not simply dropped.
|
|
"""
|
|
env = {"MJRL_NUM_ENVS": "4096", "MJRL_PLAY_NUM_ENVS": ""}
|
|
_, play = _parse([], env, monkeypatch, replay=True)
|
|
_, train = _parse([], env, monkeypatch)
|
|
assert play.num_envs == 1
|
|
assert train.num_envs == 4096
|
|
|
|
|
|
def test_play_reads_its_own_key_and_the_command_line_still_wins(
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
env = {"MJRL_NUM_ENVS": "4096", "MJRL_PLAY_NUM_ENVS": "16"}
|
|
_, play = _parse([], env, monkeypatch, replay=True)
|
|
_, train = _parse([], env, monkeypatch)
|
|
_, typed = _parse(["--num_envs", "8"], env, monkeypatch, replay=True)
|
|
assert (play.num_envs, train.num_envs, typed.num_envs) == (16, 4096, 8)
|
|
|
|
|
|
def test_only_training_is_warned_about_its_batch_size(
|
|
monkeypatch: pytest.MonkeyPatch,
|
|
) -> None:
|
|
"""`resolve()` decides the warning; this pins that `resolve_all` tells it which
|
|
entry point is asking. A flag handed to a function and never passed on is the
|
|
failure this checks for, so train with the same count is the control."""
|
|
import tasks.registry as registry
|
|
monkeypatch.setitem(registry._REGISTRY, "fixture", registry.TaskSpec("fixture"))
|
|
argv = ["--task", "fixture", "--backend", "native", "--device", "cpu",
|
|
"--num_envs", "8"]
|
|
cli, play = _parse(argv, {}, monkeypatch, replay=True)
|
|
_, train = _parse(argv, {}, monkeypatch)
|
|
_, play_res, _ = cli.resolve_all(play)
|
|
_, train_res, _ = cli.resolve_all(train, for_training=True)
|
|
assert play_res.num_envs == train_res.num_envs == 8
|
|
assert not any("batch size" in n for n in play_res.notes), play_res.notes
|
|
assert any("batch size" in n for n in train_res.notes), train_res.notes
|
|
|
|
|
|
# ── The repository's own .env ─────────────────────────────────────────────
|
|
|
|
|
|
@pytest.mark.parametrize("raw", ["0", "-4", "2.5"])
|
|
def test_warp_capacity_flags_reject_invalid_integers(raw, monkeypatch) -> None:
|
|
with pytest.raises(SystemExit) as error:
|
|
_parse(["--warp-max-constraints", raw], {}, monkeypatch)
|
|
assert error.value.code == 2
|
|
|
|
|
|
def test_warp_capacity_flags_are_rejected_for_native(monkeypatch) -> None:
|
|
import tasks.registry as registry
|
|
|
|
monkeypatch.setitem(registry._REGISTRY, "fixture", registry.TaskSpec("fixture"))
|
|
cli, args = _parse([
|
|
"--task", "fixture", "--backend", "native", "--device", "cpu",
|
|
"--warp-max-constraints", "300", "--warp-max-contacts", "56",
|
|
], {}, monkeypatch)
|
|
assert (args.warp_max_constraints, args.warp_max_contacts) == (300, 56)
|
|
with pytest.raises(SystemExit, match="require Warp"):
|
|
cli.resolve_all(args)
|
|
|
|
|
|
def test_repo_dotenv_is_present_and_parses() -> None:
|
|
"""The committed example provides optional local defaults without secrets."""
|
|
env = REPO / ".env.example"
|
|
assert env.is_file(), "the repository root should have a .env.example"
|
|
parse_dotenv(env.read_text(encoding="utf-8"))
|
|
|
|
|
|
def test_repo_dotenv_declares_every_cli_backed_key() -> None:
|
|
"""Everything the CLI can set should have an entry in `.env`, or that file is
|
|
incomplete."""
|
|
keys = set(parse_dotenv((REPO / ".env.example").read_text(encoding="utf-8")))
|
|
expected = {
|
|
"MJRL_TASK",
|
|
"MJRL_MODEL",
|
|
"MJRL_BACKEND",
|
|
"MJRL_DEVICE",
|
|
"MJRL_NUM_ENVS",
|
|
"MJRL_PLAY_NUM_ENVS",
|
|
"MJRL_CPU_THREADS",
|
|
"MJRL_TENSORBOARD",
|
|
"MJRL_TB_PORT",
|
|
}
|
|
assert expected <= keys, f"`.env` is missing: {sorted(expected - keys)}"
|
|
|
|
|
|
def test_repo_dotenv_task_is_registered() -> None:
|
|
"""The default task in `.env` must really exist, or every entry point errors
|
|
out of the box."""
|
|
import tasks
|
|
|
|
task = parse_dotenv((REPO / ".env.example").read_text(encoding="utf-8")).get("MJRL_TASK", "")
|
|
if task.strip():
|
|
tasks.get(task.strip()) # raises KeyError when not registered
|