chore: minor improvement and more clean up

KelvinChung2000 · KelvinChung2000 · commit b8e08334a2b6 · 2026-03-24T22:50:24.000Z
diff --git a/cmd2/annotated.py b/cmd2/annotated.py
@@ -39,8 +39,7 @@ def do_paint(
 
 - ``str`` -- default string argument
 - ``int``, ``float`` -- sets ``type=`` for argparse
-- ``bool`` with default ``False`` -- ``--flag`` with ``store_true``
-- ``bool`` with default ``True`` -- ``--no-flag`` with ``store_false``
+- ``bool`` with default -- ``--flag / --no-flag`` via ``BooleanOptionalAction``
 - positional ``bool`` -- parsed from ``true/false``, ``yes/no``, ``on/off``, ``1/0``
 - ``pathlib.Path`` -- sets ``type=Path``
 - ``enum.Enum`` subclass -- ``type=converter``, ``choices`` from member values
@@ -278,20 +277,15 @@ def _resolve_bool(
     _args: tuple[Any, ...],
     *,
     is_positional: bool,
-    has_default: bool,
-    default: Any,
     metadata: ArgMetadata,
+    **_ctx: Any,
 ) -> dict[str, Any]:
     """Resolve bool -- flag or positional depending on context."""
     if not is_positional:
         action_str = getattr(metadata, 'action', None) if metadata else None
         if action_str:
-            action = action_str
-        elif has_default and default is True:
-            action = 'store_false'
-        else:
-            action = 'store_true'
-        return {'action': action, 'is_bool_flag': True}
+            return {'action': action_str, 'is_bool_flag': True}
+        return {'action': argparse.BooleanOptionalAction, 'is_bool_flag': True}
     return {'type': _parse_bool}
 
 
@@ -307,8 +301,18 @@ def _make_collection_resolver(collection_type: type) -> Callable[..., dict[str,
     """Create a resolver for single-arg collections (list[T], set[T])."""
 
     def _resolve(_tp: Any, args: tuple[Any, ...], *, has_default: bool = False, **_ctx: Any) -> dict[str, Any]:
+        if len(args) == 0:
+            # Bare list/tuple without type args -- treat as list[str]/set[str]
+            nargs = '*' if has_default else '+'
+            return {
+                'is_collection': True,
+                'nargs': nargs,
+                'base_type': str,
+                'action': _CollectionCastingAction,
+                'container_factory': collection_type,
+            }
         if len(args) != 1:
-            return {}
+            return {}  # pragma: no cover
         element_type, inner = _resolve_element(args[0])
         nargs = '*' if has_default else '+'
         return {
@@ -327,12 +331,17 @@ def _resolve_tuple(_tp: Any, args: tuple[Any, ...], *, has_default: bool = False
     """Resolve tuple[T, ...] and tuple[T1, T2, ...]."""
     cast_kwargs = {'action': _CollectionCastingAction, 'container_factory': tuple}
 
+    if not args:
+        # Bare tuple without type args -- treat as tuple[str, ...]
+        nargs = '*' if has_default else '+'
+        return {'is_collection': True, 'nargs': nargs, 'base_type': str, **cast_kwargs}
+
     if len(args) == 2 and args[1] is Ellipsis:
         element_type, inner = _resolve_element(args[0])
         nargs = '*' if has_default else '+'
         return {**inner, 'is_collection': True, 'nargs': nargs, 'base_type': element_type, **cast_kwargs}
 
-    if args and Ellipsis not in args:
+    if Ellipsis not in args:
         first = args[0]
         if not all(a == first for a in args[1:]):
             raise TypeError(
@@ -344,7 +353,7 @@ 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 {}
+    return {}  # pragma: no cover
 
 
 def _resolve_literal(_tp: Any, args: tuple[Any, ...], **_ctx: Any) -> dict[str, Any]:
@@ -425,8 +434,8 @@ def _resolve_annotation(
     *,
     has_default: bool = False,
     default: Any = None,
-) -> tuple[type, dict[str, Any], ArgMetadata, bool]:
-    """Decompose a type annotation into ``(base_type, type_kwargs, metadata, is_positional)``.
+) -> tuple[dict[str, Any], ArgMetadata, bool, bool]:
+    """Decompose a type annotation into ``(type_kwargs, metadata, is_positional, is_bool_flag)``.
 
     Peels in order: Annotated → Optional → type resolution.
     """
@@ -450,7 +459,9 @@ def _resolve_annotation(
         if len(args) == 1:
             tp = args[0]
             is_optional = True
-        elif len(args) > 1:
+        else:
+            # len > 1: ambiguous union (e.g. str | int)
+            # len == 0: all-None union -- unreachable via normal typing but handle defensively
             type_names = ' | '.join(a.__name__ if hasattr(a, '__name__') else str(a) for a in args)
             raise TypeError(f"Union type {type_names} is ambiguous for auto-resolution. ")
 
@@ -490,6 +501,11 @@ def _resolve_annotation(
     return type_kwargs, metadata, is_positional, is_bool_flag
 
 
+# Parameter names that conflict with argparse internals and cannot be used
+# as annotated parameter names.
+_RESERVED_PARAM_NAMES = frozenset({'dest'})
+
+
 # ---------------------------------------------------------------------------
 # Signature → Parser conversion
 # ---------------------------------------------------------------------------
@@ -513,18 +529,26 @@ def build_parser_from_function(func: Callable[..., Any]) -> argparse.ArgumentPar
     sig = inspect.signature(func)
     try:
         hints = get_type_hints(func, include_extras=True)
-    except (NameError, AttributeError, TypeError):
-        hints = {}
+    except (NameError, AttributeError, TypeError) as exc:
+        raise TypeError(
+            f"Failed to resolve type hints for {func.__qualname__}. Ensure all annotations use valid, importable types."
+        ) from exc
 
     for name, param in sig.parameters.items():
         if name == 'self':
             continue
 
+        if name in _RESERVED_PARAM_NAMES:
+            raise ValueError(
+                f"Parameter name {name!r} in {func.__qualname__} is reserved by argparse "
+                f"and cannot be used as an annotated parameter name."
+            )
+
         annotation = hints.get(name, param.annotation)
         has_default = param.default is not inspect.Parameter.empty
         default = param.default if has_default else None
 
-        kwargs, metadata, positional, is_bool_flag = _resolve_annotation(
+        kwargs, metadata, positional, _is_bool_flag = _resolve_annotation(
             annotation,
             has_default=has_default,
             default=default,
@@ -533,12 +557,7 @@ def build_parser_from_function(func: Callable[..., Any]) -> argparse.ArgumentPar
         if positional:
             parser.add_argument(name, **kwargs)
         else:
-            if isinstance(metadata, Option) and metadata.names:
-                flags = list(metadata.names)
-            elif is_bool_flag and has_default and default is True:
-                flags = [f'--no-{name}']
-            else:
-                flags = [f'--{name}']
+            flags = list(metadata.names) if isinstance(metadata, Option) and metadata.names else [f'--{name}']
             if isinstance(metadata, Option) and metadata.required:
                 kwargs['required'] = True
             kwargs['dest'] = name
diff --git a/cmd2/decorators.py b/cmd2/decorators.py
@@ -411,7 +411,9 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
             except SystemExit as exc:
                 raise Cmd2ArgparseError from exc
 
-            # Unpack Namespace into function kwargs, filtering cmd2 internals
+            # Unpack Namespace into function kwargs, filtering cmd2 internals.
+            # Note: "dest" keys could conflict with annotation names -- may need validation.
+            # Note: "required" handling when mixing with Options metadata needs verification.
             func_kwargs: dict[str, Any] = {}
             for key, value in vars(ns).items():
                 if key.startswith('cmd2_') or key == constants.NS_ATTR_SUBCMD_HANDLER:
diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md
@@ -89,8 +89,7 @@ The decorator converts Python type annotations into `add_argument()` calls:
 | -------------------------------------- | --------------------------------------------------- |
 | `str`                                  | default (no `type=` needed)                         |
 | `int`, `float`                         | `type=int` or `type=float`                          |
-| `bool` (default `False`)               | `--flag` with `action='store_true'`                 |
-| `bool` (default `True`)                | `--no-flag` with `action='store_false'`             |
+| `bool` (with default)                  | `--flag / --no-flag` via `BooleanOptionalAction`    |
 | positional `bool`                      | parsed from `true/false`, `yes/no`, `on/off`, `1/0` |
 | `Path`                                 | `type=Path`                                         |
 | `Enum` subclass                        | `type=converter`, `choices` from member values      |
diff --git a/examples/annotated_example.py b/examples/annotated_example.py
@@ -110,9 +110,8 @@ def do_copy(self, src: Path, dst: Path) -> None:
 
     # -- Bool flags ----------------------------------------------------------
     # With @with_argparser you'd set action='store_true' or 'store_false'.
-    # Here bool defaults drive the flag style automatically.
-    #   False default -> --flag (store_true)
-    #   True default  -> --no-flag (store_false)
+    # Here bool defaults use BooleanOptionalAction automatically, giving
+    # both --flag and --no-flag from a single parameter.
 
     @cmd2.with_annotated
     @cmd2.with_category(ANNOTATED_CATEGORY)
@@ -122,10 +121,10 @@ def do_build(
         verbose: bool = False,
         color: bool = True,
     ) -> None:
-        """Build a target. Bool flags are inferred from defaults.
+        """Build a target. Bool flags use BooleanOptionalAction.
 
-        ``verbose: bool = False`` becomes ``--verbose`` (store_true).
-        ``color: bool = True`` becomes ``--no-color`` (store_false).
+        ``verbose: bool = False`` becomes ``--verbose / --no-verbose``.
+        ``color: bool = True`` becomes ``--color / --no-color``.
 
         Try:
             build app --verbose --no-color
@@ -224,6 +223,80 @@ def do_echo(self, text: str) -> None:
         """
         self.poutput(text)
 
+    # -- Subcommands ---------------------------------------------------------
+    # @with_annotated can be the parent command that dispatches to
+    # subcommands registered via @as_subcommand_to. The parent needs
+    # a manual parser with add_subparsers() since subparser setup
+    # can't be inferred from annotations.
+
+    @staticmethod
+    def _build_team_parser() -> cmd2.Cmd2ArgumentParser:
+        parser = cmd2.Cmd2ArgumentParser(description="Manage teams")
+        parser.add_subparsers(dest='subcommand', metavar='SUBCOMMAND', required=True)
+        return parser
+
+    @cmd2.with_argparser(_build_team_parser)
+    @cmd2.with_category(ANNOTATED_CATEGORY)
+    def do_team(self, args) -> None:
+        """Manage teams. Uses subcommands via @as_subcommand_to.
+
+        Try:
+            team create Warriors
+            team list
+            help team
+            help team create
+        """
+        handler = args.cmd2_handler.get()
+        if handler:
+            handler(args)
+
+    _team_create_parser = cmd2.Cmd2ArgumentParser(description="Create a new team")
+    _team_create_parser.add_argument('name', help='team name')
+    _team_create_parser.add_argument('--city', default='Unknown', help='home city')
+
+    @cmd2.as_subcommand_to('team', 'create', _team_create_parser, help='create a new team')
+    def team_create(self, args) -> None:
+        self.poutput(f"Created team: {args.name} ({args.city})")
+        self._sports.append(args.name)
+
+    _team_list_parser = cmd2.Cmd2ArgumentParser(description="List all teams")
+
+    @cmd2.as_subcommand_to('team', 'list', _team_list_parser, help='list all teams')
+    def team_list(self, _args) -> None:
+        for sport in self._sports:
+            self.poutput(f"  - {sport}")
+
+    # -- Argument groups (mutually exclusive) --------------------------------
+    # Argument groups are a parser-level feature. With @with_argparser you
+    # build them manually. They work alongside @with_annotated commands.
+
+    @staticmethod
+    def _build_output_parser() -> cmd2.Cmd2ArgumentParser:
+        parser = cmd2.Cmd2ArgumentParser(description="Output with format options")
+        parser.add_argument('message', help='message to output')
+        fmt_group = parser.add_mutually_exclusive_group()
+        fmt_group.add_argument('--json', action='store_true', help='output as JSON')
+        fmt_group.add_argument('--csv', action='store_true', help='output as CSV')
+        fmt_group.add_argument('--plain', action='store_true', default=True, help='output as plain text')
+        return parser
+
+    @cmd2.with_argparser(_build_output_parser)
+    @cmd2.with_category(ANNOTATED_CATEGORY)
+    def do_output(self, args) -> None:
+        """Output a message with mutually exclusive format options.
+
+        Try:
+            output hello --json
+            output hello --csv
+            output hello --json --csv   (error: mutually exclusive)
+        """
+        if args.json:
+            self.poutput(f'{{"message": "{args.message}"}}')
+        elif args.csv:
+            self.poutput(f'message,{args.message}')
+        else:
+            self.poutput(args.message)
+
 
 if __name__ == '__main__':
     app = AnnotatedExample()
diff --git a/tests/test_annotated.py b/tests/test_annotated.py
diff --git a/tests/test_completer_type_infer.py b/tests/test_completer_type_infer.py
