Missing documentation on magic comma

[peterjc]

Is this related to a problem? Please describe.

I am aware from the issue tracker of the "magic comma" whereby a trailing comma can sometimes influence what black does, but cannot see where this is documented - e.g. https://black.readthedocs.io/en/stable/faq.html#

Describe the solution you'd like

Have the "magic comma" documented.

Describe alternatives you've considered

I have browsed the issues but haven't hit on a succinct summary.

Additional context

I'm hoping to tweak how black formats some multi-line lists of constant values in my code.

[felix-hilden]

That'd be in the style documentation!

[peterjc]

Thank you. That covers one of my use cases nicely - arrays of numbers:

$ black --diff array_eg.py 
--- array_eg.py	2021-10-07 13:22:46.959630 +0000
+++ array_eg.py	2021-10-07 13:22:49.813943 +0000
@@ -1,6 +1,3 @@
 import numpy as np
 
-data = array([[0, 1,  2,  3],
-              [4, 5,  6,  7],
-              [8, 9, 10, 11],
-              [1, 2,  3,  4]])
+data = array([[0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11], [1, 2, 3, 4]])
would reformat array_eg.py
All done! ✨ 🍰 ✨
1 file would be reformatted.

Adding a trailing comma retains the square layout:

$ black --diff array_eg.py 
--- array_eg.py	2021-10-07 13:22:58.559466 +0000
+++ array_eg.py	2021-10-07 13:23:00.419753 +0000
@@ -1,6 +1,10 @@
 import numpy as np
 
-data = array([[0, 1,  2,  3],
-              [4, 5,  6,  7],
-              [8, 9, 10, 11],
-              [1, 2,  3,  4],])
+data = array(
+    [
+        [0, 1, 2, 3],
+        [4, 5, 6, 7],
+        [8, 9, 10, 11],
+        [1, 2, 3, 4],
+    ]
+)
would reformat array_eg.py
All done! ✨ 🍰 ✨
1 file would be reformatted.

It looks like my other example with explicit breaks but more than one item per line is not covered, which is fine. I can turn off black formatting for that snippet if really desired.

[felix-hilden]

Yeah, we are discussing the "redundant" indentation level in #1811 if you'd like to follow it. But I'll close this issue for now since there seems to be nothing new requested, and the documentation exists!