Renamed argparse_custom module to argparse_utils.

CHANGELOG.md

@@ -84,6 +84,7 @@ prompt is displayed.
     - `TextGroup` is now a standalone Rich renderable.
         - Removed `formatter_creator` parameter from `TextGroup.__init__()`.
         - Removed `Cmd2ArgumentParser.create_text_group()` method.
+    - Renamed `argparse_custom` module to `argparse_utils`.
 - Enhancements
     - New `cmd2.Cmd` parameters
         - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These

cmd2/__init__.py

@@ -12,7 +12,7 @@
     string_utils,
 )
 from .argparse_completer import set_default_ap_completer_type
-from .argparse_custom import (
+from .argparse_utils import (
     Cmd2ArgumentParser,
     TextGroup,
     register_argparse_argument_parameter,

cmd2/argparse_completer.py

@@ -1,6 +1,6 @@
 """Module defines the ArgparseCompleter class which provides argparse-based completion to cmd2 apps.
 
-See the header of argparse_custom.py for instructions on how to use these features.
+See the header of argparse_utils.py for instructions on how to use these features.
 """
 
 import argparse
@@ -22,7 +22,7 @@
 from rich.table import Column
 from rich.text import Text
 
-from .argparse_custom import (
+from .argparse_utils import (
     Cmd2ArgumentParser,
     build_range_error,
 )

cmd2/cmd2.py

@@ -101,14 +101,14 @@
 
 from . import (
     argparse_completer,
-    argparse_custom,
+    argparse_utils,
     constants,
     plugin,
     utils,
 )
 from . import rich_utils as ru
 from . import string_utils as su
-from .argparse_custom import (
+from .argparse_utils import (
     Cmd2ArgumentParser,
     TextGroup,
 )
@@ -588,7 +588,7 @@ def __init__(
 
         # Check for command line args
         if allow_cli_args:
-            parser = argparse_custom.DEFAULT_ARGUMENT_PARSER()
+            parser = argparse_utils.DEFAULT_ARGUMENT_PARSER()
             _callopts, callargs = parser.parse_known_args()
 
             # If commands were supplied at invocation, then add them to the command queue
@@ -2587,7 +2587,7 @@ def complete(
                         break
                 else:
                     # No shortcut was found. Complete the command token.
-                    parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(add_help=False)
+                    parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(add_help=False)
                     parser.add_argument(
                         'command',
                         metavar="COMMAND",
@@ -3498,7 +3498,7 @@ def _resolve_completer(
             raise ValueError(err_msg)
 
         if parser is None:
-            parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(add_help=False)
+            parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(add_help=False)
             parser.add_argument(
                 'arg',
                 suppress_tab_hint=True,
@@ -3727,7 +3727,7 @@ def _build_alias_parser() -> Cmd2ArgumentParser:
             "\n\n",
             "An alias is a command that enables replacement of a word by another string.",
         )
-        alias_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=alias_description)
+        alias_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=alias_description)
         alias_parser.epilog = TextGroup(
             "See Also",
             "macro",
@@ -3747,7 +3747,7 @@ def do_alias(self, args: argparse.Namespace) -> None:
     @classmethod
     def _build_alias_create_parser(cls) -> Cmd2ArgumentParser:
         alias_create_description = "Create or overwrite an alias."
-        alias_create_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=alias_create_description)
+        alias_create_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=alias_create_description)
 
         # Add Notes epilog
         alias_create_notes = Text.assemble(
@@ -3819,7 +3819,7 @@ def _alias_create(self, args: argparse.Namespace) -> None:
     def _build_alias_delete_parser(cls) -> Cmd2ArgumentParser:
         alias_delete_description = "Delete specified aliases or all aliases if --all is used."
 
-        alias_delete_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=alias_delete_description)
+        alias_delete_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=alias_delete_description)
         alias_delete_parser.add_argument('-a', '--all', action='store_true', help="delete all aliases")
         alias_delete_parser.add_argument(
             'names',
@@ -3862,7 +3862,7 @@ def _build_alias_list_parser(cls) -> Cmd2ArgumentParser:
             "Without arguments, all aliases will be listed.",
         )
 
-        alias_list_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=alias_list_description)
+        alias_list_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=alias_list_description)
         alias_list_parser.add_argument(
             'names',
             nargs=argparse.ZERO_OR_MORE,
@@ -3943,7 +3943,7 @@ def _build_macro_parser() -> Cmd2ArgumentParser:
             "\n\n",
             "A macro is similar to an alias, but it can contain argument placeholders.",
         )
-        macro_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=macro_description)
+        macro_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=macro_description)
         macro_parser.epilog = TextGroup(
             "See Also",
             "alias",
@@ -3979,7 +3979,7 @@ def _build_macro_create_parser(cls) -> Cmd2ArgumentParser:
             (" ───> ", Style(bold=True)),
             ("make_dinner --meat beef --veggie broccoli", Cmd2Style.COMMAND_LINE),
         )
-        macro_create_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=macro_create_description)
+        macro_create_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=macro_create_description)
 
         # Add Notes epilog
         macro_create_notes = Text.assemble(
@@ -4109,7 +4109,7 @@ def _macro_create(self, args: argparse.Namespace) -> None:
     def _build_macro_delete_parser(cls) -> Cmd2ArgumentParser:
         macro_delete_description = "Delete specified macros or all macros if --all is used."
 
-        macro_delete_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=macro_delete_description)
+        macro_delete_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=macro_delete_description)
         macro_delete_parser.add_argument('-a', '--all', action='store_true', help="delete all macros")
         macro_delete_parser.add_argument(
             'names',
@@ -4152,7 +4152,7 @@ def _build_macro_list_parser(cls) -> Cmd2ArgumentParser:
             "Without arguments, all macros will be listed.",
         )
 
-        macro_list_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=macro_list_description)
+        macro_list_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=macro_list_description)
         macro_list_parser.add_argument(
             'names',
             nargs=argparse.ZERO_OR_MORE,
@@ -4254,7 +4254,7 @@ def _build_command_info(self) -> tuple[dict[str, list[str]], list[str]]:
 
     @classmethod
     def _build_help_parser(cls) -> Cmd2ArgumentParser:
-        help_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(
+        help_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(
             description="List available commands or provide detailed help for a specific command."
         )
         help_parser.add_argument(
@@ -4500,7 +4500,7 @@ def columnize(self, str_list: Sequence[str] | None, display_width: int = 80) ->
 
     @staticmethod
     def _build_shortcuts_parser() -> Cmd2ArgumentParser:
-        return argparse_custom.DEFAULT_ARGUMENT_PARSER(description="List available shortcuts.")
+        return argparse_utils.DEFAULT_ARGUMENT_PARSER(description="List available shortcuts.")
 
     @with_argparser(_build_shortcuts_parser)
     def do_shortcuts(self, _: argparse.Namespace) -> None:
@@ -4513,7 +4513,7 @@ def do_shortcuts(self, _: argparse.Namespace) -> None:
 
     @staticmethod
     def _build__eof_parser() -> Cmd2ArgumentParser:
-        _eof_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description="Called when Ctrl-D is pressed.")
+        _eof_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description="Called when Ctrl-D is pressed.")
         _eof_parser.epilog = TextGroup(
             "Note",
             "This command is for internal use and is not intended to be called from the command line.",
@@ -4534,7 +4534,7 @@ def do__eof(self, _: argparse.Namespace) -> bool | None:
 
     @staticmethod
     def _build_quit_parser() -> Cmd2ArgumentParser:
-        return argparse_custom.DEFAULT_ARGUMENT_PARSER(description="Exit this application.")
+        return argparse_utils.DEFAULT_ARGUMENT_PARSER(description="Exit this application.")
 
     @with_argparser(_build_quit_parser)
     def do_quit(self, _: argparse.Namespace) -> bool | None:
@@ -4621,7 +4621,7 @@ def _build_base_set_parser(cls) -> Cmd2ArgumentParser:
                 "Call with just param to view that parameter's value."
             ),
         )
-        base_set_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=set_description)
+        base_set_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=set_description)
         base_set_parser.add_argument(
             'param',
             nargs=argparse.OPTIONAL,
@@ -4736,7 +4736,7 @@ def do_set(self, args: argparse.Namespace) -> None:
 
     @classmethod
     def _build_shell_parser(cls) -> Cmd2ArgumentParser:
-        shell_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description="Execute a command as if at the OS prompt.")
+        shell_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description="Execute a command as if at the OS prompt.")
         shell_parser.add_argument('command', help='the command to run', completer=cls.shell_cmd_complete)
         shell_parser.add_argument(
             'command_args', nargs=argparse.REMAINDER, help='arguments to pass to command', completer=cls.path_complete
@@ -4984,7 +4984,7 @@ def py_quit() -> None:
 
     @staticmethod
     def _build_py_parser() -> Cmd2ArgumentParser:
-        return argparse_custom.DEFAULT_ARGUMENT_PARSER(description="Run an interactive Python shell.")
+        return argparse_utils.DEFAULT_ARGUMENT_PARSER(description="Run an interactive Python shell.")
 
     @with_argparser(_build_py_parser)
     def do_py(self, _: argparse.Namespace) -> bool | None:
@@ -4997,7 +4997,7 @@ def do_py(self, _: argparse.Namespace) -> bool | None:
 
     @classmethod
     def _build_run_pyscript_parser(cls) -> Cmd2ArgumentParser:
-        run_pyscript_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(
+        run_pyscript_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(
             description="Run Python script within this application's environment."
         )
         run_pyscript_parser.add_argument('script_path', help='path to the script file', completer=cls.path_complete)
@@ -5043,7 +5043,7 @@ def do_run_pyscript(self, args: argparse.Namespace) -> bool | None:
 
     @staticmethod
     def _build_ipython_parser() -> Cmd2ArgumentParser:
-        return argparse_custom.DEFAULT_ARGUMENT_PARSER(description="Run an interactive IPython shell.")
+        return argparse_utils.DEFAULT_ARGUMENT_PARSER(description="Run an interactive IPython shell.")
 
     @with_argparser(_build_ipython_parser)
     def do_ipy(self, _: argparse.Namespace) -> bool | None:  # pragma: no cover
@@ -5121,8 +5121,8 @@ def do_ipy(self, _: argparse.Namespace) -> bool | None:  # pragma: no cover
     def _build_history_parser(cls) -> Cmd2ArgumentParser:
         history_description = "View, run, edit, save, or clear previously entered commands."
 
-        history_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(
-            description=history_description, formatter_class=argparse_custom.RawTextCmd2HelpFormatter
+        history_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(
+            description=history_description, formatter_class=argparse_utils.RawTextCmd2HelpFormatter
         )
         history_action_group = history_parser.add_mutually_exclusive_group()
         history_action_group.add_argument('-r', '--run', action='store_true', help='run selected history items')
@@ -5390,7 +5390,7 @@ def _persist_history(self) -> None:
     @classmethod
     def _build_edit_parser(cls) -> Cmd2ArgumentParser:
         edit_description = "Run a text editor and optionally open a file with it."
-        edit_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=edit_description)
+        edit_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=edit_description)
         edit_parser.epilog = TextGroup(
             "Note",
             Text.assemble(
@@ -5443,7 +5443,7 @@ def _build_base_run_script_parser(cls) -> Cmd2ArgumentParser:
             "Scripts should contain one command per line, entered as you would in the console.",
         )
 
-        run_script_parser = argparse_custom.DEFAULT_ARGUMENT_PARSER(description=run_script_description)
+        run_script_parser = argparse_utils.DEFAULT_ARGUMENT_PARSER(description=run_script_description)
         run_script_parser.add_argument(
             'script_path',
             help="path to the script file",

cmd2/decorators.py

@@ -15,7 +15,7 @@
 )
 
 from . import constants
-from .argparse_custom import Cmd2ArgumentParser
+from .argparse_utils import Cmd2ArgumentParser
 from .command_set import CommandSet
 from .exceptions import Cmd2ArgparseError
 from .parsing import Statement

cmd2/rich_utils.py

@@ -12,7 +12,7 @@
 )
 
 if TYPE_CHECKING:
-    from .argparse_custom import Cmd2HelpFormatter
+    from .argparse_utils import Cmd2HelpFormatter
 
 from rich.box import SIMPLE_HEAD
 from rich.console import (

cmd2/utils.py

@@ -36,7 +36,7 @@
 
 if TYPE_CHECKING:  # pragma: no cover
     PopenTextIO = subprocess.Popen[str]
-    from .argparse_custom import Cmd2ArgumentParser
+    from .argparse_utils import Cmd2ArgumentParser
 else:
     PopenTextIO = subprocess.Popen
 

docs/api/argparse_utils.md

@@ -0,0 +1,3 @@
+# cmd2.argparse_utils
+
+::: cmd2.argparse_utils

docs/api/index.md

@@ -13,7 +13,7 @@ incremented according to the [Semantic Version Specification](https://semver.org
 
 - [cmd2.Cmd](./cmd.md) - functions and attributes of the main class in this library
 - [cmd2.argparse_completer](./argparse_completer.md) - classes for `argparse`-based tab completion
-- [cmd2.argparse_custom](./argparse_custom.md) - classes and functions for extending `argparse`
+- [cmd2.argparse_utils](./argparse_utils.md) - classes and functions for extending `argparse`
 - [cmd2.clipboard](./clipboard.md) - functions to copy from and paste to the clipboard/pastebuffer
 - [cmd2.colors](./colors.md) - StrEnum of all color names supported by the Rich library
 - [cmd2.command_set](./command_set.md) - supports the definition of commands in separate classes to

docs/features/argument_processing.md

@@ -212,14 +212,14 @@ benefit is that your `cmd2` applications now have more aesthetically pleasing he
 color to make it quicker and easier to visually parse help text. This works for all supported
 versions of Python.
 
-- [Cmd2HelpFormatter][cmd2.argparse_custom.Cmd2HelpFormatter] - default help formatter class
-- [ArgumentDefaultsCmd2HelpFormatter][cmd2.argparse_custom.ArgumentDefaultsCmd2HelpFormatter] - adds
+- [Cmd2HelpFormatter][cmd2.argparse_utils.Cmd2HelpFormatter] - default help formatter class
+- [ArgumentDefaultsCmd2HelpFormatter][cmd2.argparse_utils.ArgumentDefaultsCmd2HelpFormatter] - adds
   default values to argument help
-- [MetavarTypeCmd2HelpFormatter][cmd2.argparse_custom.MetavarTypeCmd2HelpFormatter] - uses the
+- [MetavarTypeCmd2HelpFormatter][cmd2.argparse_utils.MetavarTypeCmd2HelpFormatter] - uses the
   argument 'type' as the default metavar value (instead of the argument 'dest')
-- [RawDescriptionCmd2HelpFormatter][cmd2.argparse_custom.RawDescriptionCmd2HelpFormatter] - retains
+- [RawDescriptionCmd2HelpFormatter][cmd2.argparse_utils.RawDescriptionCmd2HelpFormatter] - retains
   any formatting in descriptions and epilogs
-- [RawTextCmd2HelpFormatter][cmd2.argparse_custom.RawTextCmd2HelpFormatter] - retains formatting of
+- [RawTextCmd2HelpFormatter][cmd2.argparse_utils.RawTextCmd2HelpFormatter] - retains formatting of
   all help text
 
 The default `Cmd2HelpFormatter` class inherits from `argparse.HelpFormatter`. If you want a

docs/features/completion.md

@@ -118,5 +118,5 @@ demonstration.
 
 ## For More Information
 
-See [cmd2's argparse_custom API](../api/argparse_custom.md) for a more detailed discussion of
-argparse completion.
+See [cmd2's argparse_utils API](../api/argparse_utils.md) for a more detailed discussion of argparse
+completion.

mkdocs.yml

@@ -195,7 +195,7 @@ nav:
       - api/index.md
       - api/cmd.md
       - api/argparse_completer.md
-      - api/argparse_custom.md
+      - api/argparse_utils.md
       - api/clipboard.md
       - api/colors.md
       - api/command_set.md

tests/test_argparse_completer.py

@@ -15,7 +15,7 @@
     CompletionItem,
     Completions,
     argparse_completer,
-    argparse_custom,
+    argparse_utils,
     with_argparser,
 )
 from cmd2 import rich_utils as ru
@@ -1279,7 +1279,7 @@ def _complete_flags(self, text: str, line: str, begidx: int, endidx: int, used_f
 
 
 # Add a custom argparse action attribute
-argparse_custom.register_argparse_argument_parameter('complete_when_ready')
+argparse_utils.register_argparse_argument_parameter('complete_when_ready')
 
 
 # App used to test custom ArgparseCompleter types and custom argparse attributes