Moving to Black for Python formatting

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Moving to Black for Python formatting

wenzeslaus
Dear all,

At this moment, we don't use an automatic formatter for Python code and we have only limited enforcement of basic formatting rules. This is changing as we are moving towards PEP8 formatting compliance and automatic Flake8 checks.

We need an automatic formatter and enforcement in the CI. There seems to be a clear candidate for that and that is Black (The uncompromising code formatter) which was already suggested in 2019:


See details about how that applies to GRASS here:


Here is a first PR (ready to be merged) which makes changes to content of scripts and adds a automatic check:


Best,
Vaclav

_______________________________________________
grass-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/grass-dev
Reply | Threaded
Open this post in threaded view
|

Re: Moving to Black for Python formatting

wenzeslaus
Dear all,

Black is now applied to all except for GUI code (that will change hopefully soon). There are few exceptions in place, most notably ctypes. The compliance is checked using Checks in each PR (aka GitHub Actions). The version used is Black 20.8b1. It will be updated as new releases come with possibly small changes to the formatting of the code.

Use the same Black version locally, but if you don't, the worst thing which will happen is that the check will fail and you will need to fix your PR. There is a new file in the root of the repo called pyproject.toml which your local Black and perhaps your editor should pick up currently with settings only for Black. Obviously, the idea is that you just throw Black formatter at your file and don't care about formatting things manually anymore.

A lot happened with Flake8 compiace, but that's mostly irrelevant to Black except that bulk of formatting issues are gone which are now all enabled except line length check and one issue which conflicts with Black. This is accompanied by supporting # % and not just #% in the option parser. Thanks to this and recent Flake8-related fixes by Anna, it is possible to use Flake8 quite effectively to check for problems although a lot of issues still need to be ignored which is configured separately in each major directory containing Python code.

Several non-whitespace changes were included in the Black formatting, namely updates of remaining u-string literals to Python 3 and some trailing comma syntax which now makes Python 3.6 the minimum.

There is also a PR #1391 which will make it easy to ignore these (and other) formatting commits when doing git blame in the command line. The GitHub web interface offers an easy way to move over a revision.

All this applies to core repo, not the grass-addons repo. Ideas and volunteers are welcome.

Best,
Vaclav


On Wed, Feb 17, 2021 at 4:03 PM Vaclav Petras <[hidden email]> wrote:
Dear all,

At this moment, we don't use an automatic formatter for Python code and we have only limited enforcement of basic formatting rules. This is changing as we are moving towards PEP8 formatting compliance and automatic Flake8 checks.

We need an automatic formatter and enforcement in the CI. There seems to be a clear candidate for that and that is Black (The uncompromising code formatter) which was already suggested in 2019:


See details about how that applies to GRASS here:


Here is a first PR (ready to be merged) which makes changes to content of scripts and adds a automatic check:


Best,
Vaclav

_______________________________________________
grass-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/grass-dev
Reply | Threaded
Open this post in threaded view
|

Re: Moving to Black for Python formatting

Luca Delucchi
On Fri, 26 Feb 2021 at 06:00, Vaclav Petras <[hidden email]> wrote:
>
> Dear all,
>

Dear Vaclav,

> Black is now applied to all except for GUI code (that will change hopefully soon). There are few exceptions in place, most notably ctypes. The compliance is checked using Checks in each PR (aka GitHub Actions). The version used is Black 20.8b1. It will be updated as new releases come with possibly small changes to the formatting of the code.
>
> Use the same Black version locally, but if you don't, the worst thing which will happen is that the check will fail and you will need to fix your PR. There is a new file in the root of the repo called pyproject.toml which your local Black and perhaps your editor should pick up currently with settings only for Black. Obviously, the idea is that you just throw Black formatter at your file and don't care about formatting things manually anymore.
>
> A lot happened with Flake8 compiace, but that's mostly irrelevant to Black except that bulk of formatting issues are gone which are now all enabled except line length check and one issue which conflicts with Black. This is accompanied by supporting # % and not just #% in the option parser. Thanks to this and recent Flake8-related fixes by Anna, it is possible to use Flake8 quite effectively to check for problems although a lot of issues still need to be ignored which is configured separately in each major directory containing Python code.
>
> Several non-whitespace changes were included in the Black formatting, namely updates of remaining u-string literals to Python 3 and some trailing comma syntax which now makes Python 3.6 the minimum.
>
> There is also a PR #1391 which will make it easy to ignore these (and other) formatting commits when doing git blame in the command line. The GitHub web interface offers an easy way to move over a revision.
>

thanks a lot for the explanation

> All this applies to core repo, not the grass-addons repo. Ideas and volunteers are welcome.
>

Do you have any suggestions on how to proceed to grass-addons?
Did you just run blake inside a folder or did you do something more?

> Best,
> Vaclav
>

--
ciao
Luca

www.lucadelu.org
_______________________________________________
grass-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/grass-dev
Reply | Threaded
Open this post in threaded view
|

Re: Moving to Black for Python formatting

wenzeslaus


On Fri, Feb 26, 2021 at 7:01 AM Luca Delucchi <[hidden email]> wrote:
On Fri, 26 Feb 2021 at 06:00, Vaclav Petras <[hidden email]> wrote:

> All this applies to core repo, not the grass-addons repo. Ideas and volunteers are welcome.
>

Do you have any suggestions on how to proceed to grass-addons?
Did you just run blake inside a folder or did you do something more?

Here is what I did:

* Applied Black.
* Added pyproject.toml with configuration for Black.
* Modified Flake8 rules.
* Added a Black GitHub workflow.

The application of Black can use some touches here and there. You need to use the same Black version. You may want to modify some lines before and after (I did just things I caught for one reason or another - you cannot review all changes). You may run Flake8 to check for long lines after you applied Black and see if there is something you can resolve. I did separate PRs for different directories, but that was because the codebases are different in each and also a little bit to minimize conflicts with other PRs (these should not be an issue with grass-addons repo). Commit per directory, but then squashing them when merging the PR might be a good approach for grass-addons.

_______________________________________________
grass-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/grass-dev
Reply | Threaded
Open this post in threaded view
|

Re: Moving to Black for Python formatting

wenzeslaus
PR 1527 introduces Black to wxGUI code. Open PRs will likely need to be updated before merging.


On Fri, Feb 26, 2021 at 11:24 PM Vaclav Petras <[hidden email]> wrote:


On Fri, Feb 26, 2021 at 7:01 AM Luca Delucchi <[hidden email]> wrote:
On Fri, 26 Feb 2021 at 06:00, Vaclav Petras <[hidden email]> wrote:

> All this applies to core repo, not the grass-addons repo. Ideas and volunteers are welcome.
>

Do you have any suggestions on how to proceed to grass-addons?
Did you just run blake inside a folder or did you do something more?

Here is what I did:

* Applied Black.
* Added pyproject.toml with configuration for Black.
* Modified Flake8 rules.
* Added a Black GitHub workflow.

The application of Black can use some touches here and there. You need to use the same Black version. You may want to modify some lines before and after (I did just things I caught for one reason or another - you cannot review all changes). You may run Flake8 to check for long lines after you applied Black and see if there is something you can resolve. I did separate PRs for different directories, but that was because the codebases are different in each and also a little bit to minimize conflicts with other PRs (these should not be an issue with grass-addons repo). Commit per directory, but then squashing them when merging the PR might be a good approach for grass-addons.

_______________________________________________
grass-dev mailing list
[hidden email]
https://lists.osgeo.org/mailman/listinfo/grass-dev