Files
chenlin c32df70326
Checks / Layout, translation and Colab checks (push) Has been cancelled
Checks / Ruff (push) Has been cancelled
Checks / Framework tests (native backend, CPU) (push) Has been cancelled
Checks / Portable Rust controller (push) Has been cancelled
release: v0.1 generic robot training and application platform
2026-11-05 11:05:01 +08:00

145 lines
5.5 KiB
Python

"""A minimal `.env` reader with no third-party dependency.
It does one thing: fill the file's keys into `os.environ` **where nothing is set
yet**. Existing variables are never overwritten, which makes the precedence fall
out for free:
command line > shell environment > .env.local > .env > argument default
The entry points under `scripts/` call this **before** parsing arguments, and
argparse defaults then read from `os.environ` -- so "the command line wins if
given" needs no special-casing; that is already argparse's semantics.
`python-dotenv` is not used: twenty lines is all that is needed, and every extra
dependency is one more thing that may or may not be installed on a given machine.
"""
from __future__ import annotations
import os
from collections.abc import Sequence
from pathlib import Path
__all__ = ["parse_dotenv", "load_dotenv", "env_default", "env_flag", "env_choice"]
#: What counts as a switch in a `.env` file, in any case. `bool()` is no use
#: here -- `bool("off")` is True, so every "off" would read as an "on".
_TRUE = frozenset({"on", "true", "yes", "1"})
_FALSE = frozenset({"off", "false", "no", "0"})
def env_default(name: str, fallback: str | None = None) -> str | None:
"""Read an environment variable as an argument default; **an empty string
counts as unset**.
That way `MJRL_MODEL=` in `.env` means "leave it empty, use the built-in
default" rather than passing an empty string down as a real value.
"""
return os.environ.get(name, "").strip() or fallback
def env_flag(name: str, fallback: bool = False) -> bool:
"""Read an environment variable as an on/off switch.
`on/off`, `true/false`, `yes/no` and `1/0` are all accepted, in any case:
those are the spellings people write in a config file, and a switch that
honours exactly one of them is a switch that looks broken. Unset or empty
gives `fallback`.
Raises:
ValueError: for anything else, **rather than falling back**. Guessing
would mean `MJRL_TENSORBOARD=of` quietly meaning "on" -- the setting
has no visible effect, nothing says why, and the natural conclusion is
that the feature ignores its own configuration.
"""
raw = env_default(name)
if raw is None:
return fallback
value = raw.strip().lower()
if value in _TRUE:
return True
if value in _FALSE:
return False
raise ValueError(
f"{name}={raw!r} is not on or off "
f"(true/false, yes/no and 1/0 are accepted too, in any case)"
)
def env_choice(
name: str, choices: Sequence[str], fallback: str | None = None
) -> str | None:
"""Read an environment variable that has to be one of `choices`.
Matching ignores case and the value comes back in the spelling `choices` uses,
so a switch behaves the same way whichever key it is set through.
This exists because **argparse does not check a default against `choices`** --
only values actually typed on the command line. A `choices=[...]` argument
whose default comes from `.env` therefore validates nothing, and the bad value
travels on to whatever finally consumes it: `MJRL_STRIP_VISUAL=OFF` used to
surface as a bare `KeyError: 'OFF'` from a lookup table three call levels away.
Raises:
ValueError: naming the value and the choices, for the same reason
`env_flag` does rather than falling back.
"""
raw = env_default(name)
if raw is None:
return fallback
value = raw.strip().lower()
for choice in choices:
if choice.lower() == value:
return choice
raise ValueError(f"{name}={raw!r} is not one of: {', '.join(choices)}")
def parse_dotenv(text: str) -> dict[str, str]:
"""Parse `.env` text.
Supports `KEY=VALUE`, `export KEY=VALUE`, `#` comments, blank lines, and
quoting a value that contains spaces or `#`. Variable interpolation is not
supported -- a config file should not be a script.
"""
result: dict[str, str] = {}
for raw in text.splitlines():
line = raw.strip()
if not line or line.startswith("#"):
continue
if line.startswith("export "):
line = line[len("export ") :].lstrip()
key, sep, value = line.partition("=")
if not sep:
continue # not an assignment; ignore rather than error, to tolerate notes
key = key.strip()
if not key:
continue
value = value.strip()
if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
value = value[1:-1] # keep quoted content verbatim, including # and spaces
else:
value = value.split(" #", 1)[0].rstrip() # strip a trailing comment
result[key] = value
return result
def load_dotenv(*paths: Path) -> dict[str, str]:
"""Read several `.env` files in order, filling keys not already in `os.environ`.
Later files take precedence (`.env.local` should come after `.env`).
**Existing environment variables are never overwritten** -- a value exported
explicitly in the shell should beat one from a file.
Returns:
The keys and values actually written to `os.environ`, excluding those
skipped. A missing file is not an error.
"""
merged: dict[str, str] = {}
for path in paths:
if path.is_file():
merged.update(parse_dotenv(path.read_text(encoding="utf-8")))
applied = {k: v for k, v in merged.items() if k not in os.environ}
os.environ.update(applied)
return applied