[Misc] Add deprecated environment variable utilities

[carlory]

Purpose

Add general-purpose utilities for handling deprecated environment variables with deprecation warnings. These functions can be reused across the codebase when deprecating environment variables in favor of CLI arguments or config options.

This addresses the suggestion from @hmellor in PR #33536 to add general versions of the removed _get_from_env_if_set and _set_from_env_if_set methods to utils.py for reuse in future deprecations.

New functions added to vllm/utils/system_utils.py:

• get_deprecated_env_var(): Get value from deprecated env var with warning
• set_from_deprecated_env_var(): Set object field from deprecated env var with optional type conversion (bool/int)

Usage example:

from vllm.utils.system_utils import set_from_deprecated_env_var

# In a config class validator:
set_from_deprecated_env_var(
    self,
    field_name="torch_profiler_dir",
    env_var_name="VLLM_TORCH_PROFILER_DIR",
    alternative="--profiler-config.torch_profiler_dir"
)

set_from_deprecated_env_var(
    self,
    field_name="delay_iterations",
    env_var_name="VLLM_PROFILER_DELAY_ITERS",
    to_int=True,
    deprecation_version="v0.15.0",
    alternative="--profiler-config.delay_iterations"
)

Test Plan

1. Run linting: pre-commit run --files vllm/utils/system_utils.py
2. Run type checking: pre-commit run --hook-stage manual mypy-3.12 --files vllm/utils/system_utils.py
3. Verify module imports correctly:

   python -c "from vllm.utils.system_utils import get_deprecated_env_var, set_from_deprecated_env_var; print('OK')"

Test Result

All pre-commit hooks pass:

ruff check..........................................................................................Passed
ruff format.........................................................................................Passed
typos...............................................................................................Passed
Run mypy locally for lowest supported Python version................................................Passed
Check SPDX headers..................................................................................Passed

Import verification:

$ python -c "from vllm.utils.system_utils import get_deprecated_env_var, set_from_deprecated_env_var; print('OK')"
OK

[gemini-code-assist]

Code Review

The pull request introduces general-purpose utilities for handling deprecated environment variables, which is a valuable addition for managing feature deprecation in the codebase. The new functions get_deprecated_env_var and set_from_deprecated_env_var provide a centralized mechanism for issuing warnings and facilitating transitions. However, there are critical issues in the type handling and conversion logic within these functions that need to be addressed to ensure correct behavior.

[hmellor]

Thanks for this PR! Could the utilities please be moved to the config utils? The only place we should be using these is when we are forwarding environment variables to the config fields that replace them

[carlory]

@hmellor updated.

[mergify]

This pull request has merge conflicts that must be resolved before it can be
merged. Please rebase the PR, @carlory.

https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork

[mergify]

Hi @carlory, the pre-commit checks have failed. Please run:

uv pip install pre-commit
pre-commit install
pre-commit run --all-files

Then, commit the changes and push to your branch.

For future commits, pre-commit will run automatically on changed files before each commit.

Tip

Is mypy or markdownlint failing?

mypy and markdownlint are run differently in CI. If the failure is related to either of these checks, please use the following commands to run them locally:

# For mypy (substitute "3.10" with the failing version if needed)
pre-commit run --hook-stage manual mypy-3.10
# For markdownlint
pre-commit run --hook-stage manual markdownlint

[hmellor]

LGTM! Thanks for adding back these utilities