Add documentation for allow_clipboard attribute

4 files changed, 42 insertions, 17 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c7d52a49..587237b4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,8 @@
+## 2.5.0 (TBD)
+* Enhancements
+  * add `allow_clipboard` initialization parameter and attribute to disable ability to
+    add output to the operating system clipboard
+
 ## 2.4.3 (January 27, 2023)
 * Bug Fixes
   * Fixed ValueError caused when passing `Cmd.columnize()` strings wider than `display_width`.
@@ -84,7 +89,7 @@
   * Added `ap_completer_type` keyword arg to `Cmd2ArgumentParser.__init__()` which saves a call
     to `set_ap_completer_type()`. This keyword will also work with `add_parser()` when creating subcommands
     if the base command's parser is a `Cmd2ArgumentParser`.
-  * New function `register_argparse_argument_parameter()` allows developers to specify custom 
+  * New function `register_argparse_argument_parameter()` allows developers to specify custom
     parameters to be passed to the argparse parser's `add_argument()` method. These parameters will
     become accessible in the resulting argparse Action object when modifying `ArgparseCompleter` behavior.
   * Using `SimpleTable` in the output for the following commands to improve appearance.
@@ -257,12 +262,12 @@
 
 ## 1.3.7 (August 27, 2020)
 * Bug Fixes
-    * Fixes an issue introduced in 1.3.0 with processing command strings containing terminator/separator 
+    * Fixes an issue introduced in 1.3.0 with processing command strings containing terminator/separator
       character(s) that are manually passed to a command that uses argparse.
 
 ## 1.3.6 (August 27, 2020)
 * Breaking changes
-    * The functions cmd2 adds to Namespaces (`get_statement()` and `get_handler()`) are now 
+    * The functions cmd2 adds to Namespaces (`get_statement()` and `get_handler()`) are now
     `Cmd2AttributeWrapper` objects named `cmd2_statement` and `cmd2_handler`. This makes it
     easy to filter out which attributes in an `argparse.Namespace` were added by `cmd2`.
 * Deprecations
@@ -288,7 +293,7 @@
 * Breaking changes
     * CommandSet command functions (do_, complete_, help_) will no longer have the cmd2 app
       passed in as the first parameter after `self` since this is already a class member.
-    * Renamed `install_command_set()` and `uninstall_command_set()` to `register_command_set()` and 
+    * Renamed `install_command_set()` and `uninstall_command_set()` to `register_command_set()` and
       `unregister_command_set()` for better name consistency.
 * Bug Fixes
     * Fixed help formatting bug in `Cmd2ArgumentParser` when `metavar` is a tuple
@@ -298,8 +303,8 @@
     * Removed explicit type hints that fail due to a bug in 3.5.2 favoring comment-based hints instead
     * When passing a ns_provider to an argparse command, will now attempt to resolve the correct
       CommandSet instance for self. If not, it'll fall back and pass in the cmd2 app
-* Other 
-    * Added missing doc-string for new cmd2.Cmd __init__ parameters 
+* Other
+    * Added missing doc-string for new cmd2.Cmd __init__ parameters
       introduced by CommandSet enhancement
 
 ## 1.3.2 (August 10, 2020)
@@ -314,8 +319,8 @@
 ## 1.3.1 (August 6, 2020)
 * Bug Fixes
     * Fixed issue determining whether an argparse completer function required a reference to a containing
-      CommandSet. Also resolves issues determining the correct CommandSet instance when calling the argparse 
-      argument completer function.  Manifested as a TypeError when using `cmd2.Cmd.path_complete` as a completer 
+      CommandSet. Also resolves issues determining the correct CommandSet instance when calling the argparse
+      argument completer function.  Manifested as a TypeError when using `cmd2.Cmd.path_complete` as a completer
       for an argparse-based command defined in a CommandSet
 
 ## 1.3.0 (August 4, 2020)
@@ -324,7 +329,7 @@
       with your cmd2 application.
 * Other
     * Marked with_argparser_and_unknown_args pending deprecation and consolidated implementation into
-      with_argparser 
+      with_argparser
 
 ## 1.2.1 (July 14, 2020)
 * Bug Fixes
@@ -332,7 +337,7 @@
 
 ## 1.2.0 (July 13, 2020)
 * Bug Fixes
-    * Fixed `typing` module compatibility issue with Python 3.5 prior to 3.5.4 
+    * Fixed `typing` module compatibility issue with Python 3.5 prior to 3.5.4
 * Enhancements
     * Switched to getting version using `importlib.metadata` instead of using `pkg_resources`
         * Improves `cmd2` application launch time on systems that have a lot of Python packages on `sys.path`
@@ -341,7 +346,7 @@
 ## 1.1.0 (June 6, 2020)
 * Bug Fixes
     * Fixed issue where subcommand usage text could contain a subcommand alias instead of the actual name
-    * Fixed bug in `ArgparseCompleter` where `fill_width` could become negative if `token_width` was large 
+    * Fixed bug in `ArgparseCompleter` where `fill_width` could become negative if `token_width` was large
       relative to the terminal width.
 * Enhancements
     * Made `ipy` consistent with `py` in the following ways
@@ -365,7 +370,7 @@
           after parsing fails, just return instead of raising an exception.
     * Added explicit handling of `SystemExit`. If a command raises this exception, the command loop will be
       gracefully stopped.
-    
+
 ## 1.0.2 (April 06, 2020)
 * Bug Fixes
     * Ctrl-C now stops a running text script instead of just the current `run_script` command
@@ -388,9 +393,9 @@
 * Bug Fixes
     * Corrected issue where the actual new value was not always being printed in do_set. This occurred in cases where
       the typed value differed from what the setter had converted it to.
-    * Fixed bug where ANSI style sequences were not correctly handled in `utils.truncate_line()`. 
+    * Fixed bug where ANSI style sequences were not correctly handled in `utils.truncate_line()`.
     * Fixed bug where pyscripts could edit `cmd2.Cmd.py_locals` dictionary.
-    * Fixed bug where cmd2 set `sys.path[0]` for a pyscript to cmd2's working directory instead of the 
+    * Fixed bug where cmd2 set `sys.path[0]` for a pyscript to cmd2's working directory instead of the
     script file's directory.
     * Fixed bug where `sys.path` was not being restored after a pyscript ran.
 * Enhancements
diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst
index 6fdfbf27..f9bd07c6 100644
--- a/docs/api/cmd.rst
+++ b/docs/api/cmd.rst
@@ -65,3 +65,10 @@ cmd2.Cmd
         The symbol name which :ref:`features/scripting:Python Scripts` run
         using the :ref:`features/builtin_commands:run_pyscript` command can use
         to reference the parent ``cmd2`` application.
+
+    .. attribute:: allow_clipboard
+
+        If ``True``, ``cmd2`` will allow output to be written to or appended to
+        the operating system pasteboard. If ``False``, this capability will not
+        be allowed. See :ref:`features/clipboard:Clipboard Integration` for more
+        information.
diff --git a/docs/features/clipboard.rst b/docs/features/clipboard.rst
index 73e206c2..a4b9cdf2 100644
--- a/docs/features/clipboard.rst
+++ b/docs/features/clipboard.rst
@@ -25,6 +25,14 @@ contents of the clipboard by ending the command with two greater than symbols:
 Developers
 ----------
 
+You can control whether the above user features of adding output to the
+operating system clipboard are allowed for the user by setting the
+:attr:`~cmd2.Cmd.allow_clipboard` attribute. The default value is ``True``.
+Set it to ``False`` and the above functionality will generate an error
+message instead of adding the output to the clipboard.
+:attr:`~cmd2.Cmd.allow_clipboard` can be set upon initialization, and you can
+change it at any time from within your code.
+
 If you would like your ``cmd2`` based application to be able to use the
 clipboard in additional or alternative ways, you can use the following methods
 (which work uniformly on Windows, macOS, and Linux).
diff --git a/tests/test_cmd2.py b/tests/test_cmd2.py
index 859f035a..2270a907 100755
--- a/tests/test_cmd2.py
+++ b/tests/test_cmd2.py
@@ -171,9 +171,9 @@ now: True
     out, err = run_cmd(base_app, 'set quiet')
     expected = normalize(
         """
-Name   Value                           Description                                                 
+Name   Value                           Description
 ===================================================================================================
-quiet  True                            Don't print nonessential feedback                           
+quiet  True                            Don't print nonessential feedback
 """
     )
     assert out == expected
@@ -729,6 +729,7 @@ def test_pipe_to_shell_error(base_app):
     assert not out
     assert "Pipe process exited with code" in err[0]
 
+
 try:
     # try getting the contents of the clipboard
     _ = clipboard.get_paste_buffer()
@@ -742,7 +743,8 @@ except Exception:
 else:
     can_paste = True
 
-@pytest.mark.skipif(can_paste, reason="Pyperclip could not find a copy/paste mechanism for your system")
+
+@pytest.mark.skipif(not can_paste, reason="Pyperclip could not find a copy/paste mechanism for your system")
 def test_send_to_paste_buffer(base_app):
     # Test writing to the PasteBuffer/Clipboard
     run_cmd(base_app, 'help >')
@@ -755,6 +757,7 @@ def test_send_to_paste_buffer(base_app):
     assert appended_contents.startswith(paste_contents)
     assert len(appended_contents) > len(paste_contents)
 
+
 def test_get_paste_buffer_exception(base_app, mocker, capsys):
     # Force get_paste_buffer to throw an exception
     pastemock = mocker.patch('pyperclip.paste')
@@ -769,11 +772,13 @@ def test_get_paste_buffer_exception(base_app, mocker, capsys):
     # this just checks that cmd2 is surfacing whatever error gets raised by pyperclip.paste
     assert 'ValueError' in err and 'foo' in err
 
+
 def test_allow_clipboard_initializer(base_app):
     assert base_app.allow_clipboard == True
     noclipcmd = cmd2.Cmd(allow_clipboard=False)
     assert noclipcmd.allow_clipboard == False
 
+
 # if clipboard access is not allowed, cmd2 should check that first
 # before it tries to do anything with pyperclip, that's why we can
 # safely run this test without skipping it if pyperclip doesn't