Require devs to use Cmd2ArgumentParser-based parsers.

Author: kmvanbrunt

CHANGELOG.md

@@ -64,6 +64,8 @@ prompt is displayed.
       before calling it like the previous functions did.
     - Removed `Cmd.default_to_shell`.
     - Removed `Cmd.ruler` since `cmd2` no longer uses it.
+    - All parsers used with `cmd2` commands much be an instance of `Cmd2ArgumentParser` or a child
+      class of it.
 - Enhancements
     - New `cmd2.Cmd` parameters
         - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These

cmd2/argparse_completer.py

@@ -34,6 +34,7 @@
 
 from .argparse_custom import (
     ChoicesCallable,
+    Cmd2ArgumentParser,
     generate_range_error,
 )
 from .command_definition import CommandSet
@@ -49,7 +50,7 @@
 ARG_TOKENS = 'arg_tokens'
 
 
-def _build_hint(parser: argparse.ArgumentParser, arg_action: argparse.Action) -> str:
+def _build_hint(parser: Cmd2ArgumentParser, arg_action: argparse.Action) -> str:
     """Build completion hint for a given argument."""
     # Check if hinting is disabled for this argument
     suppress_hint = arg_action.get_suppress_tab_hint()  # type: ignore[attr-defined]
@@ -64,12 +65,12 @@ def _build_hint(parser: argparse.ArgumentParser, arg_action: argparse.Action) ->
     return formatter.format_help()
 
 
-def _single_prefix_char(token: str, parser: argparse.ArgumentParser) -> bool:
+def _single_prefix_char(token: str, parser: Cmd2ArgumentParser) -> bool:
     """Is a token just a single flag prefix character."""
     return len(token) == 1 and token[0] in parser.prefix_chars
 
 
-def _looks_like_flag(token: str, parser: argparse.ArgumentParser) -> bool:
+def _looks_like_flag(token: str, parser: Cmd2ArgumentParser) -> bool:
     """Determine if a token looks like a flag.
 
     Unless an argument has nargs set to argparse.REMAINDER, then anything that looks like a flag
@@ -140,12 +141,12 @@ def __init__(self, flag_arg_state: _ArgumentState) -> None:
 
 
 class _NoResultsError(CompletionError):
-    def __init__(self, parser: argparse.ArgumentParser, arg_action: argparse.Action) -> None:
+    def __init__(self, parser: Cmd2ArgumentParser, arg_action: argparse.Action) -> None:
         """CompletionError which occurs when there are no results.
 
         If hinting is allowed on this argument, then its hint text will display.
 
-        :param parser: ArgumentParser instance which owns the action being completed
+        :param parser: Cmd2ArgumentParser instance which owns the action being completed
         :param arg_action: action being completed.
         """
         # Set apply_style to False because we don't want hints to look like errors
@@ -157,14 +158,14 @@ class ArgparseCompleter:
 
     def __init__(
         self,
-        parser: argparse.ArgumentParser,
+        parser: Cmd2ArgumentParser,
         cmd2_app: 'Cmd',
         *,
         parent_tokens: Mapping[str, MutableSequence[str]] | None = None,
     ) -> None:
         """Create an ArgparseCompleter.
 
-        :param parser: ArgumentParser instance
+        :param parser: Cmd2ArgumentParser instance
         :param cmd2_app: reference to the Cmd2 application that owns this ArgparseCompleter
         :param parent_tokens: optional Mapping of parent parsers' arg names to their tokens
                               This is only used by ArgparseCompleter when recursing on subcommand parsers
@@ -187,7 +188,7 @@ def __init__(
         self._positional_actions: list[argparse.Action] = []
 
         # This will be set if self._parser has subcommands
-        self._subcommand_action: argparse._SubParsersAction[argparse.ArgumentParser] | None = None
+        self._subcommand_action: argparse._SubParsersAction[Cmd2ArgumentParser] | None = None
 
         # Start digging through the argparse structures.
         # _actions is the top level container of parameter definitions

cmd2/argparse_custom.py

@@ -2,16 +2,9 @@
 
 It also defines a parser class called Cmd2ArgumentParser which improves error
 and help output over normal argparse. All cmd2 code uses this parser and it is
-recommended that developers of cmd2-based apps either use it or write their own
-parser that inherits from it. This will give a consistent look-and-feel between
-the help/error output of built-in cmd2 commands and the app-specific commands.
-If you wish to override the parser used by cmd2's built-in commands, see
-custom_parser.py example.
-
-Since the new capabilities are added by patching at the argparse API level,
-they are available whether or not Cmd2ArgumentParser is used. However, the help
-and error output of Cmd2ArgumentParser is customized to notate nargs ranges
-whereas any other parser class won't be as explicit in their output.
+required that developers of cmd2-based apps either use it or write their own
+parser that inherits from it. If you wish to override the parser used by cmd2's
+built-in commands, see custom_parser.py example.
 
 
 **Added capabilities**

cmd2/cmd2.py

@@ -206,8 +206,8 @@ def __init__(self, msg: str = '') -> None:
 )
 
 if TYPE_CHECKING:  # pragma: no cover
-    StaticArgParseBuilder = staticmethod[[], argparse.ArgumentParser]
-    ClassArgParseBuilder = classmethod['Cmd' | CommandSet, [], argparse.ArgumentParser]
+    StaticArgParseBuilder = staticmethod[[], Cmd2ArgumentParser]
+    ClassArgParseBuilder = classmethod['Cmd' | CommandSet, [], Cmd2ArgumentParser]
     from prompt_toolkit.buffer import Buffer
 else:
     StaticArgParseBuilder = staticmethod
@@ -237,7 +237,7 @@ def __init__(self, cmd: 'Cmd') -> None:
 
         # Keyed by the fully qualified method names. This is more reliable than
         # the methods themselves, since wrapping a method will change its address.
-        self._parsers: dict[str, argparse.ArgumentParser] = {}
+        self._parsers: dict[str, Cmd2ArgumentParser] = {}
 
     @staticmethod
     def _fully_qualified_name(command_method: CommandFunc) -> str:
@@ -256,7 +256,7 @@ def __contains__(self, command_method: CommandFunc) -> bool:
         parser = self.get(command_method)
         return bool(parser)
 
-    def get(self, command_method: CommandFunc) -> argparse.ArgumentParser | None:
+    def get(self, command_method: CommandFunc) -> Cmd2ArgumentParser | None:
         """Return a given method's parser or None if the method is not argparse-based.
 
         If the parser does not yet exist, it will be created.
@@ -889,12 +889,9 @@ def register_command_set(self, cmdset: CommandSet) -> None:
     def _build_parser(
         self,
         parent: CmdOrSet,
-        parser_builder: argparse.ArgumentParser
-        | Callable[[], argparse.ArgumentParser]
-        | StaticArgParseBuilder
-        | ClassArgParseBuilder,
+        parser_builder: Cmd2ArgumentParser | Callable[[], Cmd2ArgumentParser] | StaticArgParseBuilder | ClassArgParseBuilder,
         prog: str,
-    ) -> argparse.ArgumentParser:
+    ) -> Cmd2ArgumentParser:
         """Build argument parser for a command/subcommand.
 
         :param parent: object which owns the command using the parser.
@@ -911,7 +908,7 @@ def _build_parser(
             parser = parser_builder.__func__(parent.__class__)
         elif callable(parser_builder):
             parser = parser_builder()
-        elif isinstance(parser_builder, argparse.ArgumentParser):
+        elif isinstance(parser_builder, Cmd2ArgumentParser):
             parser = copy.deepcopy(parser_builder)
         else:
             raise TypeError(f"Invalid type for parser_builder: {type(parser_builder)}")
@@ -1021,7 +1018,7 @@ def unregister_command_set(self, cmdset: CommandSet) -> None:
             self._installed_command_sets.remove(cmdset)
 
     def _check_uninstallable(self, cmdset: CommandSet) -> None:
-        def check_parser_uninstallable(parser: argparse.ArgumentParser) -> None:
+        def check_parser_uninstallable(parser: Cmd2ArgumentParser) -> None:
             cmdset_id = id(cmdset)
             for action in parser._actions:
                 if isinstance(action, argparse._SubParsersAction):
@@ -1098,9 +1095,7 @@ def _register_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:
                     f"Could not find argparser for command '{command_name}' needed by subcommand: {method}"
                 )
 
-            def find_subcommand(
-                action: argparse.ArgumentParser, subcmd_names: MutableSequence[str]
-            ) -> argparse.ArgumentParser:
+            def find_subcommand(action: Cmd2ArgumentParser, subcmd_names: MutableSequence[str]) -> Cmd2ArgumentParser:
                 if not subcmd_names:
                     return action
                 cur_subcmd = subcmd_names.pop(0)
@@ -2349,7 +2344,7 @@ def _redirect_complete(self, text: str, line: str, begidx: int, endidx: int, com
         return compfunc(text, line, begidx, endidx)
 
     @staticmethod
-    def _determine_ap_completer_type(parser: argparse.ArgumentParser) -> type[argparse_completer.ArgparseCompleter]:
+    def _determine_ap_completer_type(parser: Cmd2ArgumentParser) -> type[argparse_completer.ArgparseCompleter]:
         """Determine what type of ArgparseCompleter to use on a given parser.
 
         If the parser does not have one set, then use argparse_completer.DEFAULT_AP_COMPLETER.
@@ -3455,7 +3450,7 @@ def _resolve_completer(
         choices: Iterable[Any] | None = None,
         choices_provider: ChoicesProviderUnbound[CmdOrSet] | None = None,
         completer: CompleterUnbound[CmdOrSet] | None = None,
-        parser: argparse.ArgumentParser | None = None,
+        parser: Cmd2ArgumentParser | None = None,
     ) -> Completer:
         """Determine the appropriate completer based on provided arguments."""
         if not any((parser, choices, choices_provider, completer)):
@@ -3487,7 +3482,7 @@ def read_input(
         choices: Iterable[Any] | None = None,
         choices_provider: ChoicesProviderUnbound[CmdOrSet] | None = None,
         completer: CompleterUnbound[CmdOrSet] | None = None,
-        parser: argparse.ArgumentParser | None = None,
+        parser: Cmd2ArgumentParser | None = None,
     ) -> str:
         """Read a line of input with optional completion and history.
 

cmd2/decorators.py

@@ -13,7 +13,10 @@
 )
 
 from . import constants
-from .argparse_custom import Cmd2AttributeWrapper
+from .argparse_custom import (
+    Cmd2ArgumentParser,
+    Cmd2AttributeWrapper,
+)
 from .command_definition import (
     CommandFunc,
     CommandSet,
@@ -184,19 +187,19 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
     return arg_decorator
 
 
-#: Function signatures for command functions that use an argparse.ArgumentParser to process user input
+#: Function signatures for command functions that use a Cmd2ArgumentParser to process user input
 #: and optionally return a boolean
 ArgparseCommandFuncOptionalBoolReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace], bool | None]
 ArgparseCommandFuncWithUnknownArgsOptionalBoolReturn: TypeAlias = Callable[
     [CmdOrSet, argparse.Namespace, list[str]], bool | None
 ]
 
-#: Function signatures for command functions that use an argparse.ArgumentParser to process user input
+#: Function signatures for command functions that use a Cmd2ArgumentParser to process user input
 #: and return a boolean
 ArgparseCommandFuncBoolReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace], bool]
 ArgparseCommandFuncWithUnknownArgsBoolReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace, list[str]], bool]
 
-#: Function signatures for command functions that use an argparse.ArgumentParser to process user input
+#: Function signatures for command functions that use a Cmd2ArgumentParser to process user input
 #: and return nothing
 ArgparseCommandFuncNoneReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace], None]
 ArgparseCommandFuncWithUnknownArgsNoneReturn: TypeAlias = Callable[[CmdOrSet, argparse.Namespace, list[str]], None]
@@ -213,17 +216,17 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
 
 
 def with_argparser(
-    parser: argparse.ArgumentParser  # existing parser
-    | Callable[[], argparse.ArgumentParser]  # function or staticmethod
-    | Callable[[CmdOrSetClass], argparse.ArgumentParser],  # Cmd or CommandSet classmethod
+    parser: Cmd2ArgumentParser  # existing parser
+    | Callable[[], Cmd2ArgumentParser]  # function or staticmethod
+    | Callable[[CmdOrSetClass], Cmd2ArgumentParser],  # Cmd or CommandSet classmethod
     *,
     ns_provider: Callable[..., argparse.Namespace] | None = None,
     preserve_quotes: bool = False,
     with_unknown_args: bool = False,
 ) -> Callable[[ArgparseCommandFunc[CmdOrSet]], RawCommandFuncOptionalBoolReturn[CmdOrSet]]:
-    """Decorate a ``do_*`` method to populate its ``args`` argument with the given instance of argparse.ArgumentParser.
+    """Decorate a ``do_*`` method to populate its ``args`` argument with the given instance of Cmd2ArgumentParser.
 
-    :param parser: instance of ArgumentParser or a callable that returns an ArgumentParser for this command
+    :param parser: instance of Cmd2ArgumentParser or a callable that returns an Cmd2ArgumentParser for this command
     :param ns_provider: An optional function that accepts a cmd2.Cmd or cmd2.CommandSet object as an argument and returns an
                         argparse.Namespace. This is useful if the Namespace needs to be prepopulated with state data that
                         affects parsing.
@@ -347,9 +350,9 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
 def as_subcommand_to(
     command: str,
     subcommand: str,
-    parser: argparse.ArgumentParser  # existing parser
-    | Callable[[], argparse.ArgumentParser]  # function or staticmethod
-    | Callable[[CmdOrSetClass], argparse.ArgumentParser],  # Cmd or CommandSet classmethod
+    parser: Cmd2ArgumentParser  # existing parser
+    | Callable[[], Cmd2ArgumentParser]  # function or staticmethod
+    | Callable[[CmdOrSetClass], Cmd2ArgumentParser],  # Cmd or CommandSet classmethod
     *,
     help: str | None = None,  # noqa: A002
     aliases: Sequence[str] | None = None,
@@ -359,7 +362,7 @@ def as_subcommand_to(
 
     :param command: Command Name. Space-delimited subcommands may optionally be specified
     :param subcommand: Subcommand name
-    :param parser: instance of ArgumentParser or a callable that returns an ArgumentParser for this subcommand
+    :param parser: instance of Cmd2ArgumentParser or a callable that returns an Cmd2ArgumentParser for this subcommand
     :param help: Help message for this subcommand which displays in the list of subcommands of the command we are adding to.
                  This is passed as the help argument to subparsers.add_parser().
     :param aliases: Alternative names for this subcommand. This is passed as the alias argument to

cmd2/utils.py

@@ -1,6 +1,5 @@
 """Shared utility functions."""
 
-import argparse
 import contextlib
 import functools
 import glob
@@ -36,6 +35,7 @@
 
 if TYPE_CHECKING:  # pragma: no cover
     PopenTextIO = subprocess.Popen[str]
+    from .argparse_custom import Cmd2ArgumentParser
 else:
     PopenTextIO = subprocess.Popen
 
@@ -734,7 +734,7 @@ def get_defining_class(meth: Callable[..., Any]) -> type[Any] | None:
 class CustomCompletionSettings:
     """Used by cmd2.Cmd.complete() to complete strings other than command arguments."""
 
-    def __init__(self, parser: argparse.ArgumentParser, *, preserve_quotes: bool = False) -> None:
+    def __init__(self, parser: 'Cmd2ArgumentParser', *, preserve_quotes: bool = False) -> None:
         """CustomCompletionSettings initializer.
 
         :param parser: arg parser defining format of string being completed

docs/features/argument_processing.md

@@ -6,7 +6,7 @@ following for you:
 
 1. Parsing input and quoted strings in a manner similar to how POSIX shells do it
 1. Parse the resulting argument list using an instance of
-   [argparse.ArgumentParser](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser)
+   [Cmd2ArgumentParser](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser)
    that you provide
 1. Passes the resulting
    [argparse.Namespace](https://docs.python.org/3/library/argparse.html#argparse.Namespace) object
@@ -39,9 +39,9 @@ command which might have its own argument parsing.
 The [@with_argparser][cmd2.with_argparser] decorator can accept the following for its first
 argument:
 
-1. An existing instance of `argparse.ArgumentParser`
-2. A function or static method which returns an instance of `argparse.ArgumentParser`
-3. Cmd or CommandSet class method which returns an instance of `argparse.ArgumentParser`
+1. An existing instance of `Cmd2ArgumentParser`
+2. A function or static method which returns an instance of `Cmd2ArgumentParser`
+3. Cmd or CommandSet class method which returns an instance of `Cmd2ArgumentParser`
 
 In all cases the `@with_argparser` decorator creates a deep copy of the parser instance which it
 stores internally. A consequence is that parsers don't need to be unique across commands.
@@ -55,11 +55,11 @@ stores internally. A consequence is that parsers don't need to be unique across
 ## Argument Parsing
 
 For each command in the `cmd2.Cmd` subclass which requires argument parsing, create an instance of
-`argparse.ArgumentParser()` which can parse the input appropriately for the command (or provide a
+`Cmd2ArgumentParser` which can parse the input appropriately for the command (or provide a
 function/method that returns such a parser). Then decorate the command method with the
 `@with_argparser` decorator, passing the argument parser as the first parameter to the decorator.
 This changes the second argument of the command method, which will contain the results of
-`ArgumentParser.parse_args()`.
+`Cmd2ArgumentParser.parse_args()`.
 
 Here's what it looks like:
 
@@ -97,7 +97,7 @@ def do_speak(self, opts):
 
 By default, `cmd2` uses the docstring of the command method when a user asks for help on the
 command. When you use the `@with_argparser` decorator, the docstring for the `do_*` method is used
-to set the description for the `argparse.ArgumentParser`.
+to set the description for the `Cmd2ArgumentParser`.
 
 !!! tip "description and epilog fields are rich objects"
 
@@ -135,8 +135,8 @@ optional arguments:
   -h, --help  show this help message and exit
 ```
 
-If you would prefer, you can set the `description` while instantiating the `argparse.ArgumentParser`
-and leave the docstring on your method blank:
+If you would prefer, you can set the `description` while instantiating the `Cmd2ArgumentParser` and
+leave the docstring on your method blank:
 
 ```py
 from cmd2 import Cmd2ArgumentParser, with_argparser

docs/features/completion.md

@@ -77,7 +77,7 @@ When using `cmd2`'s [@with_argparser][cmd2.with_argparser] decorator, `cmd2` pro
 completion of flag names.
 
 Tab completion of argument values can be configured by using one of three parameters to
-[argparse.ArgumentParser.add_argument](https://docs.python.org/3/library/argparse.html#argparse.ArgumentParser.add_argument)
+`Cmd2ArgumentParser.add_argument()`.
 
 - `choices`
 - `choices_provider`

docs/migrating/next_steps.md

@@ -9,13 +9,13 @@ leveraging other `cmd2` features. The three ideas here will get you started. Bro
 For all but the simplest of commands, it's probably easier to use
 [argparse](https://docs.python.org/3/library/argparse.html) to parse user input than to do it
 manually yourself for each command. `cmd2` provides a `@with_argparser()` decorator which associates
-an `ArgumentParser` object with one of your commands. Using this method will:
+an `Cmd2ArgumentParser` object with one of your commands. Using this method will:
 
 1.  Pass your command a
     [Namespace](https://docs.python.org/3/library/argparse.html#argparse.Namespace) containing the
     arguments instead of a string of text
 2.  Properly handle quoted string input from your users
-3.  Create a help message for you based on the `ArgumentParser`
+3.  Create a help message for you based on the `Cmd2ArgumentParser`
 4.  Give you a big head start adding [Tab Completion](../features/completion.md) to your application
 5.  Make it much easier to implement subcommands (i.e. `git` has a bunch of subcommands such as
     `git pull`, `git diff`, etc)