[Feat] Add deprecated=True to CLI args (vllm-project#17426)

Signed-off-by: Aaron Pham <contact@aarnphm.xyz>

Author: aarnphm

vllm/engine/arg_utils.py

@@ -531,6 +531,7 @@ def add_cli_args(parser: FlexibleArgumentParser) -> FlexibleArgumentParser:
         guided_decoding_group.add_argument(
             "--enable-reasoning",
             action=argparse.BooleanOptionalAction,
+            deprecated=True,
             help="[DEPRECATED] The `--enable-reasoning` flag is deprecated as "
             "of v0.8.6. Use `--reasoning-parser` to specify the reasoning "
             "parser backend insteadThis flag (`--enable-reasoning`) will be "

vllm/utils.py

@@ -33,14 +33,15 @@
 import warnings
 import weakref
 from argparse import (Action, ArgumentDefaultsHelpFormatter, ArgumentParser,
-                      ArgumentTypeError)
+                      ArgumentTypeError, _ArgumentGroup)
 from asyncio import FIRST_COMPLETED, AbstractEventLoop, Task
 from collections import UserDict, defaultdict
 from collections.abc import (AsyncGenerator, Awaitable, Generator, Hashable,
                              Iterable, Iterator, KeysView, Mapping)
 from concurrent.futures.process import ProcessPoolExecutor
 from dataclasses import dataclass, field
 from functools import cache, lru_cache, partial, wraps
+from gettext import gettext as _gettext
 from types import MappingProxyType
 from typing import (TYPE_CHECKING, Any, Callable, Generic, Literal, NamedTuple,
                     Optional, Sequence, Tuple, Type, TypeVar, Union, cast,
@@ -71,6 +72,8 @@
 from vllm.logger import enable_trace_function_call, init_logger
 
 if TYPE_CHECKING:
+    from argparse import Namespace
+
     from vllm.config import ModelConfig, VllmConfig
 
 logger = init_logger(__name__)
@@ -1324,16 +1327,78 @@ def add_arguments(self, actions):
         super().add_arguments(actions)
 
 
+class _FlexibleArgumentGroup(_ArgumentGroup):
+
+    def __init__(self, parser: FlexibleArgumentParser, *args, **kwargs):
+        self._parser = parser
+        super().__init__(*args, **kwargs)
+
+    def add_argument(self, *args: Any, **kwargs: Any):
+        if sys.version_info < (3, 13):
+            deprecated = kwargs.pop('deprecated', False)
+            action = super().add_argument(*args, **kwargs)
+            object.__setattr__(action, 'deprecated', deprecated)
+            if deprecated and action.dest not in \
+                    self._parser.__class__._deprecated:
+                self._parser._deprecated.add(action)
+            return action
+
+        # python>3.13
+        return super().add_argument(*args, **kwargs)
+
+
 class FlexibleArgumentParser(ArgumentParser):
     """ArgumentParser that allows both underscore and dash in names."""
 
+    _deprecated: set[Action] = set()
+    _seen: set[str] = set()
+
     def __init__(self, *args, **kwargs):
         # Set the default 'formatter_class' to SortedHelpFormatter
         if 'formatter_class' not in kwargs:
             kwargs['formatter_class'] = SortedHelpFormatter
         super().__init__(*args, **kwargs)
 
-    def parse_args(self, args=None, namespace=None):
+    if sys.version_info < (3, 13):
+
+        def parse_known_args(  # type: ignore[override]
+            self,
+            args: Sequence[str] | None = None,
+            namespace: Namespace | None = None,
+        ) -> tuple[Namespace | None, list[str]]:
+            namespace, args = super().parse_known_args(args, namespace)
+            for action in FlexibleArgumentParser._deprecated:
+                if action.dest not in FlexibleArgumentParser._seen and getattr(
+                        namespace, action.dest,
+                        None) != action.default:  # noqa: E501
+                    self._warning(
+                        _gettext("argument '%(argument_name)s' is deprecated")
+                        % {'argument_name': action.dest})
+                    FlexibleArgumentParser._seen.add(action.dest)
+            return namespace, args
+
+        def add_argument(self, *args: Any, **kwargs: Any):
+            # add a deprecated=True compatibility
+            # for python < 3.13
+            deprecated = kwargs.pop('deprecated', False)
+            action = super().add_argument(*args, **kwargs)
+            object.__setattr__(action, 'deprecated', deprecated)
+            if deprecated and \
+                action not in FlexibleArgumentParser._deprecated:
+                self._deprecated.add(action)
+
+            return action
+
+        def _warning(self, message: str):
+            self._print_message(
+                _gettext('warning: %(message)s\n') % {'message': message},
+                sys.stderr)
+
+    def parse_args(  # type: ignore[override]
+        self,
+        args: list[str] | None = None,
+        namespace: Namespace | None = None,
+    ):
         if args is None:
             args = sys.argv[1:]
 
@@ -1504,6 +1569,15 @@ def _load_config_file(self, file_path: str) -> list[str]:
 
         return processed_args
 
+    def add_argument_group(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> _FlexibleArgumentGroup:
+        group = _FlexibleArgumentGroup(self, self, *args, **kwargs)
+        self._action_groups.append(group)
+        return group
+
 
 async def _run_task_with_lock(task: Callable, lock: asyncio.Lock, *args,
                               **kwargs):