chore: more recovery

Author: KelvinChung2000

cmd2/annotated.py

@@ -336,7 +336,10 @@ def _resolve(_tp: Any, args: tuple[Any, ...], *, has_default: bool = False, **_c
                 'container_factory': collection_type,
             }
         if len(args) != 1:
-            return {}  # pragma: no cover
+            raise TypeError(
+                f"{collection_type.__name__}[...] with {len(args)} type arguments is not supported; "
+                f"use {collection_type.__name__}[T] with a single element type."
+            )
         element_type, inner = _resolve_element(args[0])
         return {
             **inner,
@@ -375,7 +378,10 @@ def _resolve_tuple(_tp: Any, args: tuple[Any, ...], *, has_default: bool = False
         _, inner = _resolve_element(first)
         return {**inner, 'is_collection': True, 'nargs': len(args), 'base_type': first, **cast_kwargs}
 
-    return {}  # pragma: no cover
+    raise TypeError(
+        "tuple with Ellipsis in an unexpected position is not supported; "
+        "use tuple[T, ...] for variable-length or tuple[T, T] for fixed-arity."
+    )
 
 
 def _resolve_literal(_tp: Any, args: tuple[Any, ...], **_ctx: Any) -> dict[str, Any]:
@@ -478,8 +484,10 @@ def _unwrap_optional(tp: type) -> tuple[type, bool]:
         if len(non_none) == 1:
             if has_none:
                 return non_none[0], True
-            # Single-element union without None shouldn't happen, pass through
-            return non_none[0], False  # pragma: no cover
+            raise TypeError(
+                f"Unexpected single-element Union without None: Union[{non_none[0]}]. "
+                f"Use the type directly instead of wrapping in Union."
+            )
         type_names = ' | '.join(a.__name__ if hasattr(a, '__name__') else str(a) for a in non_none)
         raise TypeError(f"Union type {type_names} is ambiguous for auto-resolution.")
     return tp, False
@@ -597,8 +605,9 @@ def _validate_base_command_params(
 
 
 # Parameters that are handled specially by the decorator and should not
-# be added to the argparse parser.
-_SKIP_PARAMS = frozenset({'self', 'cmd2_handler', 'cmd2_statement'})
+# be added to the argparse parser.  The first positional parameter (self/cls)
+# is always skipped by position; these cover additional decorator-managed names.
+_SKIP_PARAMS = frozenset({'cmd2_handler', 'cmd2_statement'})
 
 
 def _resolve_parameters(
@@ -617,7 +626,12 @@ def _resolve_parameters(
 
     resolved: list[_ResolvedParam] = []
 
-    for name, param in sig.parameters.items():
+    # Skip the first parameter by position (self/cls for methods)
+    params = list(sig.parameters.items())
+    if params:
+        params = params[1:]
+
+    for name, param in params:
         if name in skip_params:
             continue
 
@@ -766,7 +780,7 @@ def build_parser_from_function(
     Parameters without defaults become positional arguments.
     Parameters with defaults become ``--option`` flags.
     ``Annotated[T, Argument(...)]`` or ``Annotated[T, Option(...)]``
-    overrides the default behaviour.
+    overrides the default behavior.
 
     :param func: the command function to inspect
     :param skip_params: parameter names to exclude from the parser
@@ -844,7 +858,7 @@ def build_subcommand_handler(
     if base_command:
         _validate_base_command_params(func)
 
-    _accepted = set(inspect.signature(func).parameters.keys()) - {'self'}
+    _accepted = set(list(inspect.signature(func).parameters.keys())[1:])
 
     @functools.wraps(func)
     def handler(self_arg: Any, ns: Any) -> Any:

cmd2/decorators.py

@@ -352,38 +352,71 @@ def with_annotated(
     ns_provider: Callable[..., argparse.Namespace] | None = None,
     preserve_quotes: bool = False,
     with_unknown_args: bool = False,
-    subcommand_to: str | None = None,
     base_command: bool = False,
+    subcommand_to: str | None = None,
     help: str | None = None,  # noqa: A002
     aliases: Sequence[str] | None = None,
+    groups: tuple[tuple[str, ...], ...] | None = None,
+    mutually_exclusive_groups: tuple[tuple[str, ...], ...] | None = None,
 ) -> Any:
     """Decorate a ``do_*`` method to build its argparse parser from type annotations.
 
-    Can be used bare or with keyword arguments::
-
-        @with_annotated
-        def do_greet(self, name: str, count: int = 1): ...
-
-        @with_annotated(preserve_quotes=True)
-        def do_raw(self, text: str): ...
-
     :param func: the command function (when used without parentheses)
-    :param ns_provider: optional namespace provider, mirroring ``with_argparser``
-    :param preserve_quotes: if True, preserve quotes in arguments
-    :param with_unknown_args: if True, capture unknown args (passed as extra kwarg ``_unknown``)
+    :param ns_provider: optional callable returning a prepopulated argparse.Namespace.
+                        Not supported with ``subcommand_to``.
+    :param preserve_quotes: if True, preserve quotes in arguments.
+                            Not supported with ``subcommand_to``.
+    :param with_unknown_args: if True, capture unknown args (passed as extra kwarg ``_unknown``).
+                              Not supported with ``subcommand_to``.
+    :param base_command: if True, this command has subcommands (adds ``add_subparsers()``).
+                         Requires a ``cmd2_handler`` parameter and no positional arguments.
+    :param subcommand_to: parent command name (e.g. ``'team'`` or ``'team member'``).
+                          Function must be named ``{parent_underscored}_{subcommand}``.
+    :param help: help text for the subcommand (only valid with ``subcommand_to``)
+    :param aliases: alternative names for the subcommand (only valid with ``subcommand_to``)
+    :param groups: tuples of parameter names to place in argument groups (for help display)
+    :param mutually_exclusive_groups: tuples of parameter names that are mutually exclusive
+
+    Example::
+
+        class MyApp(cmd2.Cmd):
+            @with_annotated
+            def do_greet(self, name: str, count: int = 1): ...
+
+            @with_annotated(base_command=True)
+            def do_team(self, *, cmd2_handler): ...
+
+            @with_annotated(subcommand_to='team', help='create a team')
+            def team_create(self, name: str): ...
+
     """
     from .annotated import (
+        _SKIP_PARAMS,
         _filtered_namespace_kwargs,
         _validate_base_command_params,
         build_parser_from_function,
         build_subcommand_handler,
     )
     from .argparse_custom import Cmd2AttributeWrapper
 
-    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
-        if subcommand_to is None and (help is not None or aliases):
-            raise TypeError("with_annotated(help=..., aliases=...) requires subcommand_to=...")
+    if (help is not None or aliases is not None) and subcommand_to is None:
+        raise TypeError("'help' and 'aliases' are only valid with subcommand_to")
+    if subcommand_to is not None:
+        unsupported: list[str] = []
+        if ns_provider is not None:
+            unsupported.append('ns_provider')
+        if preserve_quotes:
+            unsupported.append('preserve_quotes')
+        if with_unknown_args:
+            unsupported.append('with_unknown_args')
+        if unsupported:
+            names = ', '.join(unsupported)
+            raise TypeError(
+                f"{names} {'is' if len(unsupported) == 1 else 'are'} not supported with subcommand_to. "
+                "Configure these behaviors on the base command instead."
+            )
 
+    def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
         if with_unknown_args:
             unknown_param = inspect.signature(fn).parameters.get('_unknown')
             if unknown_param is None:
@@ -396,10 +429,12 @@ def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
                 fn,
                 subcommand_to,
                 base_command=base_command,
+                groups=groups,
+                mutually_exclusive_groups=mutually_exclusive_groups,
             )
             setattr(handler, constants.SUBCMD_ATTR_COMMAND, subcommand_to)
-            setattr(handler, constants.CMD_ATTR_ARGPARSER, subcmd_parser_builder)
             setattr(handler, constants.SUBCMD_ATTR_NAME, subcmd_name)
+            setattr(handler, constants.CMD_ATTR_ARGPARSER, subcmd_parser_builder)
             add_parser_kwargs: dict[str, Any] = {}
             if help is not None:
                 add_parser_kwargs['help'] = help
@@ -409,13 +444,21 @@ def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
             return handler
 
         command_name = fn.__name__[len(constants.COMMAND_FUNC_PREFIX) :]
+
+        skip_params = _SKIP_PARAMS | ({'_unknown'} if with_unknown_args else frozenset())
         if base_command:
-            _validate_base_command_params(fn)
+            _validate_base_command_params(fn, skip_params=skip_params)
 
-        accepted = set(inspect.signature(fn).parameters.keys()) - {'self'}
+        # Cache signature introspection at decoration time, not per-invocation
+        accepted = set(list(inspect.signature(fn).parameters.keys())[1:])
 
         def parser_builder() -> argparse.ArgumentParser:
-            parser = build_parser_from_function(fn)
+            parser = build_parser_from_function(
+                fn,
+                skip_params=skip_params,
+                groups=groups,
+                mutually_exclusive_groups=mutually_exclusive_groups,
+            )
             if base_command:
                 parser.add_subparsers(dest='subcommand', metavar='SUBCOMMAND', required=True)
             return parser