Added attach_subcommand() and detach_subcommand() to public API.

Author: kmvanbrunt

cmd2/argparse_custom.py

@@ -243,6 +243,7 @@ def get_choices(self) -> Choices:
 from argparse import ArgumentError
 from collections.abc import (
     Callable,
+    Iterable,
     Iterator,
     Sequence,
 )
@@ -927,6 +928,68 @@ def add_subparsers(self, **kwargs: Any) -> argparse._SubParsersAction:  # type:
 
         return super().add_subparsers(**kwargs)
 
+    def _find_subparsers_action(self) -> argparse._SubParsersAction:  # type: ignore[type-arg]
+        """Find the _SubParsersAction for this parser.
+
+        :return: the _SubParsersAction for this parser
+        :raises ValueError: if this parser does not support subcommands
+        """
+        for action in self._actions:
+            if isinstance(action, argparse._SubParsersAction):
+                return action
+        raise ValueError(f"Command '{self.prog}' does not support subcommands")
+
+    def _find_parser(self, subcommand_path: Iterable[str]) -> 'Cmd2ArgumentParser':
+        """Find a parser in the hierarchy based on a sequence of subcommand names.
+
+        :param subcommand_path: sequence of subcommand names leading to the target parser
+        :return: the discovered Cmd2ArgumentParser
+        :raises ValueError: if any subcommand in the path is not found or a level doesn't support subcommands
+        """
+        parser = self
+        for name in subcommand_path:
+            subparsers_action = parser._find_subparsers_action()
+            if name not in subparsers_action.choices:
+                raise ValueError(f"Subcommand '{name}' not found in '{parser.prog}'")
+            parser = cast(Cmd2ArgumentParser, subparsers_action.choices[name])
+        return parser
+
+    def attach_subcommand(
+        self,
+        subcommand_path: Iterable[str],
+        subcommand: str,
+        parser: 'Cmd2ArgumentParser',
+        **add_parser_kwargs: Any,
+    ) -> None:
+        """Attach a parser as a subcommand to a command at the specified path.
+
+        :param subcommand_path: sequence of subcommand names leading to the parser that will
+                                host the new subcommand. An empty sequence indicates this parser.
+        :param subcommand: name of the new subcommand
+        :param parser: the parser to attach
+        :param add_parser_kwargs: additional arguments for the subparser registration (e.g. help, aliases)
+        :raises ValueError: if the command path is invalid or doesn't support subcommands
+        """
+        target_parser = self._find_parser(subcommand_path)
+        subparsers_action = target_parser._find_subparsers_action()
+        subparsers_action.attach_parser(subcommand, parser, **add_parser_kwargs)  # type: ignore[attr-defined]
+
+    def detach_subcommand(self, subcommand_path: Iterable[str], subcommand: str) -> 'Cmd2ArgumentParser':
+        """Detach a subcommand from a command at the specified path.
+
+        :param subcommand_path: sequence of subcommand names leading to the parser hosting the
+                                subcommand to be detached. An empty sequence indicates this parser.
+        :param subcommand: name of the subcommand to detach
+        :return: the detached parser
+        :raises ValueError: if the command path is invalid or the subcommand doesn't exist
+        """
+        target_parser = self._find_parser(subcommand_path)
+        subparsers_action = target_parser._find_subparsers_action()
+        detached = subparsers_action.detach_parser(subcommand)  # type: ignore[attr-defined]
+        if detached is None:
+            raise ValueError(f"Subcommand '{subcommand}' not found in '{target_parser.prog}'")
+        return cast(Cmd2ArgumentParser, detached)
+
     def error(self, message: str) -> NoReturn:
         """Override that applies custom formatting to the error message."""
         lines = message.split('\n')

cmd2/cmd2.py

@@ -49,7 +49,6 @@
     Callable,
     Iterable,
     Mapping,
-    MutableSequence,
     Sequence,
 )
 from dataclasses import (
@@ -1085,40 +1084,8 @@ def _register_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:
             if not subcommand_valid:
                 raise CommandSetRegistrationError(f'Subcommand {subcommand_name} is not valid: {errmsg}')
 
-            command_tokens = full_command_name.split()
-            command_name = command_tokens[0]
-            subcommand_names = command_tokens[1:]
-
-            # Search for the base command function and verify it has an argparser defined
-            if command_name in self.disabled_commands:
-                command_func = self.disabled_commands[command_name].command_function
-            else:
-                command_func = self.cmd_func(command_name)
-
-            if command_func is None:
-                raise CommandSetRegistrationError(f"Could not find command '{command_name}' needed by subcommand: {method}")
-            command_parser = self._command_parsers.get(command_func)
-            if command_parser is None:
-                raise CommandSetRegistrationError(
-                    f"Could not find argparser for command '{command_name}' needed by subcommand: {method}"
-                )
-
-            def find_subcommand(action: Cmd2ArgumentParser, subcmd_names: MutableSequence[str]) -> Cmd2ArgumentParser:
-                if not subcmd_names:
-                    return action
-                cur_subcmd = subcmd_names.pop(0)
-                for sub_action in action._actions:
-                    if isinstance(sub_action, argparse._SubParsersAction):
-                        for choice_name, choice in sub_action.choices.items():
-                            if choice_name == cur_subcmd:
-                                return find_subcommand(choice, subcmd_names)
-                        break
-                raise CommandSetRegistrationError(f"Could not find subcommand '{action}'")
-
-            target_parser = find_subcommand(command_parser, subcommand_names)
-
             # Create the subcommand parser and configure it
-            subcmd_parser = self._build_parser(cmdset, subcmd_parser_builder, f'{command_name} {subcommand_name}')
+            subcmd_parser = self._build_parser(cmdset, subcmd_parser_builder, f'{full_command_name} {subcommand_name}')
             if subcmd_parser.description is None and method.__doc__:
                 subcmd_parser.description = strip_doc_annotations(method.__doc__)
 
@@ -1129,19 +1096,14 @@ def find_subcommand(action: Cmd2ArgumentParser, subcmd_names: MutableSequence[st
             # Set what instance the handler is bound to
             setattr(subcmd_parser, constants.PARSER_ATTR_COMMANDSET_ID, id(cmdset))
 
-            # Find the argparse action that handles subcommands
-            for action in target_parser._actions:
-                if isinstance(action, argparse._SubParsersAction):
-                    # Get add_parser() kwargs (aliases, help, etc.) defined by the decorator
-                    add_parser_kwargs = getattr(method, constants.SUBCMD_ATTR_ADD_PARSER_KWARGS, {})
-
-                    # Attach existing parser as a subcommand
-                    action.attach_parser(  # type: ignore[attr-defined]
-                        subcommand_name,
-                        subcmd_parser,
-                        **add_parser_kwargs,
-                    )
-                    break
+            # Get add_parser() kwargs (aliases, help, etc.) defined by the decorator
+            add_parser_kwargs = getattr(method, constants.SUBCMD_ATTR_ADD_PARSER_KWARGS, {})
+
+            # Attach existing parser as a subcommand
+            try:
+                self.attach_subcommand(full_command_name, subcommand_name, subcmd_parser, **add_parser_kwargs)
+            except ValueError as ex:
+                raise CommandSetRegistrationError(str(ex)) from ex
 
     def _unregister_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:
         """Unregister subcommands from their base command.
@@ -1165,30 +1127,77 @@ def _unregister_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:
         # iterate through all matching methods
         for _method_name, method in methods:
             subcommand_name = getattr(method, constants.SUBCMD_ATTR_NAME)
-            command_name = getattr(method, constants.SUBCMD_ATTR_COMMAND)
+            full_command_name = getattr(method, constants.SUBCMD_ATTR_COMMAND)
 
-            # Search for the base command function and verify it has an argparser defined
-            if command_name in self.disabled_commands:
-                command_func = self.disabled_commands[command_name].command_function
-            else:
-                command_func = self.cmd_func(command_name)
-
-            if command_func is None:  # pragma: no cover
-                # This really shouldn't be possible since _register_subcommands would prevent this from happening
-                # but keeping in case it does for some strange reason
-                raise CommandSetRegistrationError(f"Could not find command '{command_name}' needed by subcommand: {method}")
-            command_parser = self._command_parsers.get(command_func)
-            if command_parser is None:  # pragma: no cover
-                # This really shouldn't be possible since _register_subcommands would prevent this from happening
-                # but keeping in case it does for some strange reason
-                raise CommandSetRegistrationError(
-                    f"Could not find argparser for command '{command_name}' needed by subcommand: {method}"
-                )
+            with contextlib.suppress(ValueError):
+                self.detach_subcommand(full_command_name, subcommand_name)
 
-            for action in command_parser._actions:
-                if isinstance(action, argparse._SubParsersAction):
-                    action.detach_parser(subcommand_name)  # type: ignore[attr-defined]
-                    break
+    def _get_root_parser_and_subcmd_path(self, command: str) -> tuple[Cmd2ArgumentParser, list[str]]:
+        """Tokenize a command string and resolve the associated root parser and relative subcommand path.
+
+        This helper handles the initial resolution of a command string (e.g., 'foo bar baz') by
+        identifying 'foo' as the root command (even if disabled), retrieving its associated
+        parser, and returning any remaining tokens (['bar', 'baz']) as a path relative
+        to that parser for further traversal.
+
+        :param command: full space-delimited command path leading to a parser (e.g. 'foo' or 'foo bar')
+        :return: a tuple containing the Cmd2ArgumentParser for the root command and a list of
+                 strings representing the relative path to the desired hosting parser.
+        :raises ValueError: if the command is empty, the root command is not found, or
+                            the root command does not use an argparse parser.
+        """
+        tokens = command.split()
+        if not tokens:
+            raise ValueError("Command path cannot be empty")
+
+        root_command = tokens[0]
+        subcommand_path = tokens[1:]
+
+        # Search for the base command function and verify it has an argparser defined
+        if root_command in self.disabled_commands:
+            command_func = self.disabled_commands[root_command].command_function
+        else:
+            command_func = self.cmd_func(root_command)
+
+        if command_func is None:
+            raise ValueError(f"Root command '{root_command}' not found")
+
+        root_parser = self._command_parsers.get(command_func)
+        if root_parser is None:
+            raise ValueError(f"Command '{root_command}' does not use argparse")
+
+        return root_parser, subcommand_path
+
+    def attach_subcommand(
+        self,
+        command: str,
+        subcommand: str,
+        parser: Cmd2ArgumentParser,
+        **add_parser_kwargs: Any,
+    ) -> None:
+        """Attach a parser as a subcommand to a command at the specified path.
+
+        :param command: full command path (space-delimited) leading to the parser that will
+                        host the new subcommand (e.g. 'foo bar')
+        :param subcommand: name of the new subcommand
+        :param parser: the parser to attach
+        :param add_parser_kwargs: additional arguments for the subparser registration (e.g. help, aliases)
+        :raises ValueError: if the command path is invalid or doesn't support subcommands
+        """
+        root_parser, subcommand_path = self._get_root_parser_and_subcmd_path(command)
+        root_parser.attach_subcommand(subcommand_path, subcommand, parser, **add_parser_kwargs)
+
+    def detach_subcommand(self, command: str, subcommand: str) -> Cmd2ArgumentParser:
+        """Detach a subcommand from a command at the specified path.
+
+        :param command: full command path (space-delimited) leading to the parser hosting the
+                        subcommand to be detached (e.g. 'foo bar')
+        :param subcommand: name of the subcommand to detach
+        :return: the detached parser
+        :raises ValueError: if the command path is invalid or the subcommand doesn't exist
+        """
+        root_parser, subcommand_path = self._get_root_parser_and_subcmd_path(command)
+        return root_parser.detach_subcommand(subcommand_path, subcommand)
 
     @property
     def always_prefix_settables(self) -> bool:

tests/test_completion.py

@@ -942,7 +942,7 @@ def test_clean_display() -> None:
     assert completion_item.display == expected
     assert completion_item.display_meta == expected
 
-    # Verify that text derived display is also sanitized
+    # Verify that text-derived display is also sanitized
     text = "item\nwith\nnewlines"
     expected_text_display = "item with newlines"
     completion_item = CompletionItem(text)