Uploaded image for project: 'Request For Comments'
  1. Request For Comments
  2. RFC-649

Allow formatting python code with "black"

    Details

    • Type: RFC
    • Status: Withdrawn
    • Resolution: Done
    • Component/s: DM
    • Labels:
      None
    • Location:
      This ticket

      Description

      A good automatic code formatter has the potential to save a lot of developer time vs. hand formatting, testing with a validator, and learning to read different user's styles.

      The "black" formatter https://black.readthedocs.io/en/stable/ seems to do a very nice job with Python code (unlike AutoPep8) and the results appear to be pep8 complaint. The one major difference I have noticed compared to our standards is that when a statement with binary operators is broken into multiple lines, the binary operator is at the beginning of the new line. flake8 can be configured to support this.

      Note that black is not very configurable. So we don't have to argue about which settings to use.

      This proposal is to allow us to use black to format our code. A future RFC would be needed to require use of black.

      Thanks to Matthew Becker for bring it to my attention.

      As an experiment I used black (with no configuration) to reformat all of the python code in ts_salobj (a fairly large package of pure Python code). I then ran flake8 on it only got two categories of warnings:

      • W503 line break before binary operator. This is expected and reflects an existing standard we would have to change.
      • E203 whitespace before ':'. Black uses [start : end] instead of [start: end] for ranges.

      I made a pull request to show what changed: https://github.com/lsst-ts/ts_salobj/pull/69
      I don't agree with all the changes, but I think the results are quite readable. I think the potential productivity benefits far outweigh any minor formatting annoyances.

        Attachments

          Issue Links

            Activity

              People

              • Assignee:
                rowen Russell Owen
                Reporter:
                rowen Russell Owen
                Watchers:
                Brian Van Klaveren, Jim Bosch, John Parejko, John Swinbank, Jonathan Sick, Krzysztof Findeisen, Leanne Guy, Russell Owen, Tim Jenness
              • Votes:
                0 Vote for this issue
                Watchers:
                9 Start watching this issue

                Dates

                • Created:
                  Updated:
                  Resolved:
                  Planned End:

                  Summary Panel