Changes to this document often aren't tied and don't relate to releases of
_Black_. It's recommended that you read the latest version available.
Backslashes are bad and should be never be used however
there is one exception: with
statements using multiple context managers. Before Python
3.9 Python's grammar does not allow organizing parentheses around the series of context
managers.
We don't want formatting like:
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 eventually format it like this:
with \
make_context_manager1() as cm1, \
make_context_manager2() as cm2, \
make_context_manager3() as cm3, \
make_context_manager4() as cm4 \
:
... # backslashes and an ugly stranded colon
Although when the target version is Python 3.9 or higher, Black will use parentheses instead since they're allowed in Python 3.9 and higher.
An alternative to consider if the backslashes in the above formatting are undesirable is
to use {external:py:obj}contextlib.ExitStack
to combine context managers in the
following way:
with contextlib.ExitStack() as exit_stack:
cm1 = exit_stack.enter_context(make_context_manager1())
cm2 = exit_stack.enter_context(make_context_manager2())
cm3 = exit_stack.enter_context(make_context_manager3())
cm4 = exit_stack.enter_context(make_context_manager4())
...
Experimental, potentially disruptive style changes are gathered under the --preview
CLI flag. At the end of each year, these changes may be adopted into the default style,
as described in The Black Code Style. Because the functionality is
experimental, feedback and issue reports are highly encouraged!
Black will split long string literals and merge short ones. Parentheses are used where appropriate. When split, parts of f-strings that don't need formatting are converted to plain strings. User-made splits are respected when they do not exceed the line length limit. Line continuation backslashes are converted into parenthesized strings. Unnecessary parentheses are stripped. The stability and status of this feature is tracked in this issue.
-
Black will remove newlines in the beginning of new code blocks, i.e. when the indentation level is increased. For example:
def my_func(): print("The line above me will be deleted!")
will be changed to:
def my_func(): print("The line above me will be deleted!")
This new feature will be applied to all code blocks:
def
,class
,if
,for
,while
,with
,case
andmatch
. -
Black will enforce empty lines before classes and functions with leading comments. For example:
some_var = 1 # Leading sticky comment def my_func(): ...
will be changed to:
some_var = 1 # Leading sticky comment def my_func(): ...
Black will format parentheses around return annotations similarly to other sets of parentheses. For example:
def foo() -> (int):
...
def foo() -> looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong:
...
will be changed to:
def foo() -> int:
...
def foo() -> (
looooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooong
):
...
And, extra parentheses in await
expressions and with
statements are removed. For
example:
with ((open("bla.txt")) as f, open("x")):
...
async def main():
await (asyncio.sleep(1))
will be changed to:
with open("bla.txt") as f, open("x"):
...
async def main():
await asyncio.sleep(1)
Black is smarter when formatting multiline strings, especially in function arguments, to avoid introducing extra line breaks. Previously, it would always consider multiline strings as not fitting on a single line. With this new feature, Black looks at the context around the multiline string to decide if it should be inlined or split to a separate line. For example, when a multiline string is passed to a function, Black will only split the multiline string if a line is too long or if multiple arguments are being passed.
For example, Black will reformat
textwrap.dedent(
"""\
This is a
multiline string
"""
)
to:
textwrap.dedent("""\
This is a
multiline string
""")
And:
MULTILINE = """
foobar
""".replace(
"\n", ""
)
to:
MULTILINE = """
foobar
""".replace("\n", "")