Add "preview" and "skip-magic-trailing-comma" options, and version bump to v0.2.5

[ferdynice]

Add the "preview" option.

[peterjc]

Do you use this then?

  --preview                       Enable potentially disruptive style changes
                                  that will be added to Black's main
                                  functionality in the next major release.

[ferdynice]

Correct. There are a few other options that seem to be missing (I think). Not sure if there were existing plans to add them, but adding at least this specific option would be very helpful for us.

[peterjc]

Yes, as I recall black started with no options (except the line length - notes on that in the flake8-black change log), but has sadly been getting more and more.

I think now that they have dropped the beta tag, it is worthwhile looking at the black Python API for a neater way to use their own configuration parser, and just specify which files to check.

[peterjc]

You're welcome to take a look at that approach - although waiting on psf/black#779 might be wiser.

[ferdynice]

I don't think the options will change that often anymore, since the aim of Black is to be as opiniated as possible. Especially now that it is becoming more and more stable. Using a config parser from Black (official API or not) would be nice, but a bit out of scope for me to pick up.

Instead what I did now is add an additional option in this PR, "skip_magic_trailing_comma", which seems to be a highly debated issue. When you set this option to true, magic commas will be turned off. Without magic commas, Black won't look at existing formatting and will try to put arguments/collections as much one 1 line as possible. Check psf/black#1288

I believe with this current set of flags most users will be provided for. But feel free to decide however you see fit.

[peterjc]

That is pragmatic, and I'm OK with merging this with the hope of switching to the planned black API in future which will (hopefully) let us drop this part of the flake8-black code.

Can you do a version bump and change log entry for this too? That would save me some time making the release with these changes. Thanks!

[ferdynice]

Done! I hope I did this right.

[ferdynice]

I renamed the option in the messages to "skip-magic-trailing-comma", since that is what the actual option in the config file is named. And I tested and verified that it actually works (just like "preview").

[peterjc]

Do you happen to already have a couple of short examples where these settings come into play?

[ferdynice]

If you mean a short explanation, here you go (assume a line-length = 79 for the first example):

With preview = false (default):

def foo():
    print(
        "hellooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo world"
    )
    print("hello " "world")

With preview = true:

def foo():
    print(
        "hellooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo"
        " world"
    )
    print("hello world")

As you can see it will concatenate and split strings to accomodate Black's styling.

With skip-magic-trailing-comma = false (default):

def foo():
    SomeClass(
        foo=1,
        bar=2,  # remove this trailing comma to instruct black to put all args on a single line
    )

With skip-magic-trailing-comma = true:

def foo():
    SomeClass(foo=1, bar=2)

So without the magic trailing comma (skip-magic-trailing-comma = true), if it fits on a single line, Black will format it that way. No matter if the last arg contained a trailing comma or not.

[peterjc]

Lovely - I made something similar with commas, but reminding myself how I setup the test folders took me longer than I expected. I'll use your preview example now...

[peterjc]

Curious - adding # noqa: E501 to the very long line in your example seems to disable the black string editing. Not to worry, the second example of implicit string concatenation works.

[ferdynice]

Ah indeed. Any comment starting with # noqa it seems. But for the purpose to check if the preview option has any effect at all, the concatenation test should suffice.

[peterjc]

That's up on PyPI now https://pypi.org/project/flake8-black/0.2.5/ - conda-forge to follow.

[peterjc]

I forgot this would need the latest black, see #49. Fixed as v0.3.0