All built-in commands now use a function to create their argument parser.

This simplifies the process for overriding cmd2's default parser class.

Author: kmvanbrunt

CHANGELOG.md

@@ -1,6 +1,10 @@
 ## 3.0.0 (TBD)
-* Breaking Change
+* Breaking Changes
   * Removed macros
+* Enhancements
+  * Simplified the process to set a custom parser for `cmd2's` built-in commands.
+    See [custom_parser.py](https://github.com/python-cmd2/cmd2/blob/master/examples/custom_parser.py)
+    example for more details.
 
 ## 2.5.0 (October 23, 2024)
 * Breaking Change

cmd2/__init__.py

@@ -3,8 +3,6 @@
 # flake8: noqa F401
 """This simply imports certain things for backwards compatibility."""
 
-import sys
-
 import importlib.metadata as importlib_metadata
 
 try:
@@ -15,53 +13,56 @@
 
 from typing import List
 
+from . import plugin
 from .ansi import (
-    Cursor,
     Bg,
-    Fg,
+    Cursor,
     EightBitBg,
     EightBitFg,
+    Fg,
     RgbBg,
     RgbFg,
     TextStyle,
     style,
 )
+from .argparse_completer import set_default_ap_completer_type
 from .argparse_custom import (
     Cmd2ArgumentParser,
     Cmd2AttributeWrapper,
     CompletionItem,
     register_argparse_argument_parameter,
     set_default_argument_parser_type,
 )
-
-# Check if user has defined a module that sets a custom value for argparse_custom.DEFAULT_ARGUMENT_PARSER.
-# Do this before loading cmd2.Cmd class so its commands use the custom parser.
-import argparse
-
-cmd2_parser_module = getattr(argparse, 'cmd2_parser_module', None)
-if cmd2_parser_module is not None:
-    import importlib
-
-    importlib.import_module(cmd2_parser_module)
-
-from .argparse_completer import set_default_ap_completer_type
-
 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_category, as_subcommand_to
+from .command_definition import (
+    CommandSet,
+    with_default_category,
+)
+from .constants import (
+    COMMAND_NAME,
+    DEFAULT_SHORTCUTS,
+)
+from .decorators import (
+    as_subcommand_to,
+    with_argparser,
+    with_argument_list,
+    with_category,
+)
 from .exceptions import (
     Cmd2ArgparseError,
     CommandSetRegistrationError,
     CompletionError,
     PassThroughException,
     SkipPostcommandHooks,
 )
-from . import plugin
 from .parsing import Statement
 from .py_bridge import CommandResult
-from .utils import categorize, CompletionMode, CustomCompletionSettings, Settable
-
+from .utils import (
+    CompletionMode,
+    CustomCompletionSettings,
+    Settable,
+    categorize,
+)
 
 __all__: List[str] = [
     'COMMAND_NAME',
@@ -81,8 +82,8 @@
     'Cmd2AttributeWrapper',
     'CompletionItem',
     'register_argparse_argument_parameter',
-    'set_default_argument_parser_type',
     'set_default_ap_completer_type',
+    'set_default_argument_parser_type',
     # Cmd2
     'Cmd',
     'CommandResult',
@@ -98,6 +99,7 @@
     'Cmd2ArgparseError',
     'CommandSetRegistrationError',
     'CompletionError',
+    'PassThroughException',
     'SkipPostcommandHooks',
     # modules
     'plugin',

cmd2/argparse_custom.py

@@ -1402,14 +1402,21 @@ def set(self, new_val: Any) -> None:
         self.__attribute = new_val
 
 
-# The default ArgumentParser class for a cmd2 app
-DEFAULT_ARGUMENT_PARSER: Type[argparse.ArgumentParser] = Cmd2ArgumentParser
+# Parser type used by cmd2's built-in commands.
+# Set it using cmd2.set_default_argument_parser_type().
+DEFAULT_ARGUMENT_PARSER: Type[Cmd2ArgumentParser] = Cmd2ArgumentParser
 
 
-def set_default_argument_parser_type(parser_type: Type[argparse.ArgumentParser]) -> None:
+def set_default_argument_parser_type(parser_type: Type[Cmd2ArgumentParser]) -> None:
     """
-    Set the default ArgumentParser class for a cmd2 app. This must be called prior to loading cmd2.py if
-    you want to override the parser for cmd2's built-in commands. See examples/override_parser.py.
+    Set the default ArgumentParser class for cmd2's built-in commands.
+
+    Since built-in commands rely on customizations made in Cmd2ArgumentParser,
+    your custom parser class should inherit from Cmd2ArgumentParser.
+
+    This should be called prior to instantiating your CLI object.
+
+    See examples/custom_parser.py.
     """
     global DEFAULT_ARGUMENT_PARSER
     DEFAULT_ARGUMENT_PARSER = parser_type