From 6b935a34d08c0b18d858e7da5093dc69a29c55f2 Mon Sep 17 00:00:00 2001 From: =?utf8?q?=C5=81ukasz=20Langa?= Date: Tue, 1 Sep 2020 13:24:31 +0200 Subject: [PATCH] Clarify current trailing comma behavior in the docs --- docs/the_black_code_style.md | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/docs/the_black_code_style.md b/docs/the_black_code_style.md index 735e9c0..19464ba 100644 --- a/docs/the_black_code_style.md +++ b/docs/the_black_code_style.md @@ -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 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`, 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. @@ -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 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 _Black_ prefers double quotes (`"` and `"""`) over single quotes (`'` and `'''`). It -- 2.39.2