Improve the capabilities for launching editors for text.

Review Request #10668 — Created Aug. 28, 2019 and submitted

Information

RBTools
release-1.0.x
216db50...

Reviewers

RBTools sometimes needs to invoke editors (to create commit messages,
for instance). The code we had before failed on Python 3, due to string
type mismatches when reading in the resulting edited file content, but
even with that fixed, the editing experience was error-prone and far
from ideal.

For instance, if things went wrong during edit_text(), we'd get some
generic exception, like OSError. We now have a dedicated error for
editing-related failures, EditorError.

Another limitation was that we had no control over the filename of the
edited file. This meant we couldn't influence the editor -- no syntax
highlighting or other editor settings would apply, creating a subpar
experience. This is currently most important for editing commit
messages.

To address this, we needed to provide a filename during the editing
process, but it wasn't as simple as just a standard filename. We needed
to support two different ways of doing this: The Git way (using a fixed
filename for the file), and the Mercurial way (using a generated temp
filename with a prefix and a suffix).

edit_text() has been updated to make the Git approach easier. It now
takes a filename, which will be passed to make_tempfile() to generate
a specific filename for the content. It will also immediately delete
that file once it's been read back in, just to keep the filesystem a bit
more tidy.

To support the Mercurial approach, a new method was added:
edit_file(). This contains the core logic of edit_text(), but
operates on an existing filename. This means that for more advanced
cases, like with Mercurial commit messages, we can generate a commit
filename elsewhere and then pass it to edit_file().

These new editing capabilities have one additional benefit: The
configured editor can now be specified as RBTOOLS_EDITOR, letting us
define an editor that isn't dependent on the VISUAL or EDITOR
environment variables. This is mostly useful for testing for now, but
can be useful if someone wants an explicit editor to be used for RBTools
(or a wrapper script that processes text in some way).

A dummy editor has been added inside rbtools/testing/scripts/ for
testing purposes, allowing us to have full test coverage of these
methods. It simply uppercases the whole file.

Unit tests pass.

Manually tested the new editor errors and capabilities alongside an
upcoming change to leverage all this in Git.

Description From Last Updated

Docstring?

daviddavid

This doesn't need to be split across lines.

daviddavid

Don't keys in os.environ have to be bytestrings?

daviddavid

E202 whitespace before ')'

reviewbotreviewbot

should be str('RBTOOLS_EDITOR') and str(self.default_text_editor)

daviddavid

Do we need to force_unicode(editor)?

daviddavid
david
  1. 
      
  2. rbtools/testing/testcase.py (Diff revision 1)
     
     
    Show all issues

    Docstring?

    1. We never do that for setUp() or tearDown() in unit tests. Doesn't buy us anything.

  3. rbtools/utils/console.py (Diff revision 1)
     
     
     
    Show all issues

    This doesn't need to be split across lines.

    1. Just reads a bit better, makes the arguments more clear, but less necessary since I got rid of prefix= and suffix= there.

  4. rbtools/utils/tests.py (Diff revision 1)
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     
    Show all issues

    Don't keys in os.environ have to be bytestrings?

    1. Yeah, let me fix that.

  5. 
      
chipx86
Review request changed
Change Summary:
  • Consolidated two lines into one.
  • Switched to native strings for os.environ access.
Commit:
2d5685deb26fd82cce43150a6bdb053bd433d57c
b062840d650a0620995afd865f7f00de72bf1f1c

Checks run (1 failed, 1 succeeded)

flake8 failed.
JSHint passed.

flake8

chipx86
david
  1. Ship It!

  2. 
      
david
  1. 
      
  2. rbtools/testing/testcase.py (Diff revision 3)
     
     
    Show all issues

    should be str('RBTOOLS_EDITOR') and str(self.default_text_editor)

  3. rbtools/utils/console.py (Diff revision 3)
     
     
    Show all issues

    Do we need to force_unicode(editor)?

  4. 
      
chipx86
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to release-1.0.x (001c8b3)