feat: add support for subcommand and groups

Author: tleonhardt

cmd2/annotated.py

@@ -743,12 +743,11 @@ def _get_raw_choices(self, arg_state: _ArgumentState) -> list[CompletionItem] |
 
                 return ChoicesCallable(is_completer=True, to_call=Cmd.path_complete)
 
-            if isinstance(action_type, type) and issubclass(action_type, enum.Enum):
-                return [CompletionItem(str(m.value), display_meta=m.name) for m in action_type]
-
-            enum_from_converter = getattr(action_type, '_cmd2_enum_class', None)
-            if isinstance(enum_from_converter, type) and issubclass(enum_from_converter, enum.Enum):
-                return [CompletionItem(str(m.value), display_meta=m.name) for m in enum_from_converter]
+            enum_class = action_type if isinstance(action_type, type) and issubclass(action_type, enum.Enum) else None
+            if enum_class is None:
+                enum_class = getattr(action_type, '_cmd2_enum_class', None)
+            if isinstance(enum_class, type) and issubclass(enum_class, enum.Enum):
+                return [CompletionItem(str(m.value), display_meta=m.name) for m in enum_class]
 
         return None
 

cmd2/argparse_completer.py

@@ -308,6 +308,14 @@ class AsyncAlert:
     timestamp: float = field(default_factory=time.monotonic, init=False)
 
 
+class _ConsoleCache(threading.local):
+    """Thread-local storage for cached Rich consoles used by core print methods."""
+
+    def __init__(self) -> None:
+        self.stdout: Cmd2BaseConsole | None = None
+        self.stderr: Cmd2BaseConsole | None = None
+
+
 class Cmd:
     """An easy but powerful framework for writing line-oriented command interpreters.
 
@@ -441,6 +449,9 @@ def __init__(
         self.scripts_add_to_history = True  # Scripts and pyscripts add commands to history
         self.timing = False  # Prints elapsed time for each command
 
+        # Cached Rich consoles used by core print methods.
+        self._console_cache = _ConsoleCache()
+
         # The maximum number of items to display in a completion table. If the number of completion
         # suggestions exceeds this number, then no table will appear.
         self.max_completion_table_items: int = 50
@@ -1324,28 +1335,57 @@ def visible_prompt(self) -> str:
         """
         return su.strip_style(self.prompt)
 
-    def _create_base_printing_console(
+    def _get_core_print_console(
         self,
         *,
         file: IO[str],
         emoji: bool,
         markup: bool,
         highlight: bool,
     ) -> Cmd2BaseConsole:
-        """Create a Cmd2BaseConsole with formatting overrides.
+        """Get a console configured for the specified stream and formatting settings.
+
+        This method is intended for internal use by cmd2's core print methods.
+        To avoid the overhead of repeated initialization, it manages a thread-local
+        cache for consoles targeting ``self.stdout`` or ``sys.stderr``. It returns a cached
+        instance if its configuration matches the request. For all other streams, or if
+        the configuration has changed, a new console is created.
+
+        Note: This implementation works around a bug in Rich where passing formatting settings
+        (emoji, markup, and highlight) directly to console.print() or console.log() does not
+        always work when printing certain Renderables. Passing them to the constructor instead
+        ensures they are correctly propagated. Once this bug is fixed, these parameters can
+        be removed from this method. For more details, see:
+        https://github.com/Textualize/rich/issues/4028
+        """
+        # Dictionary of settings to check against cached consoles
+        kwargs = {
+            "emoji": emoji,
+            "markup": markup,
+            "highlight": highlight,
+        }
 
-        This works around a bug in Rich where passing these formatting settings directly to
-        console.print() or console.log() does not always work when printing certain Renderables.
-        Passing them to the constructor instead ensures they are correctly propagated.
+        # Check if we should use or update a cached console
+        if file is self.stdout:
+            cached = self._console_cache.stdout
+            if cached is not None and cached.matches_config(file=file, **kwargs):
+                return cached
 
-        See: https://github.com/Textualize/rich/issues/4028
-        """
-        return Cmd2BaseConsole(
-            file=file,
-            emoji=emoji,
-            markup=markup,
-            highlight=highlight,
-        )
+            # Create new console and update cache
+            self._console_cache.stdout = Cmd2BaseConsole(file=file, **kwargs)
+            return self._console_cache.stdout
+
+        if file is sys.stderr:
+            cached = self._console_cache.stderr
+            if cached is not None and cached.matches_config(file=file, **kwargs):
+                return cached
+
+            # Create new console and update cache
+            self._console_cache.stderr = Cmd2BaseConsole(file=file, **kwargs)
+            return self._console_cache.stderr
+
+        # For any other file, just create a new console
+        return Cmd2BaseConsole(file=file, **kwargs)
 
     def print_to(
         self,
@@ -1398,7 +1438,7 @@ def print_to(
         See the Rich documentation for more details on emoji codes, markup tags, and highlighting.
         """
         try:
-            self._create_base_printing_console(
+            self._get_core_print_console(
                 file=file,
                 emoji=emoji,
                 markup=markup,
@@ -1714,7 +1754,7 @@ def ppaged(
                 soft_wrap = True
 
             # Generate the bytes to send to the pager
-            console = self._create_base_printing_console(
+            console = self._get_core_print_console(
                 file=self.stdout,
                 emoji=emoji,
                 markup=markup,

cmd2/cmd2.py

@@ -280,7 +280,7 @@ def arg_decorator(func: ArgparseCommandFunc[CmdOrSet]) -> RawCommandFuncOptional
         """
 
         @functools.wraps(func)
-        def cmd_wrapper(*args: Any, **kwargs: dict[str, Any]) -> bool | None:
+        def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
             """Command function wrapper which translates command line into argparse Namespace and call actual command function.
 
             :param args: All positional arguments to this function.  We're expecting there to be:
@@ -349,24 +349,73 @@ def cmd_wrapper(*args: Any, **kwargs: dict[str, Any]) -> bool | None:
 def with_annotated(
     func: Callable[..., Any] | None = None,
     *,
+    ns_provider: Callable[..., argparse.Namespace] | None = None,
     preserve_quotes: bool = False,
     with_unknown_args: bool = False,
+    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::
+    .. warning:: Experimental -- behaviour may change in future releases.
 
+    :param func: the command function (when used without parentheses)
+    :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:
+    ```py
+    class MyApp(cmd2.Cmd):
         @with_annotated
         def do_greet(self, name: str, count: int = 1): ...
 
-        @with_annotated(preserve_quotes=True)
-        def do_raw(self, text: str): ...
+        @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): ...
+    ```
 
-    :param func: the command function (when used without parentheses)
-    :param preserve_quotes: if True, preserve quotes in arguments
-    :param with_unknown_args: if True, capture unknown args (passed as extra kwarg ``_unknown``)
     """
-    from .annotated import build_parser_from_function
+    from .annotated import (
+        _filtered_namespace_kwargs,
+        _validate_base_command_params,
+        build_parser_from_function,
+        build_subcommand_handler,
+    )
+
+    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:
@@ -376,45 +425,96 @@ def decorator(fn: Callable[..., Any]) -> Callable[..., Any]:
             if unknown_param.kind is inspect.Parameter.POSITIONAL_ONLY:
                 raise TypeError('Parameter _unknown must be keyword-compatible when with_unknown_args=True')
 
+        if subcommand_to is not None:
+            handler, subcmd_name, parser_builder = build_subcommand_handler(
+                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.SUBCMD_ATTR_NAME, subcmd_name)
+            setattr(handler, constants.CMD_ATTR_ARGPARSER, parser_builder)
+            add_parser_kwargs: dict[str, Any] = {}
+            if help is not None:
+                add_parser_kwargs['help'] = help
+            if aliases:
+                add_parser_kwargs['aliases'] = aliases[:]
+            setattr(handler, constants.SUBCMD_ATTR_ADD_PARSER_KWARGS, add_parser_kwargs)
+            return handler
+
+        if base_command:
+            _validate_base_command_params(fn, include_unknown=with_unknown_args)
+
+        # ---- Normal do_* command ----
         command_name = fn.__name__[len(constants.COMMAND_FUNC_PREFIX) :]
 
+        # Cache signature introspection at decoration time, not per-invocation
+        _accepted_params = set(inspect.signature(fn).parameters.keys()) - {'self'}
+
         @functools.wraps(fn)
-        def cmd_wrapper(*args: Any, **_kwargs: Any) -> bool | None:
+        def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
             cmd2_app, statement_arg = _parse_positionals(args)
             owner = args[0]  # Cmd or CommandSet instance
-            _statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(
+            statement, parsed_arglist = cmd2_app.statement_parser.get_command_arg_list(
                 command_name, statement_arg, preserve_quotes
             )
 
             arg_parser = cmd2_app._command_parsers.get(cmd_wrapper)
             if arg_parser is None:
                 raise ValueError(f'No argument parser found for {command_name}')
 
+            # Resolve namespace provider (same logic as with_argparser)
+            if ns_provider is None:
+                namespace = None
+            else:
+                provider_self = cmd2_app._resolve_func_self(ns_provider, args[0])
+                namespace = ns_provider(provider_self if provider_self is not None else cmd2_app)
+
             try:
                 if with_unknown_args:
-                    ns, unknown = arg_parser.parse_known_args(parsed_arglist)
+                    ns, unknown = arg_parser.parse_known_args(parsed_arglist, namespace)
                 else:
-                    ns = arg_parser.parse_args(parsed_arglist)
+                    ns = arg_parser.parse_args(parsed_arglist, namespace)
                     unknown = None
             except SystemExit as exc:
                 raise Cmd2ArgparseError from exc
 
-            # Unpack Namespace into function kwargs
-            func_kwargs: dict[str, Any] = {}
-            for key, value in vars(ns).items():
-                if key.startswith('cmd2_') or key == constants.NS_ATTR_SUBCMD_HANDLER:
-                    continue
-                func_kwargs[key] = value
+            # Extract user-defined kwargs from a parsed Namespace, excluding cmd2 internals.
+            func_kwargs = _filtered_namespace_kwargs(ns, exclude_subcommand=True)
+
+            # Inject cmd2-specific kwargs that commands can opt into
+            func_kwargs['cmd2_statement'] = Cmd2AttributeWrapper(statement)
+            raw_handler = getattr(ns, constants.NS_ATTR_SUBCMD_HANDLER, None)
+            bound_handler = (lambda _h=raw_handler, _ns=ns: _h(_ns)) if raw_handler is not None else None
+            func_kwargs['cmd2_handler'] = Cmd2AttributeWrapper(bound_handler)
 
             if with_unknown_args:
                 func_kwargs['_unknown'] = unknown
 
-            result: bool | None = fn(owner, **func_kwargs)
+            filtered_kwargs = {k: v for k, v in func_kwargs.items() if k in _accepted_params}
+
+            # Direct wrapper kwargs (e.g. do_greet("x", keyword_arg="y")) override parsed values
+            for key in kwargs:
+                filtered_kwargs.pop(key, None)
+
+            result: bool | None = fn(owner, **filtered_kwargs, **kwargs)
             return result
 
-        # Store a parser-builder callable — _CommandParsers._build_parser()
-        # already handles callables by calling them with no arguments.
-        setattr(cmd_wrapper, constants.CMD_ATTR_ARGPARSER, lambda: build_parser_from_function(fn))
+        # Store a parser-builder callable
+        def _build_cmd_parser() -> argparse.ArgumentParser:
+            parser = build_parser_from_function(
+                fn,
+                include_unknown=with_unknown_args,
+                groups=groups,
+                mutually_exclusive_groups=mutually_exclusive_groups,
+            )
+            if base_command:
+                parser.add_subparsers(dest='subcommand', metavar='SUBCOMMAND', required=True)
+            return parser
+
+        setattr(cmd_wrapper, constants.CMD_ATTR_ARGPARSER, _build_cmd_parser)
         setattr(cmd_wrapper, constants.CMD_ATTR_PRESERVE_QUOTES, preserve_quotes)
 
         return cmd_wrapper

cmd2/decorators.py

@@ -160,6 +160,9 @@ def __init__(
                 "Passing 'theme' is not allowed. Its behavior is controlled by the global APP_THEME and set_theme()."
             )
 
+        # Store the configuration used to create this console for caching purposes.
+        self._config_key = self._generate_config_key(file=file, **kwargs)
+
         force_terminal: bool | None = None
         force_interactive: bool | None = None
 
@@ -180,6 +183,41 @@ def __init__(
             **kwargs,
         )
 
+    @staticmethod
+    def _generate_config_key(
+        *,
+        file: IO[str] | None,
+        **kwargs: Any,
+    ) -> tuple[Any, ...]:
+        """Generate a key representing the settings used to initialize a console.
+
+        This key includes the file identity, global settings (ALLOW_STYLE, APP_THEME),
+        and any other settings passed in via kwargs.
+
+        :param file: file stream being checked
+        :param kwargs: other console settings
+        """
+        return (
+            id(file),
+            ALLOW_STYLE,
+            id(APP_THEME),
+            tuple(sorted(kwargs.items())),
+        )
+
+    def matches_config(
+        self,
+        *,
+        file: IO[str] | None,
+        **kwargs: Any,
+    ) -> bool:
+        """Check if this console instance was initialized with the specified settings.
+
+        :param file: file stream being checked
+        :param kwargs: other console settings being checked
+        :return: True if the settings match this console's configuration
+        """
+        return self._config_key == self._generate_config_key(file=file, **kwargs)
+
     def on_broken_pipe(self) -> None:
         """Override which raises BrokenPipeError instead of SystemExit."""
         self.quiet = True

cmd2/rich_utils.py

@@ -0,0 +1,3 @@
+# cmd2.annotated
+
+::: cmd2.annotated

docs/api/annotated.md

@@ -13,6 +13,7 @@ incremented according to the [Semantic Version Specification](https://semver.org
 
 - [cmd2.Cmd](./cmd.md) - functions and attributes of the main class in this library
 - [cmd2.argparse_completer](./argparse_completer.md) - classes for `argparse`-based tab completion
+- [cmd2.annotated](./annotated.md) - experimental helpers for building parsers from type annotations
 - [cmd2.argparse_custom](./argparse_custom.md) - classes and functions for extending `argparse`
 - [cmd2.clipboard](./clipboard.md) - functions to copy from and paste to the clipboard/pastebuffer
 - [cmd2.colors](./colors.md) - StrEnum of all color names supported by the Rich library