Merge branch 'main' into 1627-silence-settable

Author: tleonhardt

CHANGELOG.md

@@ -97,6 +97,10 @@ prompt is displayed.
           `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`
 - Enhancements
     - New `cmd2.Cmd` parameters
         - **auto_suggest**: (boolean) if `True`, provide fish shell style auto-suggestions. These
@@ -114,8 +118,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
@@ -131,10 +136,17 @@ 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
     - Updated `set` command to consolidate its confirmation output into a single, colorized line.
       The confirmation now uses `pfeedback()`, allowing it to be silenced when the `quiet` settable
       is enabled.
 
+## 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)
 
 - Bug Fixes

cmd2/__init__.py

@@ -50,7 +50,6 @@
     MetavarTypeCmd2HelpFormatter,
     RawDescriptionCmd2HelpFormatter,
     RawTextCmd2HelpFormatter,
-    RichPrintKwargs,
     TextGroup,
     get_theme,
     set_theme,
@@ -105,7 +104,6 @@
     "MetavarTypeCmd2HelpFormatter",
     "RawDescriptionCmd2HelpFormatter",
     "RawTextCmd2HelpFormatter",
-    "RichPrintKwargs",
     "set_theme",
     "TextGroup",
     # String Utils

cmd2/argparse_completer.py

@@ -491,13 +491,6 @@ def _handle_last_token(
 
             # 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 @@ def _handle_last_token(
 
             # 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,7 +692,7 @@ def print_help(self, tokens: Sequence[str], file: IO[str] | None = None) -> None
             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=file)
                 return
         self._parser.print_help(file=file)
 

cmd2/cmd2.py

@@ -154,7 +154,6 @@
     Cmd2ExceptionConsole,
     Cmd2GeneralConsole,
     Cmd2SimpleTable,
-    RichPrintKwargs,
     TextGroup,
 )
 from .styles import Cmd2Style
@@ -396,7 +395,8 @@ def __init__(
                                    instantiate and register all commands. If False, CommandSets
                                    must be manually installed with `register_command_set`.
         :param auto_suggest: If True, cmd2 will provide fish shell style auto-suggestions
-                            based on history. If False, these will not be provided.
+                            based on history. User can press right-arrow key to accept the
+                            provided suggestion.
         :param bottom_toolbar: if ``True``, then a bottom toolbar will be displayed.
         :param command_sets: Provide CommandSet instances to load during cmd2 initialization.
                              This allows CommandSets with custom constructor parameters to be
@@ -465,7 +465,6 @@ def __init__(
         self.interactive_pipe = False
 
         # Attributes which ARE dynamically settable via the set command at runtime
-        self.always_show_hint = False
         self.debug = False
         self.echo = False
         self.editor = self.DEFAULT_EDITOR
@@ -474,6 +473,19 @@ def __init__(
         self.scripts_add_to_history = True  # Scripts and pyscripts add commands to history
         self.timing = False  # Prints elapsed time for each command
 
+        # Default settings for Rich tracebacks created by format_exception().
+        # This dictionary can contain any parameter accepted by the
+        # rich.traceback.Traceback class. You can modify it to adjust
+        # the detail and layout of tracebacks.
+        self.traceback_kwargs: dict[str, Any] = {
+            "width": 100,
+            "code_width": None,  # Show all code characters
+            "show_locals": False,
+            "max_frames": 100,
+            "word_wrap": True,  # Wrap long lines of code instead of truncate
+            "indent_guides": True,
+        }
+
         # Cached Rich consoles used by core print methods.
         self._console_cache = _ConsoleCache()
 
@@ -1312,10 +1324,6 @@ def allow_style_type(value: str) -> ru.AllowStyle:
                 choices_provider=get_allow_style_choices,
             )
         )
-
-        self.add_settable(
-            Settable("always_show_hint", bool, "Display completion hint even when completion suggestions print", self)
-        )
         self.add_settable(Settable("debug", bool, "Show full traceback on exception", self))
         self.add_settable(Settable("echo", bool, "Echo command issued into output", self))
         self.add_settable(Settable("editor", str, "Program used by 'edit'", self))
@@ -1339,19 +1347,28 @@ def allow_style_type(value: str) -> ru.AllowStyle:
         self.add_settable(Settable("quiet", bool, "Don't print nonessential feedback", self))
         self.add_settable(Settable("scripts_add_to_history", bool, "Scripts and pyscripts add commands to history", self))
         self.add_settable(Settable("timing", bool, "Report execution times", self))
-
-    # -----  Methods related to presenting output to the user -----
+        self.add_settable(Settable("traceback_show_locals", bool, "Display local variables in tracebacks", self))
 
     @property
     def allow_style(self) -> ru.AllowStyle:
-        """Read-only property needed to support do_set when it reads allow_style."""
+        """Property needed to support do_set when it reads allow_style."""
         return ru.ALLOW_STYLE
 
     @allow_style.setter
     def allow_style(self, new_val: ru.AllowStyle) -> None:
         """Setter property needed to support do_set when it updates allow_style."""
         ru.ALLOW_STYLE = new_val
 
+    @property
+    def traceback_show_locals(self) -> bool:
+        """Property needed to support do_set when it reads traceback_show_locals."""
+        return cast(bool, self.traceback_kwargs.get("show_locals", False))
+
+    @traceback_show_locals.setter
+    def traceback_show_locals(self, value: bool) -> None:
+        """Setter property needed to support do_set when it updates traceback_show_locals."""
+        self.traceback_kwargs["show_locals"] = value
+
     @property
     def visible_prompt(self) -> str:
         """Read-only property to get the visible prompt with any ANSI style sequences stripped.
@@ -1426,7 +1443,7 @@ def print_to(
         emoji: bool = False,
         markup: bool = False,
         highlight: bool = False,
-        rich_print_kwargs: RichPrintKwargs | None = None,
+        rich_print_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,  # noqa: ARG002
     ) -> None:
         """Print objects to a given file stream.
@@ -1442,7 +1459,8 @@ def print_to(
         :param style: optional style to apply to output
         :param soft_wrap: Enable soft wrap mode. Defaults to True.
                           If True, text that doesn't fit will run on to the following line,
-                          just like with print(). This is useful for raw text and logs.
+                          just like the built-in print() function. This is useful for raw text
+                          and logs.
                           If False, Rich wraps text to fit the terminal width.
                           Set this to False when printing structured Renderables like
                           Tables, Panels, or Columns to ensure they render as expected.
@@ -1457,10 +1475,10 @@ def print_to(
                           strings, such as common Python data types like numbers, booleans, or None.
                           This is particularly useful when pretty printing objects like lists and
                           dictionaries to display them in color. Defaults to False.
-        :param rich_print_kwargs: optional additional keyword arguments to pass to Rich's Console.print().
+        :param rich_print_kwargs: optional additional keyword arguments to pass to console.print().
         :param kwargs: Arbitrary keyword arguments. This allows subclasses to extend the signature of this
                        method and still call `super()` without encountering unexpected keyword argument errors.
-                       These arguments are not passed to Rich's Console.print().
+                       These arguments are not passed to console.print().
 
         See the Rich documentation for more details on emoji codes, markup tags, and highlighting.
         """
@@ -1499,7 +1517,7 @@ def poutput(
         emoji: bool = False,
         markup: bool = False,
         highlight: bool = False,
-        rich_print_kwargs: RichPrintKwargs | None = None,
+        rich_print_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,  # noqa: ARG002
     ) -> None:
         """Print objects to self.stdout.
@@ -1531,7 +1549,7 @@ def perror(
         emoji: bool = False,
         markup: bool = False,
         highlight: bool = False,
-        rich_print_kwargs: RichPrintKwargs | None = None,
+        rich_print_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,  # noqa: ARG002
     ) -> None:
         """Print objects to sys.stderr.
@@ -1564,7 +1582,7 @@ def psuccess(
         emoji: bool = False,
         markup: bool = False,
         highlight: bool = False,
-        rich_print_kwargs: RichPrintKwargs | None = None,
+        rich_print_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,  # noqa: ARG002
     ) -> None:
         """Wrap poutput, but apply Cmd2Style.SUCCESS.
@@ -1594,7 +1612,7 @@ def pwarning(
         emoji: bool = False,
         markup: bool = False,
         highlight: bool = False,
-        rich_print_kwargs: RichPrintKwargs | None = None,
+        rich_print_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,  # noqa: ARG002
     ) -> None:
         """Wrap perror, but apply Cmd2Style.WARNING.
@@ -1626,13 +1644,7 @@ def format_exception(self, exception: BaseException) -> str:
         with console.capture() as capture:
             # Only print a traceback if we're in debug mode and one exists.
             if self.debug and sys.exc_info() != (None, None, None):
-                traceback = Traceback(
-                    width=None,  # Use all available width
-                    code_width=None,  # Use all available width
-                    show_locals=True,
-                    max_frames=0,  # 0 means full traceback.
-                    word_wrap=True,  # Wrap long lines of code instead of truncate
-                )
+                traceback = Traceback(**self.traceback_kwargs)
                 console.print(traceback, end="")
 
             else:
@@ -1690,7 +1702,7 @@ def pfeedback(
         emoji: bool = False,
         markup: bool = False,
         highlight: bool = False,
-        rich_print_kwargs: RichPrintKwargs | None = None,
+        rich_print_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,  # noqa: ARG002
     ) -> None:
         """Print nonessential feedback.
@@ -1740,7 +1752,7 @@ def ppaged(
         emoji: bool = False,
         markup: bool = False,
         highlight: bool = False,
-        rich_print_kwargs: RichPrintKwargs | None = None,
+        rich_print_kwargs: Mapping[str, Any] | None = None,
         **kwargs: Any,  # noqa: ARG002
     ) -> None:
         """Print output using a pager.
@@ -1960,10 +1972,8 @@ def tokens_for_completion(self, line: str, begidx: int, endidx: int) -> tuple[li
                  **On Failure**
                  - Two empty lists
         """
-        import copy
-
         unclosed_quote = ""
-        quotes_to_try = copy.copy(constants.QUOTES)
+        quotes_to_try = [*constants.QUOTES]
 
         tmp_line = line[:endidx]
         tmp_endidx = endidx
@@ -3802,8 +3812,7 @@ def _alias_create(self, args: argparse.Namespace) -> None:
             return
 
         # Unquote redirection and terminator tokens
-        tokens_to_unquote = constants.REDIRECTION_TOKENS
-        tokens_to_unquote.extend(self.statement_parser.terminators)
+        tokens_to_unquote = (*constants.REDIRECTION_TOKENS, *self.statement_parser.terminators)
         utils.unquote_specific_tokens(args.command_args, tokens_to_unquote)
 
         # Build the alias value string
@@ -3882,8 +3891,7 @@ def _alias_list(self, args: argparse.Namespace) -> None:
         """List some or all aliases as 'alias create' commands."""
         self.last_result = {}  # dict[alias_name, alias_value]
 
-        tokens_to_quote = constants.REDIRECTION_TOKENS
-        tokens_to_quote.extend(self.statement_parser.terminators)
+        tokens_to_quote = (*constants.REDIRECTION_TOKENS, *self.statement_parser.terminators)
 
         to_list = (
             utils.remove_duplicates(args.names)
@@ -4049,8 +4057,7 @@ def _macro_create(self, args: argparse.Namespace) -> None:
             return
 
         # Unquote redirection and terminator tokens
-        tokens_to_unquote = constants.REDIRECTION_TOKENS
-        tokens_to_unquote.extend(self.statement_parser.terminators)
+        tokens_to_unquote = (*constants.REDIRECTION_TOKENS, *self.statement_parser.terminators)
         utils.unquote_specific_tokens(args.command_args, tokens_to_unquote)
 
         # Build the macro value string
@@ -4172,8 +4179,7 @@ def _macro_list(self, args: argparse.Namespace) -> None:
         """List macros."""
         self.last_result = {}  # dict[macro_name, macro_value]
 
-        tokens_to_quote = constants.REDIRECTION_TOKENS
-        tokens_to_quote.extend(self.statement_parser.terminators)
+        tokens_to_quote = (*constants.REDIRECTION_TOKENS, *self.statement_parser.terminators)
 
         to_list = (
             utils.remove_duplicates(args.names)
@@ -4910,9 +4916,7 @@ def py_quit() -> None:
             """Exit an interactive Python environment, callable from the interactive Python console."""
             raise EmbeddedConsoleExit
 
-        from .py_bridge import (
-            PyBridge,
-        )
+        from .py_bridge import PyBridge
 
         add_to_history = self.scripts_add_to_history if pyscript else True
         py_bridge = PyBridge(self, add_to_history=add_to_history)

cmd2/constants.py

@@ -6,12 +6,12 @@
 INFINITY = float("inf")
 
 # Used for command parsing, output redirection, completion, and word breaks. Do not change.
-QUOTES = ['"', "'"]
+QUOTES = ('"', "'")
 REDIRECTION_PIPE = "|"
 REDIRECTION_OVERWRITE = ">"
 REDIRECTION_APPEND = ">>"
-REDIRECTION_CHARS = [REDIRECTION_PIPE, REDIRECTION_OVERWRITE]
-REDIRECTION_TOKENS = [REDIRECTION_PIPE, REDIRECTION_OVERWRITE, REDIRECTION_APPEND]
+REDIRECTION_CHARS = (REDIRECTION_PIPE, REDIRECTION_OVERWRITE)
+REDIRECTION_TOKENS = (REDIRECTION_PIPE, REDIRECTION_OVERWRITE, REDIRECTION_APPEND)
 COMMENT_CHAR = "#"
 MULTILINE_TERMINATOR = ";"