Updated documentation.

Author: kmvanbrunt

cmd2/cmd2.py

@@ -170,7 +170,7 @@
 
 # Set up readline
 if rl_type == RlType.NONE:  # pragma: no cover
-    Cmd2GeneralConsole(sys.stderr).print(rl_warning, style=Cmd2Style.WARNING)
+    Cmd2GeneralConsole(file=sys.stderr).print(rl_warning, style=Cmd2Style.WARNING)
 else:
     from .rl_utils import (
         readline,
@@ -1351,7 +1351,7 @@ def print_to(
             console = destination
         else:
             # It's a file-like object (e.g., sys.stdout, StringIO)
-            console = Cmd2GeneralConsole(destination)
+            console = Cmd2GeneralConsole(file=destination)
 
         prepared_objects = ru.prepare_objects_for_rendering(*objects)
 
@@ -1374,7 +1374,7 @@ def print_to(
             # warning message, then set the broken_pipe_warning attribute
             # to the message you want printed.
             if self.broken_pipe_warning and console.file != sys.stderr:
-                Cmd2GeneralConsole(sys.stderr).print(self.broken_pipe_warning)
+                Cmd2GeneralConsole(file=sys.stderr).print(self.broken_pipe_warning)
 
     def poutput(
         self,
@@ -1507,7 +1507,7 @@ def pexcept(
         :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.
         """
-        console = Cmd2ExceptionConsole(sys.stderr)
+        console = Cmd2ExceptionConsole()
 
         # Only print a traceback if we're in debug mode and one exists.
         if self.debug and sys.exc_info() != (None, None, None):
@@ -1646,7 +1646,7 @@ def ppaged(
                 soft_wrap = True
 
             # Generate the bytes to send to the pager
-            console = Cmd2GeneralConsole(self.stdout)
+            console = Cmd2GeneralConsole(file=self.stdout)
             with console.capture() as capture:
                 self.print_to(
                     console,

cmd2/rich_utils.py

@@ -124,6 +124,7 @@ class Cmd2BaseConsole(Console):
 
     def __init__(
         self,
+        *,
         file: IO[str] | None = None,
         **kwargs: Any,
     ) -> None:
@@ -180,17 +181,19 @@ def on_broken_pipe(self) -> None:
 
 
 class Cmd2GeneralConsole(Cmd2BaseConsole):
-    """Rich console for general-purpose printing."""
+    """Rich console for general-purpose printing.
 
-    def __init__(self, file: IO[str] | None = None) -> None:
+    It enables soft wrap and disables Rich's automatic detection for markup,
+    emoji, and highlighting. These defaults can be overridden in calls to the
+    console's or cmd2's print methods.
+    """
+
+    def __init__(self, *, file: IO[str] | None = None) -> None:
         """Cmd2GeneralConsole initializer.
 
         :param file: optional file object where the console should write to.
                      Defaults to sys.stdout.
         """
-        # This console is configured for general-purpose printing. It enables soft wrap
-        # and disables Rich's automatic detection for markup, emoji, and highlighting.
-        # These defaults can be overridden in calls to the console's or cmd2's print methods.
         super().__init__(
             file=file,
             soft_wrap=True,
@@ -203,35 +206,55 @@ def __init__(self, file: IO[str] | None = None) -> None:
 class Cmd2RichArgparseConsole(Cmd2BaseConsole):
     """Rich console for rich-argparse output.
 
-    This class ensures long lines in help text are not truncated by avoiding soft_wrap,
+    Ensures long lines in help text are not truncated by disabling soft_wrap,
     which conflicts with rich-argparse's explicit no_wrap and overflow settings.
+
+    Since this console is used to print error messages which may not be intended
+    for Rich formatting, it disables Rich's automatic detection for markup, emoji,
+    and highlighting. Because rich-argparse does markup and highlighting without
+    involving the console, disabling these settings does not affect the library's
+    internal functionality.
     """
 
-    def __init__(self, file: IO[str] | None = None) -> None:
+    def __init__(self, *, file: IO[str] | None = None) -> None:
         """Cmd2RichArgparseConsole initializer.
 
         :param file: optional file object where the console should write to.
                      Defaults to sys.stdout.
         """
-        # Since this console is used to print error messages which may not have
-        # been pre-formatted by rich-argparse, disable Rich's automatic detection
-        # for markup, emoji, and highlighting. rich-argparse does markup and
-        # highlighting without involving the console so these won't affect its
-        # internal functionality.
         super().__init__(
             file=file,
+            soft_wrap=False,
             markup=False,
             emoji=False,
             highlight=False,
         )
 
 
 class Cmd2ExceptionConsole(Cmd2BaseConsole):
-    """Rich console for printing exceptions.
+    """Rich console for printing exceptions and Rich Tracebacks.
 
-    Ensures that long exception messages word wrap for readability by keeping soft_wrap disabled.
+    Ensures that output is always word-wrapped for readability and disables
+    Rich's automatic detection for markup, emoji, and highlighting to prevent
+    interference with raw error data.
     """
 
+    def __init__(self, *, file: IO[str] | None = None) -> None:
+        """Cmd2ExceptionConsole initializer.
+
+        :param file: optional file object where the console should write to.
+                     If None, output defaults to sys.stderr.
+        """
+        # Use stderr=True so that Rich defaults to sys.stderr if file is None.
+        super().__init__(
+            file=file,
+            stderr=True,
+            soft_wrap=False,
+            markup=False,
+            emoji=False,
+            highlight=False,
+        )
+
 
 def console_width() -> int:
     """Return the width of the console."""