Module environment 

Environment normalization, home directory resolution, and Python interpreter discovery.

Provides:

• Home directory resolution with sudo context handling (VAL-PLAT-017)
• .mlstack_env normalization producing consistent, idempotent environment (VAL-PLAT-018)
• Python interpreter discovery across venvs, conda, and system paths (VAL-PLAT-020)

Sudo Context

When running under sudo, the real user’s home directory is resolved via:

1. MLSTACK_USER_HOME env var
2. $HOME (if not /root)
3. /etc/passwd lookup for SUDO_USER / USER / LOGNAME

Python Discovery Priority

1. MLSTACK_PYTHON_BIN / UV_PYTHON env vars
2. Active virtualenv (VIRTUAL_ENV)
3. Conda environments
4. System Python (/usr/bin/python3, etc.)
5. Component venvs (~/rocm_venv/bin/python)

.mlstack_env Normalization

The env file is idempotent: running normalization twice produces the same output as running it once. Duplicate PATH/LD_LIBRARY_PATH entries are removed, and all required variables are present.

Enums

EnvUpdateResult

Result of .mlstack_env normalization.

Functions

dedup_path_var

Deduplicate colon-separated path entries.

generate_env_file

Generate a new .mlstack_env file from scratch.

lookup_home_from_passwd

Look up a user’s home directory from /etc/passwd.

normalize_env_contents

Normalize the contents of a .mlstack_env file.

normalize_mlstack_env

Normalize the .mlstack_env file in the user’s home directory.

python_interpreters

Discover Python interpreter paths in priority order, deduplicated.

python_interpreters_for_home

Discover Python interpreters for a given home directory (testable).

resolve_canonical_python_bin

Resolve the canonical Python binary path.

resolve_user_home

Resolve the real user’s home directory, handling sudo context.