actions/black
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Clarify current trailing comma behavior in the docs

Browse Source
This commit is contained in:
Łukasz Langa 2020-09-01 13:24:31 +02:00
parent 1af648d0c1
commit 6b935a34d0
No known key found for this signature in database
GPG Key ID: B26995E310250568
1 changed files with 4 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/the_black_code_style.md
View File

@ -244,16 +244,6 @@ required due to an inner function starting immediately after.
_Black_ will add trailing commas to expressions that are split by comma where each _Black_ will add trailing commas to expressions that are split by comma where each
element is on its own line. This includes function signatures. element is on its own line. This includes function signatures.
Unnecessary trailing commas are removed if an expression fits in one line. This makes it
1% more likely that your line won't exceed the allotted line length limit. Moreover, in
this scenario, if you added another argument to your call, you'd probably fit it in the
same line anyway. That doesn't make diffs any larger.
One exception to removing trailing commas is tuple expressions with just one element. In
this case _Black_ won't touch the single trailing comma as this would unexpectedly
change the underlying data type. Note that this is also the case when commas are used
while indexing. This is a tuple in disguise: `numpy_array[3, ]`.
One exception to adding trailing commas is function signatures containing `*`, `*args`, One exception to adding trailing commas is function signatures containing `*`, `*args`,
or `**kwargs`. In this case a trailing comma is only safe to use on Python 3.6. _Black_ or `**kwargs`. In this case a trailing comma is only safe to use on Python 3.6. _Black_
will detect if your file is already 3.6+ only and use trailing commas in this situation. will detect if your file is already 3.6+ only and use trailing commas in this situation.
@ -262,6 +252,10 @@ in function signatures that have stars in them. In other words, if you'd like a
comma in this situation and _Black_ didn't recognize it was safe to do so, put it there comma in this situation and _Black_ didn't recognize it was safe to do so, put it there
manually and _Black_ will keep it. manually and _Black_ will keep it.
A pre-existing trailing comma informs _Black_ to always explode contents of the current
bracket pair into one item per line. Read more about this in the
[Pragmatism](#pragmatism) section below.
### Strings ### Strings
_Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It _Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It