Merge branch 'main' into feat/annotated-argparse

Author: tleonhardt

.github/workflows/tests.yml

@@ -40,14 +40,14 @@ jobs:
 
       - name: Upload test results to Codecov
         if: ${{ !cancelled() }}
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           flags: python${{ matrix.python-version }}
           name: codecov-umbrella-test-results
           report_type: test_results
           token: ${{ secrets.CODECOV_TOKEN }}
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v5
+        uses: codecov/codecov-action@v6
         with:
           env_vars: OS,PYTHON
           fail_ci_if_error: true

CHANGELOG.md

@@ -79,6 +79,7 @@ prompt is displayed.
         - **pre_prompt**: hook method that is called before the prompt is displayed, but after
           `prompt-toolkit` event loop has started
         - **read_secret**: read secrets like passwords without displaying them to the terminal
+        - **ppretty**: a cmd2-compatible replacement for `rich.pretty.pprint()`
     - New settables:
         - **max_column_completion_results**: (int) the maximum number of completion results to
           display in a single column

cmd2/argparse_completer.py

@@ -359,7 +359,7 @@ def consume_argument(arg_state: _ArgumentState, arg_token: str) -> None:
                     action = remaining_positionals.popleft()
 
                     # Are we at a subcommand? If so, forward to the matching completer
-                    if action == self._subcommand_action:
+                    if self._subcommand_action is not None and action == self._subcommand_action:
                         if token in self._subcommand_action.choices:
                             # Merge self._parent_tokens and consumed_arg_values
                             parent_tokens = {**self._parent_tokens, **consumed_arg_values}

cmd2/argparse_custom.py

@@ -222,42 +222,43 @@ def get_choices(self) -> Choices:
 more details on these arguments.
 
 ``argparse.ArgumentParser._get_nargs_pattern`` - adds support for nargs ranges.
-See _get_nargs_pattern_wrapper for more details.
+See ``_get_nargs_pattern_wrapper`` for more details.
 
 ``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.
+See ``_match_argument_wrapper`` for more details.
 
 **Added accessor methods**
 
 cmd2 has patched ``argparse.Action`` to include the following accessor methods
 for cases in which you need to manually access the cmd2-specific attributes.
 
-- ``argparse.Action.get_choices_callable()`` - See `action_get_choices_callable` for more details.
-- ``argparse.Action.set_choices_provider()`` - See `_action_set_choices_provider` for more details.
-- ``argparse.Action.set_completer()`` - See `_action_set_completer` for more details.
-- ``argparse.Action.get_table_columns()`` - See `_action_get_table_columns` for more details.
-- ``argparse.Action.set_table_columns()`` - See `_action_set_table_columns` for more details.
-- ``argparse.Action.get_nargs_range()`` - See `_action_get_nargs_range` for more details.
-- ``argparse.Action.set_nargs_range()`` - See `_action_set_nargs_range` for more details.
-- ``argparse.Action.get_suppress_tab_hint()`` - See `_action_get_suppress_tab_hint` for more details.
-- ``argparse.Action.set_suppress_tab_hint()`` - See `_action_set_suppress_tab_hint` for more details.
+- ``argparse.Action.get_choices_callable()`` - See ``action_get_choices_callable`` for more details.
+- ``argparse.Action.set_choices_provider()`` - See ``_action_set_choices_provider`` for more details.
+- ``argparse.Action.set_completer()`` - See ``_action_set_completer`` for more details.
+- ``argparse.Action.get_table_columns()`` - See ``_action_get_table_columns`` for more details.
+- ``argparse.Action.set_table_columns()`` - See ``_action_set_table_columns`` for more details.
+- ``argparse.Action.get_nargs_range()`` - See ``_action_get_nargs_range`` for more details.
+- ``argparse.Action.set_nargs_range()`` - See ``_action_set_nargs_range`` for more details.
+- ``argparse.Action.get_suppress_tab_hint()`` - See ``_action_get_suppress_tab_hint`` for more details.
+- ``argparse.Action.set_suppress_tab_hint()`` - See ``_action_set_suppress_tab_hint`` for more details.
 
 cmd2 has patched ``argparse.ArgumentParser`` to include the following accessor methods
 
-- ``argparse.ArgumentParser.get_ap_completer_type()`` - See `_ArgumentParser_get_ap_completer_type` for more details.
-- ``argparse.Action.set_ap_completer_type()`` - See `_ArgumentParser_set_ap_completer_type` for more details.
+- ``argparse.ArgumentParser.get_ap_completer_type()`` - See ``_ArgumentParser_get_ap_completer_type`` for more details.
+- ``argparse.Action.set_ap_completer_type()`` - See ``_ArgumentParser_set_ap_completer_type`` for more details.
+
+**Subcommand Manipulation**
 
-**Subcommand removal**
+cmd2 has patched ``argparse._SubParsersAction`` with new functions to better facilitate the
+addition and removal of subcommand parsers.
 
-cmd2 has patched ``argparse._SubParsersAction`` to include a ``remove_parser()``
-method which can be used to remove a subcommand.
+``argparse._SubParsersAction.attach_parser`` - new function to attach
+an existing ArgumentParser to a subparsers action. See ``_SubParsersAction_attach_parser``
+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.
+``argparse._SubParsersAction.detach_parser`` - new function to detach a
+parser from a subparsers action. See ``_SubParsersAction_detach_parser`` for
+more details.
 """
 
 import argparse
@@ -944,39 +945,85 @@ def _ArgumentParser_check_value(_self: argparse.ArgumentParser, action: argparse
 
 
 ############################################################################################################
-# Patch argparse._SubParsersAction to add remove_parser function
+# Patch argparse._SubParsersAction to add attach_parser function
 ############################################################################################################
 
 
-def _SubParsersAction_remove_parser(self: argparse._SubParsersAction, name: str) -> None:  # type: ignore[type-arg]  # noqa: N802
-    """Remove a sub-parser from a sub-parsers group. Used to remove subcommands from a parser.
+def _SubParsersAction_attach_parser(  # noqa: N802
+    self: argparse._SubParsersAction,  # type: ignore[type-arg]
+    name: str,
+    subcmd_parser: argparse.ArgumentParser,
+    **add_parser_kwargs: Any,
+) -> None:
+    """Attach an existing ArgumentParser to a subparsers action.
+
+    This is useful when a parser is pre-configured (e.g. by cmd2's subcommand decorator)
+    and needs to be attached to a parent parser.
 
-    This function is added by cmd2 as a method called ``remove_parser()`` to ``argparse._SubParsersAction`` class.
+    This function is added by cmd2 as a method called ``attach_parser()``
+    to ``argparse._SubParsersAction`` class.
 
-    To call: ``action.remove_parser(name)``
+    To call: ``action.attach_parser(name, subcmd_parser, **add_parser_kwargs)``
 
     :param self: instance of the _SubParsersAction being edited
-    :param name: name of the subcommand for the sub-parser to remove
+    :param name: name of the subcommand to add
+    :param subcmd_parser: the parser for this new subcommand
+    :param add_parser_kwargs: registration-specific kwargs for add_parser()
+                              (e.g. help, aliases, deprecated [Python 3.13+])
     """
-    # Remove this subcommand from its base command's help text
-    for choice_action in self._choices_actions:
-        if choice_action.dest == name:
-            self._choices_actions.remove(choice_action)
-            break
+    # Use add_parser to register the subcommand name and any aliases
+    self.add_parser(name, **add_parser_kwargs)
+
+    # Replace the parser created by add_parser() with our pre-configured one
+    self._name_parser_map[name] = subcmd_parser
+
+    # Remap any aliases to our pre-configured parser
+    for alias in add_parser_kwargs.get("aliases", ()):
+        self._name_parser_map[alias] = subcmd_parser
+
+
+setattr(argparse._SubParsersAction, 'attach_parser', _SubParsersAction_attach_parser)
 
-    # Remove this subcommand and all its aliases from the base command
+############################################################################################################
+# Patch argparse._SubParsersAction to add detach_parser function
+############################################################################################################
+
+
+def _SubParsersAction_detach_parser(  # noqa: N802
+    self: argparse._SubParsersAction,  # type: ignore[type-arg]
+    name: str,
+) -> argparse.ArgumentParser | None:
+    """Detach a parser from a subparsers action and return it.
+
+    This function is added by cmd2 as a method called ``detach_parser()`` to ``argparse._SubParsersAction`` class.
+
+    To call: ``action.detach_parser(name)``
+
+    :param self: instance of the _SubParsersAction being edited
+    :param name: name of the subcommand for the parser to detach
+    :return: the parser which was detached or None if the subcommand doesn't exist
+    """
     subparser = self._name_parser_map.get(name)
+
     if subparser is not None:
+        # Remove this subcommand and all its aliases from the base command
         to_remove = []
         for cur_name, cur_parser in self._name_parser_map.items():
             if cur_parser is subparser:
                 to_remove.append(cur_name)
         for cur_name in to_remove:
             del self._name_parser_map[cur_name]
 
+        # Remove this subcommand from its base command's help text
+        for choice_action in self._choices_actions:
+            if choice_action.dest == name:
+                self._choices_actions.remove(choice_action)
+                break
+
+    return subparser
 
-setattr(argparse._SubParsersAction, 'remove_parser', _SubParsersAction_remove_parser)
 
+setattr(argparse._SubParsersAction, 'detach_parser', _SubParsersAction_detach_parser)
 
 ############################################################################################################
 # Unless otherwise noted, everything below this point are copied from Python's

cmd2/cmd2.py

@@ -88,6 +88,7 @@
     RenderableType,
 )
 from rich.highlighter import ReprHighlighter
+from rich.pretty import Pretty
 from rich.rule import Rule
 from rich.style import (
     Style,
@@ -1128,19 +1129,15 @@ def find_subcommand(
             # Find the argparse action that handles subcommands
             for action in target_parser._actions:
                 if isinstance(action, argparse._SubParsersAction):
-                    # Get the kwargs for add_parser()
+                    # Get add_parser() kwargs (aliases, help, etc.) defined by the decorator
                     add_parser_kwargs = getattr(method, constants.SUBCMD_ATTR_ADD_PARSER_KWARGS, {})
 
-                    # Use add_parser to register the subcommand name and any aliases
-                    action.add_parser(subcommand_name, **add_parser_kwargs)
-
-                    # Replace the parser created by add_parser() with our pre-configured one
-                    action._name_parser_map[subcommand_name] = subcmd_parser
-
-                    # Also remap any aliases to our pre-configured parser
-                    for alias in add_parser_kwargs.get("aliases", []):
-                        action._name_parser_map[alias] = subcmd_parser
-
+                    # Attach existing parser as a subcommand
+                    action.attach_parser(  # type: ignore[attr-defined]
+                        subcommand_name,
+                        subcmd_parser,
+                        **add_parser_kwargs,
+                    )
                     break
 
     def _unregister_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:
@@ -1187,7 +1184,7 @@ def _unregister_subcommands(self, cmdset: Union[CommandSet, 'Cmd']) -> None:
 
             for action in command_parser._actions:
                 if isinstance(action, argparse._SubParsersAction):
-                    action.remove_parser(subcommand_name)  # type: ignore[attr-defined]
+                    action.detach_parser(subcommand_name)  # type: ignore[attr-defined]
                     break
 
     @property
@@ -1822,6 +1819,56 @@ def ppaged(
                 rich_print_kwargs=rich_print_kwargs,
             )
 
+    def ppretty(
+        self,
+        obj: Any,
+        *,
+        file: IO[str] | None = None,
+        indent_size: int = 4,
+        indent_guides: bool = True,
+        max_length: int | None = None,
+        max_string: int | None = None,
+        max_depth: int | None = None,
+        expand_all: bool = False,
+        end: str = "\n",
+    ) -> None:
+        """Pretty print an object.
+
+        This is a cmd2-compatible replacement for rich.pretty.pprint().
+
+        :param obj: object to pretty print
+        :param file: file stream being written to or None for self.stdout.
+                     Defaults to None.
+        :param indent_size: number of spaces in indent. Defaults to 4.
+        :param indent_guides: enable indentation guides. Defaults to True.
+        :param max_length: maximum length of containers before abbreviating, or None for no abbreviation.
+                           Defaults to None.
+        :param max_string: maximum length of strings before truncating, or None to disable. Defaults to None.
+        :param max_depth: maximum depth for nested data structures, or None for unlimited depth. Defaults to None.
+        :param expand_all: Expand all containers. Defaults to False.
+        :param end: string to write at end of printed text. Defaults to a newline.
+        """
+        # The overflow and soft_wrap values match those in rich.pretty.pprint().
+        # This ensures long strings are neither truncated with ellipses nor broken
+        # up by injected newlines.
+        pretty_obj = Pretty(
+            obj,
+            indent_size=indent_size,
+            indent_guides=indent_guides,
+            max_length=max_length,
+            max_string=max_string,
+            max_depth=max_depth,
+            expand_all=expand_all,
+            overflow="ignore",
+        )
+
+        self.print_to(
+            file or self.stdout,
+            pretty_obj,
+            soft_wrap=True,
+            end=end,
+        )
+
     def get_bottom_toolbar(self) -> list[str | tuple[str, str]] | None:
         """Get the bottom toolbar content.
 

cmd2/decorators.py

@@ -527,6 +527,7 @@ def as_subcommand_to(
     *,
     help: str | None = None,  # noqa: A002
     aliases: Sequence[str] | None = None,
+    **add_parser_kwargs: Any,
 ) -> Callable[[ArgparseCommandFunc[CmdOrSet]], ArgparseCommandFunc[CmdOrSet]]:
     """Tag this method as a subcommand to an existing argparse decorated command.
 
@@ -537,6 +538,8 @@ def as_subcommand_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
                     subparsers.add_parser().
+    :param add_parser_kwargs: other registration-specific kwargs for add_parser()
+                              (e.g. deprecated [Python 3.13+])
     :return: Wrapper function that can receive an argparse.Namespace
     """
 
@@ -547,13 +550,13 @@ def arg_decorator(func: ArgparseCommandFunc[CmdOrSet]) -> ArgparseCommandFunc[Cm
         setattr(func, constants.SUBCMD_ATTR_NAME, subcommand)
 
         # Keyword arguments for subparsers.add_parser()
-        add_parser_kwargs: dict[str, Any] = {}
+        final_kwargs: dict[str, Any] = dict(add_parser_kwargs)
         if help is not None:
-            add_parser_kwargs['help'] = help
+            final_kwargs['help'] = help
         if aliases:
-            add_parser_kwargs['aliases'] = aliases[:]
+            final_kwargs['aliases'] = tuple(aliases)
 
-        setattr(func, constants.SUBCMD_ATTR_ADD_PARSER_KWARGS, add_parser_kwargs)
+        setattr(func, constants.SUBCMD_ATTR_ADD_PARSER_KWARGS, final_kwargs)
 
         return func
 

cmd2/utils.py

@@ -74,7 +74,7 @@ def __init__(
         settable_object: object,
         *,
         settable_attrib_name: str | None = None,
-        onchange_cb: Callable[[str, _T, _T], Any] | None = None,
+        onchange_cb: Callable[[str, Any, Any], Any] | None = None,
         choices: Iterable[Any] | None = None,
         choices_provider: ChoicesProviderUnbound[CmdOrSet] | None = None,
         completer: CompleterUnbound[CmdOrSet] | None = None,

examples/pretty_print.py

@@ -1,42 +1,26 @@
 #!/usr/bin/env python3
-"""A simple example demonstrating how to pretty print JSON data in a cmd2 app using rich."""
-
-from rich.json import JSON
+"""A simple example demonstrating how to pretty print data."""
 
 import cmd2
 
 EXAMPLE_DATA = {
     "name": "John Doe",
     "age": 30,
     "address": {"street": "123 Main St", "city": "Anytown", "state": "CA"},
-    "hobbies": ["reading", "hiking", "coding"],
+    "hobbies": ["reading", "hiking", "coding", "cooking", "running", "painting", "music", "photography", "cycling"],
+    "member": True,
+    "vip": False,
+    "phone": None,
 }
 
 
 class Cmd2App(cmd2.Cmd):
     def __init__(self) -> None:
         super().__init__()
-        self.data = EXAMPLE_DATA
-
-    def do_normal(self, _) -> None:
-        """Display the data using the normal poutput method."""
-        self.poutput(self.data)
-
-    def do_pretty(self, _) -> None:
-        """Display the JSON data in a pretty way using rich."""
 
-        json_renderable = JSON.from_data(
-            self.data,
-            indent=2,
-            highlight=True,
-            skip_keys=False,
-            ensure_ascii=False,
-            check_circular=True,
-            allow_nan=True,
-            default=None,
-            sort_keys=False,
-        )
-        self.poutput(json_renderable)
+    def do_pretty(self, _: cmd2.Statement) -> None:
+        """Print an object using ppretty()."""
+        self.ppretty(EXAMPLE_DATA)
 
 
 if __name__ == '__main__':