In python, how to tweak Black formatter, if possible?
Question:
I know that Black is an opinionated formatter, but I love everything it does except one major thing. When I have a function with multiple arguments, instead of displaying it like this:
def example_function(arg_1: str, arg_2: bool, arg_3: int = 0, arg_4: int = 1, arg_5: float = 0.0):
pass
I’d rather display it as follows for readability
def example_function(
arg_1: str,
arg_2: bool,
arg_3: int = 0,
arg_4: int = 1,
arg_5: float = 0.0
):
Is this achievable with Black or some other formatter? I have this problem several times and it makes me consider not to use Black, either something else or nothing at all. Any ideas or comments?
Answers:
When using the Black playground at https://black.now.sh, I found that your function was reformatted exactly like that when the line length was short enough (in particular, at 78 characters).
It might be nice if there were a special configuration option that controlled the line length specifically for function parameter lines. BUT to seems to me that Black’s configuration-free approach means that there is no way to control this with any more tailored option.
This is due to the default line length for black
being longer than you’d like – 88 characters per line.
To decrease the line length, you can use the --line-length
flag as documented here:
https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html
For example:
$ black --line-length 80 example.py
Black explains the --line-length
setting in more detail here:
https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length
Line length
You probably noticed the peculiar default line length. Black defaults
to 88 characters per line, which happens to be 10% over 80. This
number was found to produce significantly shorter files than sticking
with 80 (the most popular), or even 79 (used by the standard library).
In general, 90-ish seems like the wise choice.
If you’re paid by the line of code you write, you can pass
--line-length
with a lower number. Black will try to respect that. However, sometimes it won’t be able to without breaking other rules.
In those rare cases, auto-formatted code will exceed your allotted
limit.
You can also increase it, but remember that people with sight
disabilities find it harder to work with line lengths exceeding 100
characters. It also adversely affects side-by-side diff review on
typical screen resolutions. Long lines also make it harder to present
code neatly in documentation or talk slides.
Emphasis on the final paragraph.
I’d recommend just keeping the default settings. The beauty of Black is that it chooses for you, and therefor preempts any arguments about which way is "best".
This is now possible by adding a trailing comma to your last argument.
In your example you would write instead:
def example_function(
arg_1: str,
arg_2: bool,
arg_3: int = 0,
arg_4: int = 1,
arg_5: float = 0.0, # <-- Notice the trailing comma
):
I know that Black is an opinionated formatter, but I love everything it does except one major thing. When I have a function with multiple arguments, instead of displaying it like this:
def example_function(arg_1: str, arg_2: bool, arg_3: int = 0, arg_4: int = 1, arg_5: float = 0.0):
pass
I’d rather display it as follows for readability
def example_function(
arg_1: str,
arg_2: bool,
arg_3: int = 0,
arg_4: int = 1,
arg_5: float = 0.0
):
Is this achievable with Black or some other formatter? I have this problem several times and it makes me consider not to use Black, either something else or nothing at all. Any ideas or comments?
When using the Black playground at https://black.now.sh, I found that your function was reformatted exactly like that when the line length was short enough (in particular, at 78 characters).
It might be nice if there were a special configuration option that controlled the line length specifically for function parameter lines. BUT to seems to me that Black’s configuration-free approach means that there is no way to control this with any more tailored option.
This is due to the default line length for black
being longer than you’d like – 88 characters per line.
To decrease the line length, you can use the --line-length
flag as documented here:
https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html
For example:
$ black --line-length 80 example.py
Black explains the --line-length
setting in more detail here:
https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html#line-length
Line length
You probably noticed the peculiar default line length. Black defaults
to 88 characters per line, which happens to be 10% over 80. This
number was found to produce significantly shorter files than sticking
with 80 (the most popular), or even 79 (used by the standard library).
In general, 90-ish seems like the wise choice.If you’re paid by the line of code you write, you can pass
--line-length
with a lower number. Black will try to respect that. However, sometimes it won’t be able to without breaking other rules.
In those rare cases, auto-formatted code will exceed your allotted
limit.You can also increase it, but remember that people with sight
disabilities find it harder to work with line lengths exceeding 100
characters. It also adversely affects side-by-side diff review on
typical screen resolutions. Long lines also make it harder to present
code neatly in documentation or talk slides.
Emphasis on the final paragraph.
I’d recommend just keeping the default settings. The beauty of Black is that it chooses for you, and therefor preempts any arguments about which way is "best".
This is now possible by adding a trailing comma to your last argument.
In your example you would write instead:
def example_function(
arg_1: str,
arg_2: bool,
arg_3: int = 0,
arg_4: int = 1,
arg_5: float = 0.0, # <-- Notice the trailing comma
):