Removed parse_args wrappers and made context manager public.

Author: kmvanbrunt

CHANGELOG.md

@@ -145,6 +145,9 @@ prompt is displayed.
     - 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.
+      This is helpful for redirecting output from functions like `parse_args()`, which default to
+      `sys.stdout` and lack a `file` argument.
 
 ## 3.5.1 (April 24, 2026)
 

cmd2/argparse_utils.py

@@ -557,7 +557,7 @@ class _ParserThreadLocals(threading.local):
     # 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
-    # _set_output_file() context manager.
+    # output_to() context manager.
     current_output_file: IO[str] | None = None
 
 
@@ -568,8 +568,14 @@ class Cmd2ArgumentParser(argparse.ArgumentParser):
     _thread_locals: ClassVar[_ParserThreadLocals] = _ParserThreadLocals()
 
     @contextlib.contextmanager
-    def _set_output_file(self, file: IO[str] | None) -> Iterator[None]:
-        """Context manager to temporarily set the current output file."""
+    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 redirecting output from 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:
@@ -635,58 +641,20 @@ def __init__(
         self.description: HelpContent | None  # type: ignore[assignment]
         self.epilog: HelpContent | None  # type: ignore[assignment]
 
-    def parse_args_custom_stdout(
-        self,
-        stdout: IO[str],
-        args: list[str] | None = None,
-        namespace: argparse.Namespace | None = None,
-    ) -> argparse.Namespace:
-        """Parse arguments while directing help and usage output to a custom stdout stream.
-
-        This method is particularly useful when you need to capture help output without
-        globally redirecting sys.stdout.
-
-        :param stdout: the stream to use for help and usage output
-        :param args: optional list of arguments to parse. If None, uses sys.argv[1:].
-        :param namespace: optional namespace to populate. If None, a new Namespace is created.
-        :return: the parsed namespace
-        """
-        with self._set_output_file(stdout):
-            return self.parse_args(args, namespace)
-
-    def parse_known_args_custom_stdout(
-        self,
-        stdout: IO[str],
-        args: list[str] | None = None,
-        namespace: argparse.Namespace | None = None,
-    ) -> tuple[argparse.Namespace, list[str]]:
-        """Parse known arguments while directing help and usage output to a custom stdout stream.
-
-        This method is particularly useful when you need to capture help output without
-        globally redirecting sys.stdout.
-
-        :param stdout: the stream to use for help and usage output
-        :param args: optional list of arguments to parse. If None, uses sys.argv[1:].
-        :param namespace: optional namespace to populate. If None, a new Namespace is created.
-        :return: a tuple containing the parsed namespace and a list of unknown arguments
-        """
-        with self._set_output_file(stdout):
-            return self.parse_known_args(args, namespace)
-
     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
 
-        with self._set_output_file(file):
+        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._set_output_file(file):
+        with self.output_to(file):
             super().print_help(file)
 
     def get_subparsers_action(self) -> "argparse._SubParsersAction[Cmd2ArgumentParser]":
@@ -891,7 +859,7 @@ def error(self, message: str) -> NoReturn:
             else:
                 formatted_message += "\n       " + line
 
-        with self._set_output_file(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.

cmd2/decorators.py

@@ -303,20 +303,11 @@ def cmd_wrapper(*args: Any, **kwargs: Any) -> bool | None:
 
             try:
                 parsing_results: tuple[argparse.Namespace] | tuple[argparse.Namespace, list[str]]
-                if with_unknown_args:
-                    parsing_results = arg_parser.parse_known_args_custom_stdout(
-                        cmd2_app.stdout,
-                        command_arg_list,
-                        initial_namespace,
-                    )
-                else:
-                    parsing_results = (
-                        arg_parser.parse_args_custom_stdout(
-                            cmd2_app.stdout,
-                            command_arg_list,
-                            initial_namespace,
-                        ),
-                    )
+                with arg_parser.output_to(cmd2_app.stdout):
+                    if with_unknown_args:
+                        parsing_results = arg_parser.parse_known_args(command_arg_list, initial_namespace)
+                    else:
+                        parsing_results = (arg_parser.parse_args(command_arg_list, initial_namespace),)
             except SystemExit as exc:
                 raise Cmd2ArgparseError from exc
 

tests/test_argparse_utils.py

@@ -620,8 +620,8 @@ def test_update_prog() -> None:
             assert action.choices["alias1"].prog == sub1.prog
 
 
-def test_parser_set_output_file_context_manager() -> None:
-    """Test that _set_output_file correctly shadows and restores current_output_file."""
+def test_parser_output_to_context_manager() -> None:
+    """Test that output_to() correctly shadows and restores current_output_file."""
     import io
 
     parser = Cmd2ArgumentParser()
@@ -630,9 +630,9 @@ def test_parser_set_output_file_context_manager() -> None:
 
     assert parser._thread_locals.current_output_file is None
 
-    with parser._set_output_file(buf1):
+    with parser.output_to(buf1):
         assert parser._thread_locals.current_output_file is buf1
-        with parser._set_output_file(buf2):  # type: ignore[unreachable]
+        with parser.output_to(buf2):  # type: ignore[unreachable]
             assert parser._thread_locals.current_output_file is buf2
         assert parser._thread_locals.current_output_file is buf1
 
@@ -699,26 +699,6 @@ def test_parser_error_redirection(mocker: MockerFixture) -> None:
     assert kwargs["style"] == argparse_utils.Cmd2Style.ERROR
 
 
-def test_parser_custom_stdout_methods(mocker: MockerFixture) -> None:
-    """Test parse_args_custom_stdout() and parse_known_args_custom_stdout()."""
-    import io
-
-    parser = Cmd2ArgumentParser()
-    buf = io.StringIO()
-
-    # Mock parse_args and parse_known_args
-    mock_parse = mocker.patch.object(parser, "parse_args")
-    mock_parse_known = mocker.patch.object(parser, "parse_known_args")
-
-    parser.parse_args_custom_stdout(buf, ["arg"])
-    assert parser._thread_locals.current_output_file is None
-    mock_parse.assert_called_once_with(["arg"], None)
-
-    parser.parse_known_args_custom_stdout(buf, ["arg"])
-    assert parser._thread_locals.current_output_file is None
-    mock_parse_known.assert_called_once_with(["arg"], None)
-
-
 def test_parser_implicit_output_redirection(mocker: MockerFixture) -> None:
     """Test that print_help() and print_usage() use thread-local context when no file is provided."""
     import io
@@ -731,7 +711,7 @@ def test_parser_implicit_output_redirection(mocker: MockerFixture) -> None:
     mock_formatter_class.return_value.format_help.return_value = "Help/Usage Text"
 
     # Shadow the output file
-    with parser._set_output_file(buf):
+    with parser.output_to(buf):
         # Call print_help without a file argument
         parser.print_help()
         # Verify Cmd2HelpFormatter was instantiated with file=buf (from thread-local)