Sorting includes

[henryiii]

We've already been dealing with occasion merge conflicts because of changes on imports (glaring at typing right now...). There are two solutions: One is https://pypi.org/project/reorder-python-imports/, via pre-commit. That even does the smart grouping following PEP8, but it does produces this rewrite:

from typing import Any
from typing import Dict
from typing import List
from typing import Tuple

See reasoning here. Maybe I could get used to it; part of the problem of having too many characters is solved by the smart grouping, I'm more used to the following, black compatible import style:

from typing import (
    Any,
    Dict,
    List,
    Tuple,
)

This does have a slightly higher chance of merge conflicts, but still solves most of them without adding a massive number of extra characters and visual clutter (it does add two lines, though). Generally I use black + isort + a flake8 grouping check to get this result; we could probably get most of the way there with isort + flake8, though, maybe with a pre-run of reorder-python-imports then manual grouping?

Note that reorder_python_imports has some useful tools unrelated to reordering, like removing/adding imports.

[Czaki]

Why not isort?

[henryiii]

Isn't that what I listed as the second solution? A flake8 check + isort. isort can't get the grouping for you like reorder-python-imports can.

Actually I think I forgot to list it as the second solution. I intended to when I mentioned it.

[henryiii]

Actually, I think I've only done the flake8 + black before, isort is quite powerful, didn't realize how much so. Nice!

[henryiii]

Made a PR for people to look at.

[mayeut]

If adding isort, I'd really be in favor of adding black as well. I think given the current status of cibuildwheel, having mypy, flake8, black & isort would be great.

[henryiii]

Black lets you add an empty line too,
to allow grouping,
just like we do after sentences.
It also lets you add an extra comma at the end of a list to signify something.

[henryiii]

Unblacked:

x = [[[0.0, 1.1, 2.2, 3.3],
      []],
      [[4.4, 5.5]],
      [],
      [[6.6],
      [7.7, 8.8, 9.9, 10.0, 11., 12.]]]

Blacked:

x = [
    [[0.0, 1.1, 2.2, 3.3], []],
    [[4.4, 5.5]],
    [],
    [[6.6], [7.7, 8.8, 9.9, 10.0, 11.0, 12.0]],
]

If I'm reading unBlacked code, I have to be wary of the first structure - it's legal, after all. If I'm reading Blacked code, that can never happen, I no longer pause to count the brackets, and can just keep going. Even if no one was this evil/clever, I still have to check.

If you need to impart meaning to the reader, you should impart it to Python too.

[YannickJadoul]

x = [[[0.0, 1.1, 2.2, 3.3],
      []],
     [[4.4, 5.5]],
     [],
     [[6.6],
      [7.7, 8.8, 9.9, 10.0, 11., 12.]]]

Two spaces less already paints a difference picture (one that Black doesn't perfectly show either, I'd say, but that's disputable). But I've never said that anything goes. The first one is more or less objectively badly formatted (especially without meaning attached); I think we can agree on that.

The thing I don't agree on is that in every single case, Black's output is best. Maybe, in this specific case, maybe the third level is the one you want/need to focus on? Maybe all of those deserve their own line, and meanwhile the structure is also clear from context?

If you need to impart meaning to the reader, you should impart it to Python too.

Either I don't understand what you mean, or I don't agree on that. By that reasoning, comments and well-chosen names don't matter either, because Python doesn't attach meaning to these either?

[henryiii]

I don't claim black is perfect, or the best output. I claim it is a standard (and minimizes diffs). You will never have a perfect standard.

Maybe, in this specific case, maybe the third level is the one you want/need to focus on?

But you are tricking your reader, but not Python. If a reader can be sure formatting is standard, they don't have to check for it. Your structures should be clear to the reader. If there's a format on/off, then they will know to slow down and check each bracket; but most of the time, are you trying to hide nesting to the reader? I've seen users do it, certainly, but I've never found it helpful. I want to know what the actual structure is.

That's what yaml is good at, actually, having clear structure humans can parse quickly.

By that reasoning, comments and well-chosen names don't matter either

Not really, comments and names are explicitly how you communicate to the reader. The structure of your program, however, is something you are communicating to Python (blocks, brackets, etc); they do not have arbitrary meaning.

[YannickJadoul]

But you are tricking your reader, but not Python.

I'm not trying to trick anyone. I'm trying to put emphasis on what matters to the reader.

By that reasoning, comments and well-chosen names don't matter either

Not really, comments and names are explicitly how you communicate to the reader. The structure of your program, however, is something you are communicating to Python (blocks, brackets, etc); they do not have arbitrary meaning.

That's not true to me. Python's syntactic structure is not fixed, and allows you to communicate through that as well. That's exactly the small gap where you can (sometimes) express your goal/focus, next to satisfying Python's syntax. Just like Python tells you to make variables, but not what name they should have, so the wiggle room allows you to communicate to the user. In any case, as long as it doesn't confuse the reader, it can only help.