diff --git a/CHANGELOG.md b/CHANGELOG.md index fed209083..b12238143 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/cmd2/__init__.py b/cmd2/__init__.py index 2b2e51539..8259b1629 100644 --- a/cmd2/__init__.py +++ b/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, diff --git a/cmd2/argparse_completer.py b/cmd2/argparse_completer.py index 9553e9359..6ecb2b255 100644 --- a/cmd2/argparse_completer.py +++ b/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, ) diff --git a/cmd2/argparse_custom.py b/cmd2/argparse_utils.py similarity index 100% rename from cmd2/argparse_custom.py rename to cmd2/argparse_utils.py diff --git a/cmd2/cmd2.py b/cmd2/cmd2.py index dcef8f3d5..58cb7b115 100644 --- a/cmd2/cmd2.py +++ b/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", diff --git a/cmd2/decorators.py b/cmd2/decorators.py index 41e1d391b..961d673a1 100644 --- a/cmd2/decorators.py +++ b/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 diff --git a/cmd2/rich_utils.py b/cmd2/rich_utils.py index 786d8ff44..897d070f8 100644 --- a/cmd2/rich_utils.py +++ b/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 ( diff --git a/cmd2/utils.py b/cmd2/utils.py index 5a984fafe..d612f0e74 100644 --- a/cmd2/utils.py +++ b/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 diff --git a/docs/api/argparse_custom.md b/docs/api/argparse_custom.md deleted file mode 100644 index 53f97a629..000000000 --- a/docs/api/argparse_custom.md +++ /dev/null @@ -1,3 +0,0 @@ -# cmd2.argparse_custom - -::: cmd2.argparse_custom diff --git a/docs/api/argparse_utils.md b/docs/api/argparse_utils.md new file mode 100644 index 000000000..192e55c8f --- /dev/null +++ b/docs/api/argparse_utils.md @@ -0,0 +1,3 @@ +# cmd2.argparse_utils + +::: cmd2.argparse_utils diff --git a/docs/api/index.md b/docs/api/index.md index e317a235f..c386df05a 100644 --- a/docs/api/index.md +++ b/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 diff --git a/docs/features/argument_processing.md b/docs/features/argument_processing.md index 18f093848..b18aabe1c 100644 --- a/docs/features/argument_processing.md +++ b/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 diff --git a/docs/features/completion.md b/docs/features/completion.md index 868099025..85143650b 100644 --- a/docs/features/completion.md +++ b/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. diff --git a/mkdocs.yml b/mkdocs.yml index 2511a6943..ec47edc38 100644 --- a/mkdocs.yml +++ b/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 diff --git a/tests/test_argparse_completer.py b/tests/test_argparse_completer.py index 0bd1a0c5a..eb33e0776 100644 --- a/tests/test_argparse_completer.py +++ b/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 diff --git a/tests/test_argparse_custom.py b/tests/test_argparse_utils.py similarity index 97% rename from tests/test_argparse_custom.py rename to tests/test_argparse_utils.py index 7d71aad65..a303558a4 100644 --- a/tests/test_argparse_custom.py +++ b/tests/test_argparse_utils.py @@ -10,10 +10,10 @@ from cmd2 import ( Choices, Cmd2ArgumentParser, - argparse_custom, + argparse_utils, constants, ) -from cmd2.argparse_custom import ( +from cmd2.argparse_utils import ( Cmd2HelpFormatter, build_range_error, register_argparse_argument_parameter, @@ -27,7 +27,7 @@ def test_text_group_direct_cmd2() -> None: """Print a TextGroup directly using a Cmd2RichArgparseConsole.""" title = "Notes" content = "Some text" - text_group = argparse_custom.TextGroup(title, content) + text_group = argparse_utils.TextGroup(title, content) console = Cmd2RichArgparseConsole() with console.capture() as capture: console.print(text_group) @@ -40,7 +40,7 @@ def test_text_group_direct_plain() -> None: """Print a TextGroup directly not using a Cmd2RichArgparseConsole.""" title = "Notes" content = "Some text" - text_group = argparse_custom.TextGroup(title, content) + text_group = argparse_utils.TextGroup(title, content) console = Console() with console.capture() as capture: console.print(text_group) @@ -52,7 +52,7 @@ def test_text_group_direct_plain() -> None: def test_text_group_in_parser_cmd2(capsys) -> None: """Print a TextGroup with argparse using a Cmd2RichArgparseConsole.""" parser = Cmd2ArgumentParser(prog="test") - parser.epilog = argparse_custom.TextGroup("Notes", "Some text") + parser.epilog = argparse_utils.TextGroup("Notes", "Some text") # Render help parser.print_help() @@ -75,7 +75,7 @@ def _get_formatter(self, **kwargs: Any) -> Cmd2HelpFormatter: return formatter parser = CustomParser(prog="test") - parser.epilog = argparse_custom.TextGroup("Notes", "Some text") + parser.epilog = argparse_utils.TextGroup("Notes", "Some text") # Render help parser.print_help() @@ -356,7 +356,7 @@ def test_register_argparse_argument_parameter() -> None: param_name = "test_unique_param" register_argparse_argument_parameter(param_name) - assert param_name in argparse_custom._CUSTOM_ACTION_ATTRIBS + assert param_name in argparse_utils._CUSTOM_ACTION_ATTRIBS assert hasattr(argparse.Action, f'get_{param_name}') assert hasattr(argparse.Action, f'set_{param_name}') @@ -586,14 +586,14 @@ def test_formatter_set_color(mocker) -> None: formatter = Cmd2HelpFormatter(prog='test') # return (inside _set_color if sys.version_info < (3, 14)) - mocker.patch('cmd2.argparse_custom.sys.version_info', (3, 13, 0)) + mocker.patch('cmd2.argparse_utils.sys.version_info', (3, 13, 0)) # This should return early without calling super()._set_color mock_set_color = mocker.patch('rich_argparse.RichHelpFormatter._set_color') formatter._set_color(True) mock_set_color.assert_not_called() # except TypeError and super()._set_color(color) - mocker.patch('cmd2.argparse_custom.sys.version_info', (3, 15, 0)) + mocker.patch('cmd2.argparse_utils.sys.version_info', (3, 15, 0)) # Reset mock and make it raise TypeError when called with kwargs mock_set_color.reset_mock()