run/keys/core/boxes: Allow editing message content via external editors.

A new OPEN_EXTERNAL_EDITOR command (hotkey: Ctrl o) may now open an
external editor, if details of one are provided, to allow message
content to be edited outside of the application, during message compose
or editing.

The external editor may be specified by, in order of increasing
precedence:
- the semi-standard EDITOR environment variable
- a ZULIP_EDIT_COMMAND environment variable
- a new 'editor' key in the zuliprc file

ZULIP_EDIT_COMMAND is added to allow a custom form of EDITOR to be used,
ie. to avoid causing issues with other tools that may depend upon the
latter.

The command is validated as being set and the path to it as existing,
with errors reported to the user.

The feature then operates via a randomly-named temporary file,
initialized with any existing message content, which is opened by the
application with the editor. The application pauses at this point, until
the editing is complete, when the content is substituted back into the
compose content area, and the application resumes.

README updated to document new zuliprc option.
hotkeys automaically updated for new command.

Tests updated.

Additional defensive approaches and textual changes made by neiljp.

Author: mek-yt

README.md

@@ -251,6 +251,10 @@ color-depth=256
 ## This is highly dependent on a suitable terminal emulator, and support in the selected theme
 ## Terminal emulators without this feature may show an arbitrary solid background color
 transparency=disabled
+
+## Editor: set external editor command, to edit message content
+## If not set, this falls back to the $ZULIP_EDITOR_COMMAND then $EDITOR environment variables
+# editor: nano
 ```
 
 > **NOTE:** Most of these configuration settings may be specified on the

docs/hotkeys.md

@@ -97,6 +97,7 @@
 |Cycle through autocomplete suggestions in reverse|<kbd>Ctrl</kbd> + <kbd>r</kbd>|
 |Exit message compose box|<kbd>Esc</kbd>|
 |Insert new line|<kbd>Enter</kbd>|
+|Open an external editor to edit the message content|<kbd>Ctrl</kbd> + <kbd>o</kbd>|
 
 ## Editor: Navigation
 |Command|Key Combination|

tests/cli/test_run.py

@@ -27,6 +27,8 @@
 MODULE = "zulipterminal.cli.run"
 CONTROLLER = MODULE + ".Controller"
 
+os.environ["ZULIP_EDITOR_COMMAND"] = ""
+
 
 @pytest.mark.parametrize(
     "color, code",
@@ -206,6 +208,7 @@ def test_valid_zuliprc_but_no_connection(
         "   color depth setting '256' specified from default config.",
         "   notify setting 'disabled' specified from default config.",
         "   transparency setting 'disabled' specified from default config.",
+        "   external editor command '' specified from environment.",
         "\x1b[91m",
         f"Error connecting to Zulip server: {server_connection_error}.\x1b[0m",
     ]
@@ -266,6 +269,7 @@ def test_warning_regarding_incomplete_theme(
         "   color depth setting '256' specified from default config.",
         "   notify setting 'disabled' specified from default config.",
         "   transparency setting 'disabled' specified from default config.",
+        "   external editor command '' specified from environment.",
         "\x1b[91m",
         f"Error connecting to Zulip server: {server_connection_error}.\x1b[0m",
     ]
@@ -486,6 +490,7 @@ def test_successful_main_function_with_config(
         "   color depth setting '256' specified in zuliprc file.",
         "   notify setting 'enabled' specified in zuliprc file.",
         "   transparency setting 'disabled' specified from default config.",
+        "   external editor command '' specified from environment.",
     ]
     assert lines == expected_lines
 

tests/core/test_core.py

@@ -61,6 +61,7 @@ def controller(self, mocker: MockerFixture) -> Controller:
             color_depth=256,
             in_explore_mode=self.in_explore_mode,
             debug_path=None,
+            editor_command="",
             **dict(
                 autohide=self.autohide,
                 notify=self.notify_enabled,

zulipterminal/cli/run.py

@@ -33,6 +33,7 @@
 class ConfigSource(Enum):
     DEFAULT = "from default config"
     ZULIPRC = "in zuliprc file"
+    ENV = "from environment"
     COMMANDLINE = "on command line"
 
 
@@ -82,6 +83,7 @@ class SettingData(NamedTuple):
     "maximum-footlinks": "3",
     "exit_confirmation": "enabled",
     "transparency": "disabled",
+    "editor": "",
 }
 assert DEFAULT_SETTINGS["autohide"] in VALID_BOOLEAN_SETTINGS["autohide"]
 assert DEFAULT_SETTINGS["notify"] in VALID_BOOLEAN_SETTINGS["notify"]
@@ -579,6 +581,21 @@ def print_setting(setting: str, data: SettingData, suffix: str = "") -> None:
         print_setting("notify setting", zterm["notify"])
         print_setting("transparency setting", zterm["transparency"])
 
+        if zterm["editor"].source == ConfigSource.ZULIPRC:
+            editor_command = zterm["editor"].value
+            editor_config_source = ConfigSource.ZULIPRC
+        else:
+            editor_command = os.environ.get(
+                "ZULIP_EDITOR_COMMAND",
+                os.environ.get("EDITOR", ""),
+            )
+            editor_config_source = ConfigSource.ENV
+
+        print_setting(
+            "external editor command",
+            SettingData(editor_command, editor_config_source),
+        )
+
         ### Generate data not output to user, but into Controller
         # Translate valid strings for boolean values into True/False
         boolean_settings: Dict[str, bool] = dict()
@@ -605,6 +622,7 @@ def print_setting(setting: str, data: SettingData, suffix: str = "") -> None:
             in_explore_mode=args.explore,
             **boolean_settings,
             debug_path=debug_path,
+            editor_command=editor_command,
         ).main()
     except ServerConnectionFailure as e:
         # Acts as separator between logs

zulipterminal/config/keys.py

@@ -428,6 +428,11 @@ class KeyBinding(TypedDict):
         'help_text': 'Insert new line',
         'key_category': 'compose_box',
     },
+    'OPEN_EXTERNAL_EDITOR': {
+        'keys': ['ctrl o'],
+        'help_text': 'Open an external editor to edit the message content',
+        'key_category': 'compose_box',
+    },
     'FULL_RENDERED_MESSAGE': {
         'keys': ['f'],
         'help_text': 'Show/hide full rendered message (from message information)',

zulipterminal/core.py

@@ -69,6 +69,7 @@ def __init__(
         theme: ThemeSpec,
         color_depth: int,
         debug_path: Optional[str],
+        editor_command: str,
         in_explore_mode: bool,
         transparency: bool,
         autohide: bool,
@@ -84,6 +85,7 @@ def __init__(
         self.exit_confirmation = exit_confirmation
         self.notify_enabled = notify
         self.maximum_footlinks = maximum_footlinks
+        self.editor_command = editor_command
 
         self.debug_path = debug_path
 

zulipterminal/ui_tools/boxes.py

@@ -3,9 +3,13 @@
 """
 
 import re
+import shlex
+import shutil
+import subprocess
 import unicodedata
 from collections import Counter
 from datetime import datetime, timedelta
+from tempfile import NamedTemporaryFile
 from time import sleep
 from typing import Any, Callable, Dict, List, NamedTuple, Optional, Tuple
 
@@ -839,6 +843,47 @@ def keypress(self, size: urwid_Size, key: str) -> Optional[str]:
         elif is_command_key("MARKDOWN_HELP", key):
             self.view.controller.show_markdown_help()
             return key
+        elif is_command_key("OPEN_EXTERNAL_EDITOR", key):
+            editor_command = self.view.controller.editor_command
+
+            # None would indicate for shlex.split to read sys.stdin for Python < 3.12
+            # It should never occur in practice
+            assert isinstance(editor_command, str)
+
+            if editor_command == "":
+                self.view.controller.report_error(
+                    "No external editor command specified; "
+                    "Set 'editor' in zuliprc file, or "
+                    "$ZULIP_EDITOR_COMMAND or $EDITOR environment variables."
+                )
+                return key
+
+            editor_command_line: List[str] = shlex.split(editor_command)
+            if not editor_command_line:
+                fullpath_program = None  # A command may be specified, but empty
+            else:
+                fullpath_program = shutil.which(editor_command_line[0])
+            if fullpath_program is None:
+                self.view.controller.report_error(
+                    "External editor command not found; "
+                    "Check your zuliprc file, $EDITOR or $ZULIP_EDITOR_COMMAND."
+                )
+                return key
+            editor_command_line[0] = fullpath_program
+
+            with NamedTemporaryFile(suffix=".md") as edit_tempfile:
+                with open(edit_tempfile.name, mode="w") as edit_writer:
+                    edit_writer.write(self.msg_write_box.edit_text)
+                self.view.controller.loop.screen.stop()
+
+                editor_command_line.append(edit_tempfile.name)
+                subprocess.call(editor_command_line)
+
+                with open(edit_tempfile.name, mode="r") as edit_reader:
+                    self.msg_write_box.edit_text = edit_reader.read().rstrip()
+            self.view.controller.loop.screen.start()
+            return key
+
         elif is_command_key("SAVE_AS_DRAFT", key):
             if self.msg_edit_state is None:
                 if self.compose_box_status == "open_with_private":