[GRASS-dev] black: Python code formatter (eg PEP8)

[Panagiotis Mavrogiorgos]

Just few more points (not in any particular order):

- If black is used, all open pull requests, branches etc will need to be
rebased. My guess is that it will often be easier to just re-implement
instead of solving the conflicts.
- Unless black is used on releasebranches too, backporting will not be
trivial and/or automated.
- black uses 88 chars as the default line length. For legacy python this is
usually enough, but for newer code using type annotations you often want to
bump that up to 100 or even 120 chars
- black formats functions/methods with a lot of arguments in a specific way
that may not be to everyone's liking. E.g.

def foo(aaaaaaaaaaaa, bbbbbbbbbbbb, cccccccccccccccc, ddddddddddddddddddd):
>     pass


becomes:

def foo(
>     aaaaaaaaaaaa,
>     bbbbbbbbbbbb,
>     cccccccccccccccc,
>     ddddddddddddddddddd,
> ):
>     pass


bumping up the line length, somewhat's mitigates this.

- black is an automated tool. Optimal results are usually achieved by
manually adjusting the code and/or writing the code in a way that is
compatible with black (i.e. black will not change it). a typical example -
and there are more - are double list comprehensions (which IMHV should
usually be avoided but that's not really relevant here). E.g:

words = [word.upper() for sentence in paragraph for word in sentence]
>

becomes:

words = [
>     word.upper()
>     for sentence in paragraph
>     for word in sentence
> ]


Re-rewriting this as a nested loop is one less line of code, is more
readable because it doesn't change the flow of execution, is more
expendable and is obviously more familiar to those who don't know python
that well:

words = []
> for sentence in paragraph:
>     for word in sentence:
>         words.append(word.upper())


For the record, this particular case could be re-written using
itertools.chain

from itertools import chain


> words = [word.upper() for word in chain(*paragraph)]


- black doesn't play too well with inline comments. E.g.

a = [
>     "a",
>     "b",  # noqa
>     "c",
> ]


will be transformed to:

a = ["a", "b", "c"]  # noqa


This means that the noqa comment will be applied to all the arguments
instead of "b" only.

- Probably not a huge issue for GRASS, but black does not preserve
indentation of comments. So E.g this will become:

# class A(object):
>     # def __init__(self):
>         # self.a = 1
>         # self.b = 2


 will become

# class A(object):
> # def __init__(self):
> # self.a = 1
> # self.b = 2


If you want to preserve the indentation you would need to comment out using
this:

# class A(object):
> #    def __init__(self):
> #        self.a = 1
> #        self.b = 2


all the best,
P.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/grass-dev/attachments/20190603/b3831ca5/attachment.html>