Modular commands attempt 3 #943

CHANGELOG.md

@@ -1,3 +1,8 @@
+## 1.3.0 (August 4, 2020)
+* Enchancements
+    * Added CommandSet - Enables defining a separate loadable module of commands to register/unregister
+      with your cmd2 application. 
+
 ## 1.2.1 (July 14, 2020)
 * Bug Fixes
     * Relax minimum version of `importlib-metadata` to >= 1.6.0 when using Python < 3.8

Pipfile

@@ -12,6 +12,7 @@ wcwidth = ">=0.1.7"
 
 [dev-packages]
 cmd2 = {editable = true,path = "."}
+cmd2_ext_test = {editable = true,path = "plugins/ext_test"}
 codecov = "*"
 doc8 = "*"
 flake8 = "*"

cmd2/__init__.py

@@ -28,8 +28,9 @@
 # Get the current value for argparse_custom.DEFAULT_ARGUMENT_PARSER
 from .argparse_custom import DEFAULT_ARGUMENT_PARSER
 from .cmd2 import Cmd
+from .command_definition import CommandSet, with_default_category
 from .constants import COMMAND_NAME, DEFAULT_SHORTCUTS
-from .decorators import with_argument_list, with_argparser, with_argparser_and_unknown_args, with_category
+from .decorators import with_argument_list, with_argparser, with_argparser_and_unknown_args, with_category, as_subcommand_to
 from .exceptions import Cmd2ArgparseError, SkipPostcommandHooks
 from . import plugin
 from .parsing import Statement

cmd2/argparse_completer.py

@@ -23,6 +23,7 @@
     CompletionItem,
     generate_range_error,
 )
+from .command_definition import CommandSet
 from .table_creator import Column, SimpleTable
 from .utils import CompletionError, basic_complete
 
@@ -181,7 +182,8 @@ def __init__(self, parser: argparse.ArgumentParser, cmd2_app: cmd2.Cmd, *,
                 if isinstance(action, argparse._SubParsersAction):
                     self._subcommand_action = action
 
-    def complete_command(self, tokens: List[str], text: str, line: str, begidx: int, endidx: int) -> List[str]:
+    def complete_command(self, tokens: List[str], text: str, line: str, begidx: int, endidx: int, *,
+                         cmd_set: Optional[CommandSet] = None) -> List[str]:
         """
         Complete the command using the argparse metadata and provided argument dictionary
         :raises: CompletionError for various types of tab completion errors
@@ -358,7 +360,8 @@ def update_mutex_groups(arg_action: argparse.Action) -> None:
 
                                 completer = ArgparseCompleter(self._subcommand_action.choices[token], self._cmd2_app,
                                                               parent_tokens=parent_tokens)
-                                return completer.complete_command(tokens[token_index:], text, line, begidx, endidx)
+                                return completer.complete_command(tokens[token_index:], text, line, begidx, endidx,
+                                                                  cmd_set=cmd_set)
                             else:
                                 # Invalid subcommand entered, so no way to complete remaining tokens
                                 return []
@@ -403,7 +406,8 @@ def update_mutex_groups(arg_action: argparse.Action) -> None:
         # Check if we are completing a flag's argument
         if flag_arg_state is not None:
             completion_results = self._complete_for_arg(flag_arg_state.action, text, line,
-                                                        begidx, endidx, consumed_arg_values)
+                                                        begidx, endidx, consumed_arg_values,
+                                                        cmd_set=cmd_set)
 
             # If we have results, then return them
             if completion_results:
@@ -423,7 +427,8 @@ def update_mutex_groups(arg_action: argparse.Action) -> None:
                 pos_arg_state = _ArgumentState(action)
 
             completion_results = self._complete_for_arg(pos_arg_state.action, text, line,
-                                                        begidx, endidx, consumed_arg_values)
+                                                        begidx, endidx, consumed_arg_values,
+                                                        cmd_set=cmd_set)
 
             # If we have results, then return them
             if completion_results:
@@ -543,7 +548,8 @@ def format_help(self, tokens: List[str]) -> str:
 
     def _complete_for_arg(self, arg_action: argparse.Action,
                           text: str, line: str, begidx: int, endidx: int,
-                          consumed_arg_values: Dict[str, List[str]]) -> List[str]:
+                          consumed_arg_values: Dict[str, List[str]], *,
+                          cmd_set: Optional[CommandSet] = None) -> List[str]:
         """
         Tab completion routine for an argparse argument
         :return: list of completions
@@ -563,6 +569,12 @@ def _complete_for_arg(self, arg_action: argparse.Action,
         kwargs = {}
         if isinstance(arg_choices, ChoicesCallable):
             if arg_choices.is_method:
+                cmd_set = getattr(self._parser, constants.PARSER_ATTR_COMMANDSET, cmd_set)
+                if cmd_set is not None:
+                    if isinstance(cmd_set, CommandSet):
+                        # If command is part of a CommandSet, `self` should be the CommandSet and Cmd will be next
+                        if cmd_set is not None:
+                            args.append(cmd_set)
                 args.append(self._cmd2_app)
 
             # Check if arg_choices.to_call expects arg_tokens

cmd2/argparse_custom.py

@@ -60,18 +60,32 @@ def my_choices_function():
 
         parser.add_argument('-o', '--options', choices_function=my_choices_function)
 
-``choices_method`` - this is exactly like choices_function, but the function
-needs to be an instance method of a cmd2-based class. When ArgparseCompleter
-calls the method, it will pass the app instance as the self argument. This is
-good in cases where the list of choices being generated relies on state data of
-the cmd2-based app
-
-    Example::
+``choices_method`` - this is equivalent to choices_function, but the function
+needs to be an instance method of a cmd2.Cmd or cmd2.CommandSet subclass. When
+ArgparseCompleter calls the method, it well detect whether is is bound to a
+CommandSet or Cmd subclass.
+If bound to a cmd2.Cmd subclass, it will pass the app instance as the `self`
+argument. This is good in cases where the list of choices being generated
+relies on state data of the cmd2-based app.
+If bound to a cmd2.CommandSet subclass, it will pass the CommandSet instance
+as the `self` argument, and the app instance as the positional argument.
+
+    Example bound to cmd2.Cmd::
 
         def my_choices_method(self):
             ...
             return my_generated_list
 
+        parser.add_argument("arg", choices_method=my_choices_method)
+
+    Example bound to cmd2.CommandSEt::
+
+        def my_choices_method(self, app: cmd2.Cmd):
+            ...
+            return my_generated_list
+
+        parser.add_argument("arg", choices_method=my_choices_method)
+
 ``completer_function`` - pass a tab completion function that does custom
 completion. Since custom tab completion operations commonly need to modify
 cmd2's instance variables related to tab completion, it will be rare to need a
@@ -84,10 +98,16 @@ def my_completer_function(text, line, begidx, endidx):
             return completions
         parser.add_argument('-o', '--options', completer_function=my_completer_function)
 
-``completer_method`` - this is exactly like completer_function, but the
-function needs to be an instance method of a cmd2-based class. When
-ArgparseCompleter calls the method, it will pass the app instance as the self
-argument. cmd2 provides a few completer methods for convenience (e.g.,
+``completer_method`` - this is equivalent to completer_function, but the function
+needs to be an instance method of a cmd2.Cmd or cmd2.CommandSet subclass. When
+ArgparseCompleter calls the method, it well detect whether is is bound to a
+CommandSet or Cmd subclass.
+If bound to a cmd2.Cmd subclass, it will pass the app instance as the `self`
+argument. This is good in cases where the list of choices being generated
+relies on state data of the cmd2-based app.
+If bound to a cmd2.CommandSet subclass, it will pass the CommandSet instance
+as the `self` argument, and the app instance as the positional argument.
+cmd2 provides a few completer methods for convenience (e.g.,
 path_complete, delimiter_complete)
 
     Example::
@@ -192,11 +212,15 @@ def my_completer_method(self, text, line, begidx, endidx, arg_tokens)
 completion and enables nargs range parsing. See _add_argument_wrapper for
 more details on these arguments.
 
-``argparse.ArgumentParser._get_nargs_pattern`` - adds support to for nargs
-ranges. See _get_nargs_pattern_wrapper for more details.
+``argparse.ArgumentParser._get_nargs_pattern`` - adds support for nargs ranges.
+See _get_nargs_pattern_wrapper for more details.
 
-``argparse.ArgumentParser._match_argument`` - adds support to for nargs ranges.
+``argparse.ArgumentParser._match_argument`` - adds support for nargs ranges.
 See _match_argument_wrapper for more details.
+
+``argparse._SubParsersAction.remove_parser`` - new function which removes a
+sub-parser from a sub-parsers group. See _SubParsersAction_remove_parser for
+more details.
 """
 
 import argparse
@@ -528,6 +552,42 @@ def _match_argument_wrapper(self, action, arg_strings_pattern) -> int:
 # noinspection PyProtectedMember
 argparse.ArgumentParser._match_argument = _match_argument_wrapper
 
+
+############################################################################################################
+# Patch argparse._SubParsersAction to add remove_parser function
+############################################################################################################
+
+def _SubParsersAction_remove_parser(self, name: str):
+    """
+    Removes a sub-parser from a sub-parsers group
+
+    This is a custom method being added to the argparse._SubParsersAction
+    class so cmd2 can remove subcommands from a parser.
+
+    :param self: instance of the _SubParsersAction being edited
+    :param name: name of the sub-parser to remove
+    """
+    for choice_action in self._choices_actions:
+        if choice_action.dest == name:
+            self._choices_actions.remove(choice_action)
+            break
+
+    subparser = self._name_parser_map[name]
+    to_remove = []
+    for name, parser in self._name_parser_map.items():
+        if parser is subparser:
+            to_remove.append(name)
+    for name in to_remove:
+        del self._name_parser_map[name]
+
+    if name in self.choices:
+        del self.choices[name]
+
+
+# noinspection PyProtectedMember
+setattr(argparse._SubParsersAction, 'remove_parser', _SubParsersAction_remove_parser)
+
+
 ############################################################################################################
 # Unless otherwise noted, everything below this point are copied from Python's
 # argparse implementation with minor tweaks to adjust output.
@@ -728,14 +788,40 @@ def _format_args(self, action, default_metavar) -> str:
 class Cmd2ArgumentParser(argparse.ArgumentParser):
     """Custom ArgumentParser class that improves error and help output"""
 
-    def __init__(self, *args, **kwargs) -> None:
-        if 'formatter_class' not in kwargs:
-            kwargs['formatter_class'] = Cmd2HelpFormatter
-
-        super().__init__(*args, **kwargs)
+    def __init__(self,
+                 prog=None,
+                 usage=None,
+                 description=None,
+                 epilog=None,
+                 parents=None,
+                 formatter_class=Cmd2HelpFormatter,
+                 prefix_chars='-',
+                 fromfile_prefix_chars=None,
+                 argument_default=None,
+                 conflict_handler='error',
+                 add_help=True,
+                 allow_abbrev=True) -> None:
+        super(Cmd2ArgumentParser, self).__init__(
+            prog=prog,
+            usage=usage,
+            description=description,
+            epilog=epilog,
+            parents=parents if parents else [],
+            formatter_class=formatter_class,
+            prefix_chars=prefix_chars,
+            fromfile_prefix_chars=fromfile_prefix_chars,
+            argument_default=argument_default,
+            conflict_handler=conflict_handler,
+            add_help=add_help,
+            allow_abbrev=allow_abbrev)
 
     def add_subparsers(self, **kwargs):
-        """Custom override. Sets a default title if one was not given."""
+        """
+        Custom override. Sets a default title if one was not given.
+
+        :param kwargs: additional keyword arguments
+        :return: argparse Subparser Action
+        """
         if 'title' not in kwargs:
             kwargs['title'] = 'subcommands'