tui: open log files in external application

* Allow log files to be open in external applications.
* Tui will suspend whilst the external tool is open, and resume once it
  has closed.
* Options implemented are `$EDITOR`, `$GEDITOR`, `$PAGER` and `vim` as a
  backup.

changes.d/6611.feat.md

@@ -0,0 +1 @@
+Tui: Add ability to open log files in external tools. Configure your `$EDITOR`, `$GEDITOR` or `$PAGER` options to configure which tool is used.

cylc/flow/tui/overlay.py

@@ -38,8 +38,10 @@
 """
 
 from functools import partial
+import os
 import re
 import sys
+from time import sleep
 
 import urwid
 
@@ -413,6 +415,8 @@ def log(app, id_=None, list_files=None, get_log=None):
     # display the actual log file itself
     text_widget = urwid.Text('')
 
+    _filename = None
+
     def open_menu(*_args, **_kwargs):
         """Open an overlay for selecting a log file."""
         nonlocal app, id_
@@ -459,7 +463,8 @@ def open_log(*_, filename=None, close=False):
 
         """
 
-        nonlocal host_widget, file_widget, text_widget
+        nonlocal host_widget, file_widget, text_widget, _filename
+        _filename = filename
         try:
             host, path, text = get_log(filename)
         except Exception as exc:
@@ -473,6 +478,67 @@ def open_log(*_, filename=None, close=False):
             if close:
                 app.close_topmost()
 
+    def open_in_editor(*_, command):
+        """Suspend Tui, open the file in an external utility, then restore Tui.
+
+        Args:
+            command:
+                The command to run as a list, e.g. 'gvim -f'.
+                This command must be blocking, the tui session will be
+                restored when the command exits.
+
+        """
+        import shlex
+        from subprocess import Popen
+        import stat
+        import tempfile
+
+        nonlocal _filename
+
+        try:
+            host, path, text = get_log(_filename)
+        except Exception as exc:
+            host_widget.set_text(f'Error: {exc}')
+            file_widget.set_text('')
+        else:
+            host_widget.set_text(f'Host: {host}')
+            file_widget.set_text(f'Path: {path}')
+
+        with tempfile.NamedTemporaryFile('w+') as temp_file:
+            # write the text into a temp file
+            temp_file.write(text)
+            temp_file.seek(0, 0)
+
+            # make the file readonly to avoid confusion
+            os.chmod(temp_file.name, stat.S_IRUSR)
+
+            # suspend Tui
+            app.loop.screen.stop()
+
+            # open the file using the external tool (must be blocking)
+            print('Launching external tool, Tui will resume once it exits.')
+            try:
+                Popen(
+                    [*shlex.split(command), temp_file.name]
+                ).wait()  # nosec B603
+                # (this is running a command the user has configured)
+            except OSError as exc:
+                # ensure any critical errors are visible to the user so
+                # that they have a chance to fix them
+                _sleep_time = 5
+                print(
+                    (
+                        f'Error running {command} {temp_file.name}'
+                        f'\n{exc}'
+                        f'\nTui will resume in {_sleep_time} seconds'
+                    ),
+                    file=sys.stderr
+                )
+                sleep(_sleep_time)
+
+            # restore Tui
+            app.loop.screen.start()
+
     # load the default log file
     if id_:
         # NOTE: the kwargs are not provided in the overlay unit tests
@@ -489,6 +555,25 @@ def open_log(*_, filename=None, close=False):
                 'Select File',
                 on_press=open_menu,
             ),
+            urwid.Columns([
+                ('pack', urwid.Text('Open in:  ')),
+                *(
+                    (
+                        'pack',
+                        urwid.Button(
+                            label,
+                            align='left',
+                            on_press=partial(open_in_editor, command=command),
+                        ),
+                    )
+                    for label, command in (
+                        ('$EDITOR', os.environ.get('EDITOR', 'vim')),
+                        ('$GEDITOR', os.environ.get('GEDITOR', 'gvim -f')),
+                        ('$PAGER', os.environ.get('PAGER', 'less')),
+                        ('vim', 'vim'),
+                    )
+                ),
+            ]),
             urwid.Divider(),
             text_widget,
         ]),

tests/integration/tui/screenshots/test_errors.list-error.html

@@ -2,7 +2,7 @@
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Error: Somethi</span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Error                                       </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">Select File </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Something went wrong :(                     </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">        </span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
-<span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
+<span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Open in:  </span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">$E</span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">              </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>

tests/integration/tui/screenshots/test_errors.open-error.html

@@ -2,7 +2,7 @@
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Error: Something went wrong :(                                            </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5"></span><span style="color:#e5e5e5;background:#000000">S</span><span style="color:#000000;background:#e5e5e5">elect File                                                           </span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
-<span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
+<span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">Open in:  </span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">$EDITOR</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">$GEDITOR</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">$PAGER</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">&lt;</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">vim</span><span style="color:#000000;background:#e5e5e5"> </span><span style="color:#000000;background:#e5e5e5">&gt;</span><span style="color:#000000;background:#e5e5e5">                        </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>
 <span style="color:#000000;background:#e5e5e5">│</span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">                                                                          </span><span style="color:#000000;background:#e5e5e5">  </span><span style="color:#000000;background:#e5e5e5">│</span>