Added ability to pass a console object to Cmd.print_to().

Author: kmvanbrunt

CHANGELOG.md

@@ -1,3 +1,10 @@
+# 3.2.3 (TBD)
+
+  - Enhancements
+    - Added ability to pass a console object to `Cmd.print_to()`. This provides support for
+      things like wrapping a `print_to()` call in a `console.status()` or `console.capture()`
+      context manager.
+
 ## 3.2.2 (February 21, 2026)
 
 - Bug Fixes

cmd2/cmd2.py

@@ -65,7 +65,11 @@
 )
 
 import rich.box
-from rich.console import Group, RenderableType
+from rich.console import (
+    Console,
+    Group,
+    RenderableType,
+)
 from rich.highlighter import ReprHighlighter
 from rich.rule import Rule
 from rich.style import Style, StyleType
@@ -133,6 +137,7 @@
     shlex_split,
 )
 from .rich_utils import (
+    Cmd2BaseConsole,
     Cmd2ExceptionConsole,
     Cmd2GeneralConsole,
     RichPrintKwargs,
@@ -1247,7 +1252,7 @@ def visible_prompt(self) -> str:
 
     def print_to(
         self,
-        file: IO[str],
+        destination: IO[str] | Cmd2BaseConsole,
         *objects: Any,
         sep: str = " ",
         end: str = "\n",
@@ -1259,13 +1264,30 @@ def print_to(
         rich_print_kwargs: RichPrintKwargs | None = None,
         **kwargs: Any,  # noqa: ARG002
     ) -> None:
-        """Print objects to a given file stream.
+        """Print objects to a given destination (file stream or cmd2 console).
 
         This method is configured for general-purpose printing. By default, it enables
         soft wrap and disables Rich's automatic detection for markup, emoji, and highlighting.
         These defaults can be overridden by passing explicit keyword arguments.
 
-        :param file: file stream being written to
+        See the Rich documentation for more details on emoji codes, markup tags, and highlighting.
+
+        !!! note
+
+            To ensure consistent behavior, this method requires a file-like object or
+            an instance of ``Cmd2BaseConsole``.
+            Consoles not derived from ``Cmd2BaseConsole`` are disallowed because:
+
+            1. **Style Control**: They ignore the global ``ALLOW_STYLE`` setting.
+            2. **Theming**: They do not respect the application-wide ``APP_THEME``.
+            3. **Error Handling**: They trigger a ``SystemExit`` on broken pipes.
+               ``Cmd2BaseConsole`` instead raises a catchable ``BrokenPipeError``,
+               ensuring the CLI application remains alive if a pipe is closed.
+
+        :param destination: The output target. File-like objects are automatically
+                            wrapped in a ``Cmd2GeneralConsole`` to ensure they respect
+                            cmd2 global settings; otherwise, this must be an
+                            instance of ``Cmd2BaseConsole``.
         :param objects: objects to print
         :param sep: string to write between printed text. Defaults to " ".
         :param end: string to write at end of printed text. Defaults to a newline.
@@ -1290,13 +1312,28 @@ def print_to(
         :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().
-
-        See the Rich documentation for more details on emoji codes, markup tags, and highlighting.
+        :raises TypeError: If ``destination`` is a non-cmd2 ``Console`` instance that
+                           does not derive from ``Cmd2BaseConsole``.
         """
+        if isinstance(destination, Console):
+            if not isinstance(destination, Cmd2BaseConsole):
+                # Explicitly reject non-cmd2 consoles to ensure safe behavior
+                raise TypeError(
+                    f"destination must be a 'Cmd2BaseConsole' or a file-like object, "
+                    f"not a non-cmd2 '{type(destination).__name__}'. "
+                    "Consoles not derived from 'Cmd2BaseConsole' bypass cmd2's "
+                    "'ALLOW_STYLE' logic, 'APP_THEME' settings, and trigger 'SystemExit' "
+                    "on broken pipes."
+                )
+            console = destination
+        else:
+            # It's a file-like object (e.g., sys.stdout, StringIO)
+            console = Cmd2GeneralConsole(destination)
+
         prepared_objects = ru.prepare_objects_for_rendering(*objects)
 
         try:
-            Cmd2GeneralConsole(file).print(
+            console.print(
                 *prepared_objects,
                 sep=sep,
                 end=end,
@@ -1313,7 +1350,7 @@ def print_to(
             # writing. If you would like your application to print a
             # warning message, then set the broken_pipe_warning attribute
             # to the message you want printed.
-            if self.broken_pipe_warning and file != sys.stderr:
+            if self.broken_pipe_warning and console.file != sys.stderr:
                 Cmd2GeneralConsole(sys.stderr).print(self.broken_pipe_warning)
 
     def poutput(
@@ -1581,17 +1618,16 @@ def ppaged(
 
         # Check if we are outputting to a pager.
         if functional_terminal and can_block:
-            prepared_objects = ru.prepare_objects_for_rendering(*objects)
-
             # Chopping overrides soft_wrap
             if chop:
                 soft_wrap = True
 
             # Generate the bytes to send to the pager
             console = Cmd2GeneralConsole(self.stdout)
             with console.capture() as capture:
-                console.print(
-                    *prepared_objects,
+                self.print_to(
+                    console,
+                    *objects,
                     sep=sep,
                     end=end,
                     style=style,

tests/test_cmd2.py

@@ -6,9 +6,7 @@
 import signal
 import sys
 import tempfile
-from code import (
-    InteractiveConsole,
-)
+from code import InteractiveConsole
 from typing import NoReturn
 from unittest import mock
 
@@ -2130,6 +2128,22 @@ def test_read_command_line_eof(base_app, monkeypatch) -> None:
     assert line == 'eof'
 
 
+def test_print_to_custom_console(base_app) -> None:
+    console = ru.Cmd2GeneralConsole()
+    with console.capture() as capture:
+        base_app.print_to(console, "hello")
+    assert capture.get() == "hello\n"
+
+
+def test_print_to_invalid_console_type(base_app) -> None:
+    from rich.console import Console
+
+    console = Console()
+    with pytest.raises(TypeError) as excinfo:
+        base_app.print_to(console, "hello")
+    assert "destination must be a 'Cmd2BaseConsole'" in str(excinfo.value)
+
+
 def test_poutput_string(outsim_app) -> None:
     msg = 'This is a test'
     outsim_app.poutput(msg)