• 
      

    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)