Add preference of parantheses over backslashes in docs (#1399)
Closes https://github.com/psf/black/issues/392 Revived from https://github.com/psf/black/pull/558 Relevant to https://github.com/psf/black/issues/664
This commit is contained in:
parent
4501f22fcb
commit
f6393a20fc
63
README.md
63
README.md
@ -238,6 +238,69 @@ def very_important_function(
|
|||||||
...
|
...
|
||||||
```
|
```
|
||||||
|
|
||||||
|
_Black_ prefers parentheses over backslashes, and will remove backslashes if found.
|
||||||
|
|
||||||
|
```py3
|
||||||
|
# in:
|
||||||
|
|
||||||
|
if some_short_rule1 \
|
||||||
|
and some_short_rule2:
|
||||||
|
...
|
||||||
|
|
||||||
|
# out:
|
||||||
|
|
||||||
|
if some_short_rule1 and some_short_rule2:
|
||||||
|
...
|
||||||
|
|
||||||
|
|
||||||
|
# in:
|
||||||
|
|
||||||
|
if some_long_rule1 \
|
||||||
|
and some_long_rule2:
|
||||||
|
...
|
||||||
|
|
||||||
|
# out:
|
||||||
|
|
||||||
|
if (
|
||||||
|
some_long_rule1
|
||||||
|
and some_long_rule2
|
||||||
|
):
|
||||||
|
...
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
Backslashes and multiline strings are one of the two places in the Python grammar that
|
||||||
|
break significant indentation. You never need backslashes, they are used to force the
|
||||||
|
grammar to accept breaks that would otherwise be parse errors. That makes them confusing
|
||||||
|
to look at and brittle to modify. This is why _Black_ always gets rid of them.
|
||||||
|
|
||||||
|
If you're reaching for backslashes, that's a clear signal that you can do better if you
|
||||||
|
slightly refactor your code. I hope some of the examples above show you that there are
|
||||||
|
many ways in which you can do it.
|
||||||
|
|
||||||
|
However there is one exception: `with` statements using multiple context managers.
|
||||||
|
Python's grammar does not allow organizing parentheses around the series of context
|
||||||
|
managers.
|
||||||
|
|
||||||
|
We don't want formatting like:
|
||||||
|
|
||||||
|
```py3
|
||||||
|
with make_context_manager1() as cm1, make_context_manager2() as cm2, make_context_manager3() as cm3, make_context_manager4() as cm4:
|
||||||
|
... # nothing to split on - line too long
|
||||||
|
```
|
||||||
|
|
||||||
|
So _Black_ will now format it like this:
|
||||||
|
|
||||||
|
```py3
|
||||||
|
with \
|
||||||
|
make_context_manager(1) as cm1, \
|
||||||
|
make_context_manager(2) as cm2, \
|
||||||
|
make_context_manager(3) as cm3, \
|
||||||
|
make_context_manager(4) as cm4 \
|
||||||
|
:
|
||||||
|
... # backslashes and an ugly stranded colon
|
||||||
|
```
|
||||||
|
|
||||||
You might have noticed that closing brackets are always dedented and that a trailing
|
You might have noticed that closing brackets are always dedented and that a trailing
|
||||||
comma is always added. Such formatting produces smaller diffs; when you add or remove an
|
comma is always added. Such formatting produces smaller diffs; when you add or remove an
|
||||||
element, it's always just one line. Also, having the closing bracket dedented provides a
|
element, it's always just one line. Also, having the closing bracket dedented provides a
|
||||||
|
Loading…
Reference in New Issue
Block a user