chore: more *args edge case handling

Author: KelvinChung2000

cmd2/annotated.py

@@ -61,7 +61,8 @@ def do_paint(
 - ``list[T]`` / ``set[T]`` / ``tuple[T, ...]`` -- ``nargs='+'`` (or ``'*'`` if has a default or is ``| None``)
 - ``tuple[T, T]`` (fixed arity, same type) -- ``nargs=N`` with ``type=T``
 - ``*args: T`` -- variadic positional with ``nargs='*'`` (zero or more), collected into a tuple.
-  ``T`` is the type of each value (a scalar), not the collected tuple
+  ``T`` is the type of each value (a scalar), not the collected tuple.
+  ``Annotated[T, Argument(...)]`` metadata (help text, metavar, choices) is honored
 - ``T | None`` (no default) -- positional with ``nargs='?'`` (accepts 0-or-1 tokens)
 - ``T | None = None`` -- ``--flag`` option with ``default=None``
 
@@ -87,6 +88,12 @@ def do_paint(
 - ``*args: tuple[T, ...]`` (or ``*args: list[T]`` / any collection element) -- on ``*args``
   the annotation is the type of each value, so a collection element would mean a
   tuple-of-collections.  Annotate the element type instead, e.g. ``*args: str``
+- ``*args: Annotated[T, Option(...)]`` -- ``*args`` is always positional, so ``Option()``
+  metadata is rejected; use ``Argument()`` instead
+- ``*args: Annotated[T, Argument(nargs=N)]`` -- ``*args`` arity is fixed to ``nargs='*'``
+  and cannot be overridden
+- a keyword-only parameter (after ``*``) annotated with ``Argument()`` metadata -- ``Argument()``
+  marks a positional, which contradicts keyword-only; use ``Option()`` or omit the metadata
 - ``Annotated[T, Argument(nargs=N)]`` where ``N`` produces a list (``'*'``, ``'+'``,
   or integer ``>= 1``) and ``T`` is not a collection type.  Use ``list[T]`` or
   ``tuple[T, ...]`` to match the runtime shape.
@@ -550,7 +557,7 @@ def _nargs_yields_list(nargs: Any) -> bool:
 
 
 def _resolve_type(
-    tp: type,
+    tp: Any,
     *,
     is_positional: bool = False,
     is_optional: bool = False,
@@ -837,10 +844,24 @@ def _resolve_parameters(
         if param.kind == inspect.Parameter.VAR_POSITIONAL:
             # ``*args: T`` is a variadic positional: zero or more values (nargs='*')
             # collected into a tuple. The hint gives the element type T (the type of
-            # each value), so annotating *args with a collection -- e.g.
-            # ``*args: tuple[str, ...]`` -- would mean each value is itself a tuple
-            # (a tuple-of-tuples), which cannot be mapped onto a flat command line.
-            element = hints.get(name, str)
+            # each value). Peel any Annotated/Optional so we see the real element
+            # type and any Argument() metadata (help text, metavar, choices, ...).
+            element, metadata, _element_optional = _normalize_annotation(hints.get(name, str))
+
+            if isinstance(metadata, Option):
+                raise TypeError(
+                    f"Parameter '*{name}' in {func.__qualname__} uses Option() metadata, but *args is "
+                    f"always a positional argument. Use Argument() metadata instead."
+                )
+            if isinstance(metadata, Argument) and metadata.nargs is not None:
+                raise TypeError(
+                    f"Parameter '*{name}' in {func.__qualname__} sets nargs={metadata.nargs!r} via Argument(), "
+                    f"but *args always accepts zero or more values (nargs='*') and its arity cannot be overridden."
+                )
+
+            # Annotating *args with a collection -- e.g. ``*args: tuple[str, ...]`` -- would
+            # mean each value is itself a tuple (a tuple-of-collections), which cannot be
+            # mapped onto a flat command line.
             _, element_kwargs = _resolve_type(element, is_positional=True)
             if element_kwargs.get("is_collection"):
                 # Show the parametrized form (e.g. ``tuple[str, ...]``), not the bare origin.
@@ -852,8 +873,15 @@ def _resolve_parameters(
                     f"'{element_display}'. Annotate the element type instead "
                     f"(e.g. '*{name}: str'); values are always collected into a tuple."
                 )
-            variadic_annotation = types.GenericAlias(tuple, (element, ...))
-            kwargs, metadata, positional = _resolve_annotation(variadic_annotation, is_variadic=True)
+
+            # Each value has type ``element``; values are collected into a tuple (nargs='*').
+            # ``is_optional=True`` selects nargs='*' (zero or more); any Argument() metadata
+            # (help text, metavar, choices) is applied to the variadic positional.
+            variadic_tuple = types.GenericAlias(tuple, (element, ...))
+            _, kwargs = _resolve_type(variadic_tuple, is_positional=True, is_optional=True, metadata=metadata)
+            kwargs.pop("is_collection", None)
+            kwargs.pop("base_type", None)
+            positional = True
         else:
             annotation = hints.get(name, param.annotation)
             has_default = param.default is not inspect.Parameter.empty
@@ -867,6 +895,13 @@ def _resolve_parameters(
                 is_kw_only=is_kw_only,
             )
 
+            if is_kw_only and isinstance(metadata, Argument):
+                raise TypeError(
+                    f"Parameter '{name}' in {func.__qualname__} is keyword-only but uses Argument() metadata, "
+                    f"which marks it as a positional argument. Keyword-only parameters always become options; "
+                    f"use Option() metadata (or omit the metadata) instead."
+                )
+
         if positional:
             flags: list[str] = []
         else:

tests/test_annotated.py

@@ -136,6 +136,12 @@ def _func_star_args_bare(self, *args) -> None: ...  # type: ignore[no-untyped-de
 def _func_star_args_tuple(self, *files: tuple[str, ...]) -> None: ...
 def _func_star_args_list(self, *xs: list[str]) -> None: ...
 def _func_star_args_bare_list(self, *xs: list) -> None: ...  # type: ignore[type-arg]
+def _func_star_args_meta(self, *files: Annotated[str, Argument(help_text="a file", metavar="FILE")]) -> None: ...
+def _func_star_args_meta_choices(self, *modes: Annotated[str, Argument(choices=["a", "b"])]) -> None: ...
+def _func_star_args_option_meta(self, *files: Annotated[str, Option("--files")]) -> None: ...
+def _func_star_args_nargs_meta(self, *files: Annotated[str, Argument(nargs=2)]) -> None: ...
+def _func_kw_only_argument(self, *, name: Annotated[str, Argument()]) -> None: ...
+def _func_kw_only_argument_default(self, *, name: Annotated[str, Argument()] = "x") -> None: ...
 def _func_var_keyword(self, name: str, **kwargs: str) -> None: ...
 def _func_dest_param(self, dest: str) -> None: ...
 def _func_kw_only(self, *, name: str) -> None: ...
@@ -526,6 +532,43 @@ def test_star_args_collection_element_raises(self, func) -> None:
         with pytest.raises(TypeError, match=r"the type of each value"):
             build_parser_from_function(func)
 
+    def test_star_args_honors_argument_metadata(self) -> None:
+        """``Annotated[T, Argument(...)]`` on ``*args`` applies help/metavar to the variadic positional."""
+        action = _get_param_action(_func_star_args_meta)
+        assert action.option_strings == []
+        assert action.nargs == "*"
+        assert action.help == "a file"
+        assert action.metavar == "FILE"
+
+    def test_star_args_honors_argument_choices(self) -> None:
+        """``Argument(choices=...)`` on ``*args`` restricts every value to the choices."""
+        parser = build_parser_from_function(_func_star_args_meta_choices)
+        assert parser.parse_args(["a", "b", "a"]).modes == ("a", "b", "a")
+        with pytest.raises(SystemExit):
+            parser.parse_args(["a", "nope"])
+
+    def test_star_args_option_metadata_raises(self) -> None:
+        """``Option()`` on ``*args`` is rejected; *args is always positional."""
+        with pytest.raises(TypeError, match=r"\*args is always a positional"):
+            build_parser_from_function(_func_star_args_option_meta)
+
+    def test_star_args_nargs_metadata_raises(self) -> None:
+        """An explicit ``nargs`` on ``*args`` is rejected; its arity is fixed to ``'*'``."""
+        with pytest.raises(TypeError, match=r"arity cannot be overridden"):
+            build_parser_from_function(_func_star_args_nargs_meta)
+
+    @pytest.mark.parametrize(
+        "func",
+        [
+            pytest.param(_func_kw_only_argument, id="no_default"),
+            pytest.param(_func_kw_only_argument_default, id="with_default"),
+        ],
+    )
+    def test_kw_only_with_argument_metadata_raises(self, func) -> None:
+        """A keyword-only parameter cannot use ``Argument()`` (which marks a positional)."""
+        with pytest.raises(TypeError, match=r"keyword-only but uses Argument\(\)"):
+            build_parser_from_function(func)
+
     def test_optional_annotated_outside_raises(self) -> None:
         with pytest.raises(TypeError, match="Annotated"):
             build_parser_from_function(_func_optional_annotated_outside)