Renamed add_existing_parser() to attach_parser().

Renamed remove_parser() to detach_parser().

Author: kmvanbrunt

cmd2/argparse_custom.py

@@ -252,13 +252,13 @@ def get_choices(self) -> Choices:
 cmd2 has patched ``argparse._SubParsersAction`` with new functions to better facilitate the
 addition and removal of subcommand parsers.
 
-``argparse._SubParsersAction.remove_parser`` - new function which removes a
-sub-parser from a sub-parsers group. See ``_SubParsersAction_remove_parser`` for
-more details.
-
-``argparse._SubParsersAction.add_existing_parser`` - new function which allows you to attach
-an existing ArgumentParser to a sub-parsers group. See ``_SubParsersAction_add_existing_parser``
+``argparse._SubParsersAction.attach_parser`` - new function to attach
+an existing ArgumentParser to a subparsers action. See ``_SubParsersAction_attach_parser``
 for more details.
+
+``argparse._SubParsersAction.detach_parser`` - new function to detach a
+parser from a subparsers action. See ``_SubParsersAction_detach_parser`` for
+more details.
 """
 
 import argparse
@@ -945,62 +945,25 @@ def _ArgumentParser_check_value(_self: argparse.ArgumentParser, action: argparse
 
 
 ############################################################################################################
-# Patch argparse._SubParsersAction to add remove_parser function
-############################################################################################################
-
-
-def _SubParsersAction_remove_parser(  # noqa: N802
-    self: argparse._SubParsersAction,  # type: ignore[type-arg]
-    name: str,
-) -> None:
-    """Remove a sub-parser from a sub-parsers group. Used to remove subcommands from a parser.
-
-    This function is added by cmd2 as a method called ``remove_parser()`` to ``argparse._SubParsersAction`` class.
-
-    To call: ``action.remove_parser(name)``
-
-    :param self: instance of the _SubParsersAction being edited
-    :param name: name of the subcommand for the sub-parser to remove
-    """
-    # Remove this subcommand from its base command's help text
-    for choice_action in self._choices_actions:
-        if choice_action.dest == name:
-            self._choices_actions.remove(choice_action)
-            break
-
-    # Remove this subcommand and all its aliases from the base command
-    subparser = self._name_parser_map.get(name)
-    if subparser is not None:
-        to_remove = []
-        for cur_name, cur_parser in self._name_parser_map.items():
-            if cur_parser is subparser:
-                to_remove.append(cur_name)
-        for cur_name in to_remove:
-            del self._name_parser_map[cur_name]
-
-
-setattr(argparse._SubParsersAction, 'remove_parser', _SubParsersAction_remove_parser)
-
-############################################################################################################
-# Patch argparse._SubParsersAction to add add_existing_parser function
+# Patch argparse._SubParsersAction to add attach_parser function
 ############################################################################################################
 
 
-def _SubParsersAction_add_existing_parser(  # noqa: N802
+def _SubParsersAction_attach_parser(  # noqa: N802
     self: argparse._SubParsersAction,  # type: ignore[type-arg]
     name: str,
     subcmd_parser: argparse.ArgumentParser,
     **add_parser_kwargs: Any,
 ) -> None:
-    """Attach an existing ArgumentParser to a sub-parsers group.
+    """Attach an existing ArgumentParser to a subparsers action.
 
     This is useful when a parser is pre-configured (e.g. by cmd2's subcommand decorator)
     and needs to be attached to a parent parser.
 
-    This function is added by cmd2 as a method called ``add_existing_parser()``
+    This function is added by cmd2 as a method called ``attach_parser()``
     to ``argparse._SubParsersAction`` class.
 
-    To call: ``action.add_existing_parser(name, subcmd_parser, **add_parser_kwargs)``
+    To call: ``action.attach_parser(name, subcmd_parser, **add_parser_kwargs)``
 
     :param self: instance of the _SubParsersAction being edited
     :param name: name of the subcommand to add
@@ -1019,7 +982,48 @@ def _SubParsersAction_add_existing_parser(  # noqa: N802
         self._name_parser_map[alias] = subcmd_parser
 
 
-setattr(argparse._SubParsersAction, 'add_existing_parser', _SubParsersAction_add_existing_parser)
+setattr(argparse._SubParsersAction, 'attach_parser', _SubParsersAction_attach_parser)
+
+############################################################################################################
+# Patch argparse._SubParsersAction to add detach_parser function
+############################################################################################################
+
+
+def _SubParsersAction_detach_parser(  # noqa: N802
+    self: argparse._SubParsersAction,  # type: ignore[type-arg]
+    name: str,
+) -> argparse.ArgumentParser | None:
+    """Detach a parser from a subparsers action and return it.
+
+    This function is added by cmd2 as a method called ``detach_parser()`` to ``argparse._SubParsersAction`` class.
+
+    To call: ``action.detach_parser(name)``
+
+    :param self: instance of the _SubParsersAction being edited
+    :param name: name of the subcommand for the parser to detach
+    :return: the parser which was detached or None if the subcommand doesn't exist
+    """
+    subparser = self._name_parser_map.get(name)
+
+    if subparser is not None:
+        # Remove this subcommand and all its aliases from the base command
+        to_remove = []
+        for cur_name, cur_parser in self._name_parser_map.items():
+            if cur_parser is subparser:
+                to_remove.append(cur_name)
+        for cur_name in to_remove:
+            del self._name_parser_map[cur_name]
+
+        # Remove this subcommand from its base command's help text
+        for choice_action in self._choices_actions:
+            if choice_action.dest == name:
+                self._choices_actions.remove(choice_action)
+                break
+
+    return subparser
+
+
+setattr(argparse._SubParsersAction, 'detach_parser', _SubParsersAction_detach_parser)
 
 ############################################################################################################
 # Unless otherwise noted, everything below this point are copied from Python's

cmd2/cmd2.py

@@ -1132,8 +1132,8 @@ def find_subcommand(
                     # Get add_parser() kwargs (aliases, help, etc.) defined by the decorator
                     add_parser_kwargs = getattr(method, constants.SUBCMD_ATTR_ADD_PARSER_KWARGS, {})
 
-                    # Add the existing parser as a subcommand
-                    action.add_existing_parser(  # type: ignore[attr-defined]
+                    # Attach existing parser as a subcommand
+                    action.attach_parser(  # type: ignore[attr-defined]
                         subcommand_name,
                         subcmd_parser,
                         **add_parser_kwargs,
@@ -1184,7 +1184,7 @@ def _unregister_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:
 
             for action in command_parser._actions:
                 if isinstance(action, argparse._SubParsersAction):
-                    action.remove_parser(subcommand_name)  # type: ignore[attr-defined]
+                    action.detach_parser(subcommand_name)  # type: ignore[attr-defined]
                     break
 
     @property

tests/test_argparse_custom.py

@@ -308,6 +308,48 @@ def test_cmd2_attribute_wrapper() -> None:
     assert wrapper.get() == new_val
 
 
+def test_parser_attachment() -> None:
+    # Attach a parser as a subcommand
+    root_parser = Cmd2ArgumentParser(description="root command")
+    root_subparsers = root_parser.add_subparsers()
+
+    child_parser = Cmd2ArgumentParser(description="child command")
+    root_subparsers.attach_parser(  # type: ignore[attr-defined]
+        "child",
+        child_parser,
+        help="a child command",
+        aliases=["child_alias"],
+    )
+
+    # Verify the same parser instance was used
+    assert root_subparsers._name_parser_map["child"] is child_parser
+    assert root_subparsers._name_parser_map["child_alias"] is child_parser
+
+    # Verify an action with the help text exists
+    child_action = None
+    for action in root_subparsers._choices_actions:
+        if action.dest == "child":
+            child_action = action
+            break
+    assert child_action is not None
+    assert child_action.help == "a child command"
+
+    # Detatch the subcommand
+    detached_parser = root_subparsers.detach_parser("child")  # type: ignore[attr-defined]
+
+    # Verify subcommand and its aliases were removed
+    assert detached_parser is child_parser
+    assert "child" not in root_subparsers._name_parser_map
+    assert "child_alias" not in root_subparsers._name_parser_map
+
+    # Verify the help text action was removed
+    choices_actions = [action.dest for action in root_subparsers._choices_actions]
+    assert "child" not in choices_actions
+
+    # Verify it returns None when subcommand does not exist
+    assert root_subparsers.detach_parser("fake") is None  # type: ignore[attr-defined]
+
+
 def test_completion_items_as_choices(capsys) -> None:
     """Test cmd2's patch to Argparse._check_value() which supports CompletionItems as choices.
     Choices are compared to CompletionItems.orig_value instead of the CompletionItem instance.