[Clipboard] Check clipboard on init a provide property. Also add unit tests and Changelog entry.

Author: neoniobium

CHANGELOG.md

@@ -4,6 +4,8 @@
     - `@with_annotated` argument groups can now contain an `ArgumentBlock`'s arguments. A `Group`
       member names a command-line argument, and a block expands into one argument per field, so its
       fields are named: `Group("host", "port")`.
+    - `Cmd` now uses the `pyperclip` clipboard integration from `prompt_toolkit` as the default
+      clipboard if available and provides it as a property.
 - Breaking Changes
     - A `Group` member now names an argument rather than a parameter. The two differ only for an
       `ArgumentBlock` parameter, which is expanded away and has no argument of its own:

cmd2/cmd2.py

@@ -73,6 +73,7 @@
 )
 from prompt_toolkit.application import create_app_session, get_app
 from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+from prompt_toolkit.clipboard import Clipboard
 from prompt_toolkit.clipboard.pyperclip import PyperclipClipboard
 from prompt_toolkit.completion import Completer, DummyCompleter
 from prompt_toolkit.formatted_text import ANSI, AnyFormattedText
@@ -386,31 +387,32 @@ def __init__(
     ) -> None:
         """Easy but powerful framework for writing line-oriented command interpreters, extends Python's cmd package.
 
-        :param completekey: name of a completion key, default to 'tab'. (If None or an empty string, 'tab' is used)
+        :param completekey: name of a completion key, default to 'tab'. (If ``None`` or an empty string, 'tab' is used)
         :param stdin: alternate input file object, if not specified, sys.stdin is used
         :param stdout: alternate output file object, if not specified, sys.stdout is used
         :param allow_cli_args: if ``True``, then [cmd2.Cmd.__init__][] will process command
                                line arguments as either commands to be run. This should be
                                set to ``False`` if your application parses its own command line
                                arguments.
-        :param allow_clipboard: If False, cmd2 will disable clipboard interactions
+        :param allow_clipboard: If ``False``, cmd2 will disable clipboard interactions
         :param allow_redirection: If ``False``, prevent output redirection and piping to shell
                                   commands. This parameter prevents redirection and piping, but
                                   does not alter parsing behavior. A user can still type
                                   redirection and piping tokens, and they will be parsed as such
                                   but they won't do anything.
-        :param auto_load_commands: If True, cmd2 will check for all subclasses of `CommandSet`
+        :param auto_load_commands: If ``True``, cmd2 will check for all subclasses of `CommandSet`
                                    that are currently loaded by Python and automatically
-                                   instantiate and register all commands. If False, CommandSets
+                                   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
+        :param auto_suggest: If ``True``, cmd2 will provide fish shell style auto-suggestions
                             based on history. User can press right-arrow key to accept the
                             provided suggestion.
         :param complete_in_thread: if ``True``, then completion will run in a separate thread.
         :param command_sets: Provide CommandSet instances to load during cmd2 initialization.
                              This allows CommandSets with custom constructor parameters to be
                              loaded.  This also allows the a set of CommandSets to be provided
-                             when `auto_load_commands` is set to False
+                             when `auto_load_commands` is set to ``False``
+
         :param enable_bottom_toolbar: if ``True``, enables a bottom toolbar while at the main prompt.
                                       Override ``get_bottom_toolbar()`` to define its content.
         :param enable_rprompt: if ``True``, enables a right prompt while at the main prompt.
@@ -429,7 +431,7 @@ def __init__(
                                  updates in the bottom toolbar).
         :param shortcuts: Mapping containing shortcuts for commands. If not supplied,
                           then defaults to constants.DEFAULT_SHORTCUTS. If you do not want
-                          any shortcuts, pass None and an empty dictionary will be created.
+                          any shortcuts, pass ``None`` and an empty dictionary will be created.
         :param silence_startup_script: if ``True``, then the startup script's output will be
                                        suppressed. Anything written to stderr will still display.
         :param startup_script: file path to a script to execute at startup
@@ -440,7 +442,7 @@ def __init__(
                             terminate single-line commands. If not supplied, the default
                             is a semicolon. If your app only contains single-line commands
                             and you want terminators to be treated as literals by the parser,
-                            then set this to None.
+                            then set this to ``None``.
         """
         # Check if py or ipy need to be disabled in this instance
         if not include_py:
@@ -790,9 +792,20 @@ def _(event: Any) -> None:  # pragma: no cover
             "refresh_interval": refresh_interval,
             "rprompt": self.get_rprompt if enable_rprompt else None,
             "style": DynamicStyle(get_pt_theme),
-            "clipboard": PyperclipClipboard(),
         }
 
+        # Only enable PyperclipClipboard if the system clipboard is accessible to Pyperclip.
+        try:
+            cb = PyperclipClipboard()
+            cb.get_data()  # Check if the system clipboard is accessible to Pyperclip
+        except Exception:  # noqa: BLE001, S110
+            # Prevent prompt_toolkit from crashing in headless environments and fallback
+            # on prompt toolkit's default clipboard (InMemoryClipboard) by not providing
+            # any argument for 'clipboard' in kwargs
+            pass
+        else:
+            kwargs["clipboard"] = cb
+
         if self.stdin.isatty() and self.stdout.isatty():
             try:
                 if self.stdin != sys.stdin:
@@ -1487,6 +1500,17 @@ def visible_prompt(self) -> str:
         """
         return su.strip_style(self.prompt)
 
+    @property
+    def clipboard(self) -> Clipboard:
+        """The application clipboard.
+
+        The clipboard the be either a ``PyperclipClipboard`` or an ``InMemoryClipboard``
+        depending on weather the system clipboard is accessible to ``pyperclip``.
+
+        :return: the clipboard of the application's main session
+        """
+        return self.main_session.clipboard
+
     def _get_core_print_console(
         self,
         *,
@@ -3325,12 +3349,9 @@ def _redirect_output(self, statement: Statement) -> utils.RedirectionSavedState:
                 if not self.allow_clipboard:
                     raise RedirectionError("Clipboard access not allowed")
 
-                # attempt to get the paste buffer, this forces pyperclip to go figure
-                # out if it can actually interact with the paste buffer, and will throw exceptions
-                # if it's not gonna work. That way we throw the exception before we go
-                # run the command and queue up all the output. if this is going to fail,
-                # no point opening up the temporary file
-                current_paste_buffer = self.main_session.clipboard.get_data().text
+                # Get the current paste buffer from either the system clipboard if available
+                # or the in-memory clipboard only available to the main session
+                current_paste_buffer = self.clipboard.get_data().text
                 # create a temporary file to store output
                 new_stdout = cast(TextIO, tempfile.TemporaryFile(mode="w+"))  # noqa: SIM115
                 redir_saved_state.redirecting = True
@@ -3360,7 +3381,10 @@ def _restore_output(self, statement: Statement, saved_redir_state: utils.Redirec
                 and not statement.redirect_to
             ):
                 self.stdout.seek(0)
-                self.main_session.clipboard.set_text(self.stdout.read())
+                # Read stdout into the clipboard. Uses the system clipboard if available
+                # otherwise fall back to the in-memory clipboard only available to the main
+                # session
+                self.clipboard.set_text(self.stdout.read())
 
             with contextlib.suppress(BrokenPipeError):
                 # Close the file or pipe that stdout was redirected to

tests/test_cmd2.py

@@ -15,6 +15,8 @@
 import pyperclip  # type: ignore[import-untyped]
 import pytest
 from prompt_toolkit.auto_suggest import AutoSuggestFromHistory
+from prompt_toolkit.clipboard.in_memory import InMemoryClipboard
+from prompt_toolkit.clipboard.pyperclip import PyperclipClipboard
 from prompt_toolkit.completion import DummyCompleter
 from prompt_toolkit.input import DummyInput, create_pipe_input
 from prompt_toolkit.output import DummyOutput
@@ -50,15 +52,6 @@
 )
 
 
-def get_paste_buffer() -> str:
-    """
-    Get the contents of the clipboard / paste buffer. This is just wrapper around
-    pyperclip paste() that provides the correct type annotation.
-
-    """
-    return cast(str, pyperclip.paste())
-
-
 def create_outsim_app():
     c = cmd2.Cmd()
     c.stdout = utils.StdSim(c.stdout)
@@ -882,28 +875,31 @@ def test_pipe_to_shell_error(redirection_app) -> None:
 
 try:
     # try getting the contents of the clipboard
-    _ = get_paste_buffer()
+    _ = pyperclip.paste()
     # pyperclip raises at least the following types of exceptions
     #   FileNotFoundError on Windows Subsystem for Linux (WSL) when Windows paths are removed from $PATH
     #   ValueError for headless Linux systems without Gtk installed
     #   AssertionError can be raised by paste_klipper().
     #   PyperclipException for pyperclip-specific exceptions
 except Exception:  # noqa: BLE001
-    can_paste = False
+    pyperclip_can_paste = False
 else:
-    can_paste = True
+    pyperclip_can_paste = True
 
 
-@pytest.mark.skipif(not can_paste, reason="Pyperclip could not find a copy/paste mechanism for your system")
+@pytest.mark.skipif(not pyperclip_can_paste, reason="Pyperclip could not find a copy/paste mechanism for your system")
 def test_send_to_paste_buffer(redirection_app: RedirectionApp, capsys: pytest.CaptureFixture[str]) -> None:
     # Test writing to the PasteBuffer/Clipboard
     run_cmd(redirection_app, "print_output >")
 
+    # check if the clipboard is a PyperclipClipboard
+    assert isinstance(redirection_app.clipboard, PyperclipClipboard)
+
     # Verify print() went to sys.stdout
     out, _err = capsys.readouterr()
     assert out == "print\n"
 
-    lines = get_paste_buffer().splitlines()
+    lines = redirection_app.clipboard.get_data().text.splitlines()
     assert len(lines) == 1
     assert lines[0] == "poutput"
 
@@ -913,14 +909,45 @@ def test_send_to_paste_buffer(redirection_app: RedirectionApp, capsys: pytest.Ca
     out, _err = capsys.readouterr()
     assert out == "print\n"
 
-    lines = get_paste_buffer().splitlines()
+    lines = redirection_app.clipboard.get_data().text.splitlines()
     assert len(lines) == 2
     assert lines[0] == "poutput"
     assert lines[1] == "poutput"
 
 
+def test_init_with_no_clipboard_allowed() -> None:
+    app = cmd2.Cmd(allow_clipboard=False)
+
+    # Check for the clipboard type
+    if pyperclip_can_paste:
+        assert isinstance(app.clipboard, PyperclipClipboard)
+    else:
+        assert isinstance(app.clipboard, InMemoryClipboard)
+
+
+def test_init_with_clipboard_allowed() -> None:
+    app = cmd2.Cmd(allow_clipboard=True)
+
+    # Check for the clipboard type
+    if pyperclip_can_paste:
+        assert isinstance(app.clipboard, PyperclipClipboard)
+    else:
+        assert isinstance(app.clipboard, InMemoryClipboard)
+
+
+def test_pyperclip_exception_on_init(mocker) -> None:
+    # Force pyperclip.paste to throw an exception
+    pastemock = mocker.patch("pyperclip.paste")
+    pastemock.side_effect = ValueError("foo")
+    app = cmd2.Cmd(allow_clipboard=True)
+
+    # Check if if the clipboard is an InMemoryClipboard when pyperclip cannot access
+    # the system clipboard
+    assert isinstance(app.clipboard, InMemoryClipboard)
+
+
 def test_get_paste_buffer_exception(redirection_app, mocker, capsys) -> None:
-    # Force get_paste_buffer to throw an exception
+    # Force pyperclip.paste to throw an exception which will be
     pastemock = mocker.patch("pyperclip.paste")
     pastemock.side_effect = ValueError("foo")