add automatic code format enforcer - black #813

gaborbernat · 2018-05-12T11:03:36Z

Black is the uncompromising Python code formatter. By using it, you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters. - https://github.com/ambv/black

obestwalter · 2018-05-12T11:13:22Z

Hi @gaborbernat, are you using this project already somewhere else and can share some experiences with it? A first glimpse over the diff, looks like it is doing a good job. I also think I could get used to that style. Is it stable?

gaborbernat · 2018-05-12T11:21:05Z

Was presented at PyCon lighting talks yesterday. Is marked as stable. I think it has been used internally at FB for a while, having a core Python developer as a creator should be a good enough guarantee.

codecov · 2018-05-12T11:33:52Z

Codecov Report

Merging #813 into master will increase coverage by <1%.
The diff coverage is 93%.

@@          Coverage Diff           @@
##           master   #813    +/-   ##
======================================
+ Coverage      95%    95%   +<1%     
======================================
  Files          11     11            
  Lines        2320   2321     +1     
======================================
+ Hits         2212   2213     +1     
  Misses        108    108

obestwalter · 2018-05-12T12:11:53Z

I can't say I like the style it enforces, especially how parentheses are always on their own lines, but I get the argument that it produces the smallest possible difffs and most of that is a matter of getting used to anyway.

http://black.readthedocs.io/en/stable/installation_and_usage.html#note-this-is-an-early-pre-release

It's marked alpha.

Also, as a temporary safety measure, Black will check that the reformatted code still produces a valid AST that is equivalent to the original. This slows it down. If you’re feeling confident, use --fast.

... but that check puts my worries to rest.

I will start using it in my own code that I am working with for a while.

obestwalter · 2018-05-12T12:23:52Z

I stumbled over the first bug already. It does not correctly break lines in some cases. Will have a look if there is an issue for this already.

gaborbernat · 2018-05-12T12:34:10Z

It's not perfect, but I think it still provides much value.

obestwalter · 2018-05-12T12:40:36Z

I just read the https://github.com/ambv/black#the-black-code-style and I have to say that I am convinced.

I also agree with the thoughts about line length:

You probably noticed the peculiar default line length. Black defaults to 88 characters per line, which happens to be 10% over 80. This number was found to produce significantly shorter files than sticking with 80 (the most popular), or even 79 (used by the standard library). In general, 90-ish seems like the wise choice.

So I would also propose to keep the black default for that.

obestwalter · 2018-05-12T12:44:33Z

Not a bug - missing (tricky) feature (string wrapping): psf/black#182

gaborbernat · 2018-05-12T13:05:47Z

Eh I like what we have with 100 now myself. As for the later, maybe down the line it will be fixed and then the formatter will fix that too automatically.

obestwalter · 2018-05-12T13:12:19Z

It does some really weird things with strings though ...

It turns

fmt = (
    "%(asctime)s %(filename)s.%(funcName)s:%(lineno)d %(levelname)s: "
    "%(message)s"
)

into

fmt = (
    "%(asctime)s %(filename)s.%(funcName)s:%(lineno)d %(levelname)s: " "%(message)s"
)

It does not concatenate the strings again ...

gaborbernat · 2018-05-12T13:18:40Z

Hmmm may require some manual one time mangling then. Probably fill in an issue for it though.

obestwalter · 2018-05-12T13:26:59Z

See psf/black#205

asottile

I wish it was single quotes instead :/

asottile · 2018-05-12T14:18:02Z

.pre-commit-config.yaml

    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
    -   id: check-yaml
    -   id: debug-statements
    -   id: flake8
+-   repo: https://github.com/ambv/black
+    rev: stable


You'll want to pick a specific tag: https://pre-commit.com/#using-the-latest-version-for-a-repository

fixed, and yeah I agree about the quotes; but at the end of day I prefer consistency over which of the two :-)

gaborbernat · 2018-05-12T14:33:00Z

@obestwalter take another look cleaned up manually few of the oddities, if there are any more you spot can do similarly

asottile · 2018-05-12T14:37:46Z

Another option would be to use autopep8 + double-quote-string-fixer (converts strings in the opposite directing of black) + a few other one off formatters to get basically the same deal 🤷‍♂️

gaborbernat · 2018-05-12T14:40:09Z

I'm personally not that pedantic about the single quote to consider worth the effort there.

obestwalter · 2018-05-12T15:23:39Z

I also have a slight preference for single quotes, but don't mind either way, as long as it is consistent.

gaborbernat · 2018-05-12T15:48:50Z

@obestwalter it now passed tests, let me know if you spot anything else 😄

obestwalter · 2018-05-13T10:04:29Z

I wish it was single quotes instead :/

Hey @asottile, if you are interested how this came to pass: I just stumbled over the issue dealing with this: psf/black#51 - there are a few very strong arguments why double quotes are the better choice. The TL;DR of the tipping point is: apostrophes (psf/black#75 (comment)).

Regarding other tools: the more I look into black the more I get the feeling that this could become a standard that will save the community a lot of bike shedding.

I really like the idea to approach the problem from the angle that code should be formatted in a way that maintainability and protection from stupid bugs is prioritized. For that goal it is doing stuff that "traditional" formatters won't touch and IMO that is a GoodThing. Prominently protecting us from the infamous: "Whoops there should actually have been a comma between those two strings in a list, where I moved an element from the end to the middle".

@ambv also has a very clear vision, but is open to change his opinion if confronted with strong arguments (e.g. he also preferred single quotes first), so this looks like a very good project to go with and thanks to the AST checking safeguard, we do not have to be too worried that this first big reformatting PR will introduce some subtle bugs.

The only problems I see atm are around the topic of strings, but they seem to be not too painful and will likely get better. I noticed that our way of creating these mini configs with initproj gets totally shot, which IMO is another black bug, as it actually changes the formatting of the string that will be outputted. In our case it is only an annoyance as the change in formatting does not affect the parsed config. It just looks really ugly now, but they can be formatted in normal strings anyway (I don't need a triple quoted string to create a test config with one or two line breaks), so I would suggest to reformat simple configs like:

    config = newconfig(
        [],
        """
        [testenv:py1]
        deps=pytest
    """,
    )

to:

config = newconfig([], "[testenv:py1]\ndeps=pytest")

Which is much more readable than even the default formatting anyway.

I am going through the PR today and if there are no objections, I think we should whip this into shape together quickly as long as @gaborbernat has still his PyCon wings on :)

asottile · 2018-05-13T14:58:30Z

the more I look into black the more I get the feeling that this could become a standard that will save the community a lot of bike shedding.

yapf started with exactly the same mentality, and is much more mature.

For that goal it is doing stuff that "traditional" formatters won't touch

true yapf / autopep8 don't even try here but that isn't to say that all formatters don't: - https://github.com/asottile/add-trailing-comma - https://github.com/asottile/pyupgrade

The TL;DR of the tipping point is: apostrophes

For me it's less of a personal preference thing and more of an annoyance. A good chunk of the python I write is for web development where double quotes in strings are extremely common (html!). The linked comment above happens way more frequently in the _other direction_ for me. It's also contrary to nearly every style guide I've worked with (again, because web development, but also because pressing the shift key is a slow and `"ERorr prone"` operation).

config = newconfig([], "[testenv:py1]\ndeps=pytest") Which is much more readable than even the default formatting anyway.

Having used this corner-cut myself before, I find it all too easy to typo `\b` instead of `\n` whereas with multiline strings this isn't a problem. Another note in your example is the two aren't equivalent -- there's a whitespace difference (`textrwap.dedent` comes to mind). Anyway, I'm not out here to change minds -- code formatters are some of my favorite things and I think using more of them is a great step in the right direction. Just wish @ambv's black didn't strongly prefer (in my mind) the less convenient quotation style.

gaborbernat · 2018-05-13T15:32:39Z

Given tox is definitely not a web tool, I can get along with having ". As for the initproj we already dedent by default the code, so I think that's just fine.

RonnyPfannschmidt · 2018-05-13T15:38:15Z

i just finished applying black to 2 of my projects along with pre-commit hooks

while my quoting preference is also different, i consider it a straw-man argument, you fix it once, and then keep it consistent -> and consistency is more important there imho

obestwalter · 2018-05-13T16:31:50Z

I understand your annoyance @asottile - it is very dependent on in which kind of universe your code lives - maybe that should really be something configurable in black and maybe it will be at some point to get those kind of projects on board (line lenght is configurable already after all).

The way how black deals with quotes is definitely quite sane IMO - independent of preferences. It always tries to reformat the string in a way that you need the least amount of escapes. e.g. It leaves strings like bla = 'hello "world"' alone and reformats strings like blu = "hello \"world\"" to blu = 'hello "world"'

As you seem o.k. with using black anyway as a step in the right direction and we have an implicit +1 from @RonnyPfannschmidt also, I would say let's just run with this for now.

I'll finish reviewing this tonight then and merge it, so that new PRs coming in tomorrow at the sprint can already base on this, o.k.?

obestwalter

Well, that was one of the most boring and at the same time terrifying PRs I ever had the honour to wade through. All in all I am quite pleased with what black does. There are a few instances where I am actively repelled when I see the result, but a lot of it is getting used to and the rest will be fixable by writing the code differently or in the occasional case where readability is too degraded by black there is always the # fmt: off | # fmt: on wrapper.

Most of the comments are non actionable, where I just had to express my feelings :) - the other actionable ones are trivial.

Good job also on switching all strings to format as well. Which tool did you use for that?

obestwalter · 2018-05-13T17:04:50Z

tests/test_config.py

            [testenv:py1]
-        """)
+        """,
+        )


Looking at it closely it turns out that although what black does here looks awkward and in some cases as if it would change the actual output it really doesn't. It does the right thing and keeps the formatting of the resulting string exactly. So all o.k. on this front.

Yeah, the comma in this case is optional, but never changes the meaning.

I was rather thinking that the line break introduced after the """ would introduce changes in formatting (in some cases - not this one, so the comment was placed not in a good example), but they don't.

obestwalter · 2018-05-13T17:17:30Z

tests/test_config.py

+        assert config.option.force_dep == ["dep1==1.5", "dep2==2.1", "dep3==3.0"]
+        assert (
+            [str(x) for x in config.envconfigs["python"].deps]
+            == ["dep1==1.5", "dep2==2.1", "dep3==3.0", "dep4==4.0"]


Wow - that looks really weird ...

obestwalter · 2018-05-13T17:22:17Z

tests/test_config.py

+                ["cmd2", "-f", "foo bar"],
+                ["cmd3", "-f", "foo", "bar"],
+            ]
+        )


oh dear ... I start wondering, if this isn't a bit too weird ... it will definitely need some getting used to reading stuff like this - but maybe it will also lead to expressing things like that differently, e.g. like:

result = [ ["cmd1", "--foo-args=foo bar"], ["cmd2", "-f", "foo bar"], ["cmd3", "-f", "foo", "bar"], ] assert x == result

obestwalter · 2018-05-13T17:42:50Z

tests/test_config.py

-        (["-qq"], 2),
-        (["-qqq"], 3),
-    ])
+    @pytest.mark.parametrize("args, expected", [([], 0), (["-q"], 1), (["-qq"], 2), (["-qqq"], 3)])


ugh - that one is really screwing up readability to me a lot.

Maybe we should deactivate it for these cases?

# fmt: off @pytest.mark.parametrize('args, expected', [ ([], 0), (["-q"], 1), (["-qq"], 2), (["-qqq"], 3), ]) # fmt: on def test_quiet(self, args, expected, newconfig): config = newconfig(args, "") assert config.option.quiet_level == expected

scratch that - let's just see how it goes without any special casing this early in the game ... I guess it is all a matter of getting used to.

obestwalter · 2018-05-13T17:57:29Z

tests/test_config.py

+            " ",
+            "w[]ord",
+            " ",
+            "{posargs:{a key}}",
        ]


obestwalter · 2018-05-13T19:08:03Z

tox/session.py

-    tw.line("TOX_TESTENV_PASSENV: space-separated list of extra "
-            "environment variables to be passed into test command "
-            "environments")
+    tw.line("TOXENV: comma separated list of environments " "(overridable by '-e')")


needs manual concat.

obestwalter · 2018-05-13T19:16:22Z

tox/venv.py

-                            "command failed but result from testenv is ignored\n"
-                            "  cmd: %s" % (str(err),))
+                            "command failed but result from testenv is ignored\ncmd: {}".format(
+                                str(err)


loose the str() here.

obestwalter · 2018-05-13T19:18:37Z

.pre-commit-config.yaml

 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    sha: v1.1.1
+    rev: v1.2.3
    hooks:
    -   id: trailing-whitespace


Not necessary with black anymore, I guess.

obestwalter · 2018-05-13T19:18:49Z

.pre-commit-config.yaml

 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    sha: v1.1.1
+    rev: v1.2.3
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer


obestwalter · 2018-05-13T19:20:19Z

README.rst

@@ -16,6 +16,9 @@
 .. image:: https://readthedocs.org/projects/tox/badge/?version=latest
  :target: http://tox.readthedocs.io/en/latest/?badge=latest
  :alt: Documentation status
+.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
+  :target: https://github.com/ambv/black
+  :alt: Code style: black


Yeah, I guess that is the case now :)

obestwalter · 2018-05-13T21:01:43Z

@asottile said:

Having used this corner-cut myself before, I find it all too easy to typo
\b instead of \n whereas with multiline strings this isn't a problem.
Another note in your example is the two aren't equivalent -- there's a
whitespace difference (textrwap.dedent comes to mind).

In general I agree, but I think in the context of a tox config test this is not a problem. If you accidentally type \b your test will fail and you'll fix the typo. The whitespace difference is also irrelevant in the context of those particular tests.

gaborbernat · 2018-05-13T21:26:11Z

@obestwalter should be ready for merge now, 😄 as for doing the % to str.format I did it mostly by search, and pycharm suggestions

obestwalter · 2018-05-13T21:29:18Z

as for doing the % to str.format I did it mostly by search, and pycharm suggestions

Wow. You've been busy then :) thanks for all the work you put in to whip that into shape.

obestwalter · 2018-05-13T21:31:52Z

tests/test_config.py

+    getcontextname,
+    is_section_substitution,
+    parseconfig,
+)


argh, now we're back to that thing, but tbh atm I don't care anymore. From now on it's just a question of reconfiguring whatever formatter we use.

yeah, maybe things will change in future with psf/black#204

stays as it is then 👍

obestwalter · 2018-05-13T21:32:55Z

tests/test_config.py

-            ]
-        )
+        expected = [
+            "nosetests", " ", "-v", " ", "-a", " ", "!deferred", " ", "--with-doctest", " ", "[]"


phew - thanks.

gaborbernat requested review from obestwalter and asottile May 12, 2018 11:03

gaborbernat force-pushed the master branch from 64d05aa to 88c1972 Compare May 12, 2018 11:33

add automatic code format enforcer - black

d9dbcee

gaborbernat force-pushed the master branch from 88c1972 to d9dbcee Compare May 12, 2018 11:37

gaborbernat added 2 commits May 12, 2018 10:03

convert % to format

89d8912

fix double quotes in one line

c4cf33a

asottile reviewed May 12, 2018

View reviewed changes

gaborbernat added 3 commits May 12, 2018 10:26

some more % to format changes

b8ee4a7

use stable release of black

2c68d4d

allow unicode in description

4487ddc

gaborbernat force-pushed the master branch from adaf98b to af29ae1 Compare May 12, 2018 14:48

fix typo

7474be8

gaborbernat force-pushed the master branch from af29ae1 to 7474be8 Compare May 12, 2018 15:23

obestwalter requested changes May 13, 2018

View reviewed changes

pr feedback fixes

8cafe90

gaborbernat force-pushed the master branch from 54c1882 to 8cafe90 Compare May 13, 2018 21:18

obestwalter approved these changes May 13, 2018

View reviewed changes

obestwalter merged commit 7a589ea into tox-dev:master May 13, 2018

asottile mentioned this pull request May 14, 2018

Whitespace hooks are still useful for non-python #816

Merged

add automatic code format enforcer - black #813

add automatic code format enforcer - black #813

Conversation

gaborbernat commented May 12, 2018

obestwalter commented May 12, 2018

gaborbernat commented May 12, 2018

codecov bot commented May 12, 2018 • edited Loading

Codecov Report

obestwalter commented May 12, 2018 • edited Loading

obestwalter commented May 12, 2018

gaborbernat commented May 12, 2018

obestwalter commented May 12, 2018

obestwalter commented May 12, 2018

gaborbernat commented May 12, 2018

obestwalter commented May 12, 2018 • edited Loading

gaborbernat commented May 12, 2018

obestwalter commented May 12, 2018

asottile left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gaborbernat commented May 12, 2018

asottile commented May 12, 2018

gaborbernat commented May 12, 2018

obestwalter commented May 12, 2018

gaborbernat commented May 12, 2018

obestwalter commented May 13, 2018 • edited Loading

asottile commented May 13, 2018 via email • edited Loading

gaborbernat commented May 13, 2018

RonnyPfannschmidt commented May 13, 2018

obestwalter commented May 13, 2018 • edited Loading

obestwalter left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

obestwalter commented May 13, 2018 • edited Loading

gaborbernat commented May 13, 2018

obestwalter commented May 13, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

codecov bot commented May 12, 2018 •

edited

Loading

obestwalter commented May 12, 2018 •

edited

Loading

obestwalter commented May 12, 2018 •

edited

Loading

obestwalter commented May 13, 2018 •

edited

Loading

asottile commented May 13, 2018 via email •

edited

Loading

obestwalter commented May 13, 2018 •

edited

Loading

obestwalter left a comment •

edited

Loading

obestwalter commented May 13, 2018 •

edited

Loading