cmd2 4.0.0b4__tar.gz → 4.0.0b6__tar.gz

{cmd2-4.0.0b4 → cmd2-4.0.0b6}/CHANGELOG.md

@@ -81,7 +81,9 @@ prompt is displayed.
     - `cmd2` no longer sets a default title for a subparsers group. If you desire a title, you will
       need to pass one in like this `parser.add_subparsers(title="subcommands")`. This is standard
       `argparse` behavior.
-    - `TextGroup` is now a standalone Rich renderable.
+    - Added `HelpFormatterRenderable` protocol and `HelpContent` type alias to support context-aware
+      help content in `argparse`.
+    - `TextGroup` now implements `HelpFormatterRenderable`.
         - Removed `formatter_creator` parameter from `TextGroup.__init__()`.
         - Removed `Cmd2ArgumentParser.create_text_group()` method.
     - `argparse` and `Rich` integration refactoring:
@@ -96,6 +98,17 @@ prompt is displayed.
         - Replaced the global `APP_THEME` constant in `rich_utils.py` with `get_theme()` and
           `set_theme()` functions to support lazy initialization and safer in-place updates of the
           theme.
+    - Renamed `Cmd._command_parsers` to `Cmd.command_parsers`.
+    - Removed `RichPrintKwargs` `TypedDict` in favor of using `Mapping[str, Any]`, allowing for
+      greater flexibility in passing keyword arguments to `console.print()` calls.
+    - Removed `always_show_hint` settable as it provided a poor user experience with
+      `prompt-toolkit`
+    - `cmd2` redirection only captures output directed to `self.stdout` (e.g., via
+      `self.poutput()`). Standard `print()` calls write directly to `sys.stdout` and are not
+      captured. However, `print()` calls within `pyscripts` and the interactive Python shell are
+      treated as command output and sent to `self.stdout`, allowing them to be captured.
+    - Verbose help table descriptions are no longer generated from help function output. The system
+      now relies exclusively on command function docstrings.
 - Enhancements
     - New `cmd2.Cmd` parameters
         - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These
@@ -113,8 +126,9 @@ prompt is displayed.
         - **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
+        - **max_column_completion_results**: (int) Maximum number of completion results to display
+          in a single column
+        - **traceback_show_locals**: (bool) Display local variables in tracebacks
     - `cmd2.Cmd.select` has been revamped to use the
       [choice](https://python-prompt-toolkit.readthedocs.io/en/3.0.52/pages/asking_for_a_choice.html)
       function from `prompt-toolkit` when both **stdin** and **stdout** are TTYs
@@ -130,6 +144,18 @@ prompt is displayed.
       specific `cmd2.Cmd` subclass (e.g.,`class MyCommandSet(CommandSet[MyApp]):`). This provides
       full type hints and IDE autocompletion for `self._cmd` without needing to override and cast
       the property.
+    - Added `traceback_kwargs` attribute to allow customization of Rich-based tracebacks.
+    - The `print()` function available in a `pyscript` writes to `self.stdout` and respects the
+      `allow_style` setting. It also supports printing `Rich` objects.
+    - Added `Cmd2ArgumentParser.output_to()` context manager to temporarily set the output stream
+      during `argparse` operations. This is helpful for directing output for functions like
+      `parse_args()`, which default to `sys.stdout` and lack a `file` argument.
+
+## 3.5.1 (April 24, 2026)
+
+- Bug Fixes
+    - Fixed `ArgparseCompleter.print_help()` not passing file stream to recursive call.
+    - Fixed issue where `constants.REDIRECTION_TOKENS` was being mutated.
 
 ## 3.5.0 (April 13, 2026)
 

{cmd2-4.0.0b4 → cmd2-4.0.0b6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cmd2
-Version: 4.0.0b4
+Version: 4.0.0b6
 Summary: cmd2 - quickly build feature-rich and user-friendly interactive command line applications in Python
 Author: cmd2 Contributors
 License-Expression: MIT

{cmd2-4.0.0b4 → cmd2-4.0.0b6}/cmd2/__init__.py

@@ -50,7 +50,6 @@ from .rich_utils import (
     MetavarTypeCmd2HelpFormatter,
     RawDescriptionCmd2HelpFormatter,
     RawTextCmd2HelpFormatter,
-    RichPrintKwargs,
     TextGroup,
     get_theme,
     set_theme,
@@ -105,7 +104,6 @@ __all__: list[str] = [  # noqa: RUF022
     "MetavarTypeCmd2HelpFormatter",
     "RawDescriptionCmd2HelpFormatter",
     "RawTextCmd2HelpFormatter",
-    "RichPrintKwargs",
     "set_theme",
     "TextGroup",
     # String Utils

{cmd2-4.0.0b4 → cmd2-4.0.0b6}/cmd2/argparse_completer.py

@@ -491,13 +491,6 @@ class ArgparseCompleter:
 
             # If we have results, then return them
             if completions:
-                if not completions.hint:
-                    # Add a hint even though there are results in case Cmd.always_show_hint is True.
-                    completions = dataclasses.replace(
-                        completions,
-                        hint=_build_hint(self._parser, flag_arg_state.action),
-                    )
-
                 return completions
 
             # Otherwise, print a hint if the flag isn't finished or text isn't possibly the start of a flag
@@ -519,12 +512,6 @@ class ArgparseCompleter:
 
             # If we have results, then return them
             if completions:
-                if not completions.hint:
-                    # Add a hint even though there are results in case Cmd.always_show_hint is True.
-                    completions = dataclasses.replace(
-                        completions,
-                        hint=_build_hint(self._parser, pos_arg_state.action),
-                    )
                 return completions
 
             # Otherwise, print a hint if text isn't possibly the start of a flag
@@ -705,9 +692,9 @@ class ArgparseCompleter:
             if parser is not None:
                 completer_type = self._cmd2_app._determine_ap_completer_type(parser)
                 completer = completer_type(parser, self._cmd2_app)
-                completer.print_help(tokens[1:])
+                completer.print_help(tokens[1:], file)
                 return
-        self._parser.print_help(file=file)
+        self._parser.print_help(file)
 
     def _choices_to_items(self, arg_state: _ArgumentState) -> list[CompletionItem]:
         """Convert choices from action to list of CompletionItems."""

{cmd2-4.0.0b4 → cmd2-4.0.0b6}/cmd2/argparse_utils.py

@@ -225,27 +225,35 @@ available on the resulting ``Action`` object to access its underlying attribute:
 """
 
 import argparse
+import contextlib
 import re
 import sys
+import threading
 from argparse import ArgumentError
 from collections.abc import (
     Callable,
     Iterable,
+    Iterator,
     Sequence,
 )
+from dataclasses import dataclass
 from typing import (
+    IO,
     TYPE_CHECKING,
     Any,
+    ClassVar,
     NoReturn,
     cast,
 )
 
-from rich.console import RenderableType
 from rich.table import Column
 
 from . import constants
 from .completion import CompletionItem
-from .rich_utils import Cmd2HelpFormatter
+from .rich_utils import (
+    Cmd2HelpFormatter,
+    HelpContent,
+)
 from .styles import Cmd2Style
 from .types import (
     CmdOrSetT,
@@ -494,16 +502,93 @@ def _ActionsContainer_add_argument(  # noqa: N802
 # Overwrite _ActionsContainer.add_argument with our patch
 argparse._ActionsContainer.add_argument = _ActionsContainer_add_argument  # type: ignore[method-assign]
 
+############################################################################################################
+# Patch argparse._SubParsersAction by adding remove_parser() function
+############################################################################################################
+
+
+def _SubParsersAction_remove_parser(  # noqa: N802
+    self: argparse._SubParsersAction,  # type: ignore[type-arg]
+    name: str,
+) -> argparse.ArgumentParser:
+    """Remove a subparser from a subparsers group.
+
+    This function is added by cmd2 as a method called ``remove_parser()``
+    to ``argparse._SubParsersAction`` class.
+
+    To call: ``action.remove_parser(name)``
+
+    :param self: instance of the _SubParsersAction being edited
+    :param name: name of the subcommand for the subparser to remove
+    :return: the removed parser
+    :raises ValueError: if the subcommand doesn't exist
+    """
+    if name not in self._name_parser_map:
+        raise ValueError(f"Subcommand '{name}' does not exist")
+
+    subparser = self._name_parser_map[name]
+
+    # Find all names (primary and aliases) that map to this subparser
+    all_names = [cur_name for cur_name, cur_parser in self._name_parser_map.items() if cur_parser is subparser]
+
+    # Remove the help entry for this subparser. To handle the case where
+    # name is an alias, we remove the action whose 'dest' matches any of
+    # the names mapped to this subparser.
+    for choice_action in self._choices_actions:
+        if choice_action.dest in all_names:
+            self._choices_actions.remove(choice_action)
+            break
+
+    # Remove all references to this subparser, including aliases.
+    for cur_name in all_names:
+        del self._name_parser_map[cur_name]
+
+    return cast(argparse.ArgumentParser, subparser)
+
+
+argparse._SubParsersAction.remove_parser = _SubParsersAction_remove_parser  # type: ignore[attr-defined]
+
+
+@dataclass
+class _ParserThreadLocals(threading.local):
+    """Thread-local storage used by Cmd2ArgumentParser to manage execution context."""
+
+    # The active output stream for help, usage, and errors. Since argparse does not
+    # pass the destination stream to the formatter factory, this transient value
+    # provides the context needed to synchronize Rich's rendering with the specific
+    # capabilities of the destination file descriptor. It is managed via the
+    # output_to() context manager.
+    current_output_file: IO[str] | None = None
+
 
 class Cmd2ArgumentParser(argparse.ArgumentParser):
     """Custom ArgumentParser class that improves error and help output."""
 
+    # Thread-local storage shared by all parser instances (including subparsers)
+    _thread_locals: ClassVar[_ParserThreadLocals] = _ParserThreadLocals()
+
+    @contextlib.contextmanager
+    def output_to(self, file: IO[str] | None) -> Iterator[None]:
+        """Context manager to temporarily set the output stream during argparse operations.
+
+        This is helpful for directing output for functions like `parse_args()`, which
+        default to `sys.stdout` and lack a `file` argument.
+
+        :param file: the file stream to use for output
+        """
+        previous = self._thread_locals.current_output_file
+        self._thread_locals.current_output_file = file
+        try:
+            yield
+        finally:
+            self._thread_locals.current_output_file = previous
+
     def __init__(
         self,
         prog: str | None = None,
         usage: str | None = None,
-        description: RenderableType | None = None,
-        epilog: RenderableType | None = None,
+        description: HelpContent | None = None,
+        epilog: HelpContent | None = None,
         parents: Sequence[argparse.ArgumentParser] = (),
         formatter_class: type[Cmd2HelpFormatter] = Cmd2HelpFormatter,
         prefix_chars: str = "-",
@@ -553,10 +638,26 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
 
         # To assist type checkers, recast these to reflect our usage of rich-argparse.
         self.formatter_class: type[Cmd2HelpFormatter]
-        self.description: RenderableType | None  # type: ignore[assignment]
-        self.epilog: RenderableType | None  # type: ignore[assignment]
+        self.description: HelpContent | None  # type: ignore[assignment]
+        self.epilog: HelpContent | None  # type: ignore[assignment]
+
+    def print_usage(self, file: IO[str] | None = None) -> None:  # type:ignore[override]
+        """Override to ensure the formatter is aware of the target file."""
+        if file is None:
+            file = self._thread_locals.current_output_file
 
-    def _get_subparsers_action(self) -> "argparse._SubParsersAction[Cmd2ArgumentParser]":
+        with self.output_to(file):
+            super().print_usage(file)
+
+    def print_help(self, file: IO[str] | None = None) -> None:  # type:ignore[override]
+        """Override to ensure the formatter is aware of the target file."""
+        if file is None:
+            file = self._thread_locals.current_output_file
+
+        with self.output_to(file):
+            super().print_help(file)
+
+    def get_subparsers_action(self) -> "argparse._SubParsersAction[Cmd2ArgumentParser]":
         """Get the _SubParsersAction for this parser if it exists.
 
         :return: the _SubParsersAction for this parser
@@ -619,7 +720,7 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         self.prog = prog
 
         try:
-            subparsers_action = self._get_subparsers_action()
+            subparsers_action = self.get_subparsers_action()
         except ValueError:
             # This parser has no subcommands
             return
@@ -638,12 +739,14 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         # add_parser() will have the correct prog value.
         subparsers_action._prog_prefix = self._build_subparsers_prog_prefix(positionals)
 
-        # subparsers_action.choices includes aliases. Since primary names are inserted first,
-        # we skip already updated parsers to ensure primary names are used in 'prog'.
+        # subparsers_action._name_parser_map includes aliases. Since primary names are inserted
+        # first, we skip already updated parsers to ensure primary names are used in 'prog'.
+        # We can't rely on subparsers_action._choices_actions to filter out aliases because while
+        # it contains only primary names, it omits any subcommands that lack help text.
         updated_parsers: set[Cmd2ArgumentParser] = set()
 
         # Set the prog value for each subcommand's parser
-        for subcmd_name, subcmd_parser in subparsers_action.choices.items():
+        for subcmd_name, subcmd_parser in subparsers_action._name_parser_map.items():
             if subcmd_parser in updated_parsers:
                 continue
 
@@ -651,7 +754,7 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
             subcmd_parser.update_prog(subcmd_prog)
             updated_parsers.add(subcmd_parser)
 
-    def _find_parser(self, subcommand_path: Iterable[str]) -> "Cmd2ArgumentParser":
+    def find_parser(self, subcommand_path: Iterable[str]) -> "Cmd2ArgumentParser":
         """Find a parser in the hierarchy based on a sequence of subcommand names.
 
         :param subcommand_path: sequence of subcommand names leading to the target parser
@@ -660,10 +763,10 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         """
         parser = self
         for name in subcommand_path:
-            subparsers_action = parser._get_subparsers_action()
-            if name not in subparsers_action.choices:
-                raise ValueError(f"Subcommand '{name}' not found in '{parser.prog}'")
-            parser = subparsers_action.choices[name]
+            subparsers_action = parser.get_subparsers_action()
+            if name not in subparsers_action._name_parser_map:
+                raise ValueError(f"Subcommand '{name}' does not exist for '{parser.prog}'")
+            parser = subparsers_action._name_parser_map[name]
         return parser
 
     def attach_subcommand(
@@ -683,7 +786,8 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         :raises TypeError: if subcommand_parser is not an instance of the following or their subclasses:
                            1. Cmd2ArgumentParser
                            2. The parser_class configured for the target subcommand group
-        :raises ValueError: if the command path is invalid or doesn't support subcommands
+        :raises ValueError: if the command path is invalid, doesn't support subcommands, or the
+                            subcommand already exists
         """
         if not isinstance(subcommand_parser, Cmd2ArgumentParser):
             raise TypeError(
@@ -691,8 +795,8 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
                 f"Received: '{type(subcommand_parser).__name__}'."
             )
 
-        target_parser = self._find_parser(subcommand_path)
-        subparsers_action = target_parser._get_subparsers_action()
+        target_parser = self.find_parser(subcommand_path)
+        subparsers_action = target_parser.get_subparsers_action()
 
         # Verify the parser is compatible with the 'parser_class' configured for this
         # subcommand group. We use isinstance() here to allow for subclasses, providing
@@ -705,6 +809,12 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
                 f"Received: '{type(subcommand_parser).__name__}'."
             )
 
+        # Do not overwrite existing subcommands or aliases
+        all_names = (subcommand, *add_parser_kwargs.get("aliases", ()))
+        for name in all_names:
+            if name in subparsers_action._name_parser_map:
+                raise ValueError(f"Subcommand '{name}' already exists for '{target_parser.prog}'")
+
         # Use add_parser to register the subcommand name and any aliases
         placeholder_parser = subparsers_action.add_parser(subcommand, **add_parser_kwargs)
 
@@ -728,28 +838,16 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
         :return: the detached parser
         :raises ValueError: if the command path is invalid or the subcommand doesn't exist
         """
-        target_parser = self._find_parser(subcommand_path)
-        subparsers_action = target_parser._get_subparsers_action()
-
-        subparser = subparsers_action._name_parser_map.get(subcommand)
-        if subparser is None:
-            raise ValueError(f"Subcommand '{subcommand}' not found in '{target_parser.prog}'")
-
-        # Remove this subcommand and all its aliases from the base command
-        to_remove = []
-        for cur_name, cur_parser in subparsers_action._name_parser_map.items():
-            if cur_parser is subparser:
-                to_remove.append(cur_name)
-        for cur_name in to_remove:
-            del subparsers_action._name_parser_map[cur_name]
-
-        # Remove this subcommand from its base command's help text
-        for choice_action in subparsers_action._choices_actions:
-            if choice_action.dest == subcommand:
-                subparsers_action._choices_actions.remove(choice_action)
-                break
+        target_parser = self.find_parser(subcommand_path)
+        subparsers_action = target_parser.get_subparsers_action()
 
-        return subparser
+        try:
+            return cast(
+                Cmd2ArgumentParser,
+                subparsers_action.remove_parser(subcommand),  # type: ignore[attr-defined]
+            )
+        except ValueError:
+            raise ValueError(f"Subcommand '{subcommand}' does not exist for '{target_parser.prog}'") from None
 
     def error(self, message: str) -> NoReturn:
         """Override that applies custom formatting to the error message."""
@@ -761,19 +859,21 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
             else:
                 formatted_message += "\n       " + line
 
-        self.print_usage(sys.stderr)
+        with self.output_to(sys.stderr):
+            self.print_usage(sys.stderr)
 
-        # Use console to add style since it will respect ALLOW_STYLE's value
-        console = self._get_formatter().console
-        with console.capture() as capture:
-            console.print(formatted_message, style=Cmd2Style.ERROR)
-        formatted_message = f"{capture.get()}"
+            # Use console to add style since it will respect ALLOW_STYLE's value.
+            # Now _get_formatter() will return a formatter bound to stderr.
+            console = self._get_formatter().console
+            with console.capture() as capture:
+                console.print(formatted_message, style=Cmd2Style.ERROR)
+            formatted_message = f"{capture.get()}"
 
         self.exit(2, f"{formatted_message}\n")
 
-    def _get_formatter(self, **kwargs: Any) -> Cmd2HelpFormatter:
+    def _get_formatter(self, **_kwargs: Any) -> Cmd2HelpFormatter:
         """Override with customizations for Cmd2HelpFormatter."""
-        return cast(Cmd2HelpFormatter, super()._get_formatter(**kwargs))
+        return self.formatter_class(prog=self.prog, file=self._thread_locals.current_output_file)
 
     def format_help(self) -> str:
         """Override to add a newline."""