The (future of the) Black code style¶

Preview style¶

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!

Currently, the following features are included in the preview style:

always_one_newline_after_import: Always force one blank line after import statements, except when the line after the import is a comment or an import statement
wrap_long_dict_values_in_parens: Add parentheses around long values in dictionaries (see below)
fix_fmt_skip_in_one_liners: Fix # fmt: skip behaviour on one-liner declarations, such as def foo(): return "mock" # fmt: skip, where previously the declaration would have been incorrectly collapsed.
standardize_type_comments: Format type comments which have zero or more spaces between # and type: or between type: and value to # type: (value)
wrap_comprehension_in: Wrap the in clause of list and dictionary comprehensions across lines if it would otherwise exceed the maximum line length.
remove_parens_around_except_types: Remove parentheses around multiple exception types in except and except* without as. See PEP 758 for details.
normalize_cr_newlines: Add \r style newlines to the potential newlines to normalize file newlines both from and to.
fix_module_docstring_detection: Fix module docstrings being treated as normal strings if preceeded by comments.
fix_type_expansion_split: Fix type expansions split in generic functions.
multiline_string_handling: more compact formatting of expressions involving multiline strings (see below)
fix_module_docstring_detection: Fix module docstrings being treated as normal strings if preceeded by comments.

Improved parentheses management in dicts¶

For dict literals with long values, they are now wrapped in parentheses. Unnecessary parentheses are now removed. For example:

my_dict = {
    "a key in my dict": a_very_long_variable
    * and_a_very_long_function_call()
    / 100000.0,
    "another key": (short_value),
}

will be changed to:

my_dict = {
    "a key in my dict": (
        a_very_long_variable * and_a_very_long_function_call() / 100000.0
    ),
    "another key": short_value,
}

Improved multiline string handling¶

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", "")

Unstable style¶

In the past, the preview style included some features with known bugs, so that we were unable to move these features to the stable style. Therefore, such features are now moved to the --unstable style. All features in the --preview style are expected to make it to next year’s stable style; features in the --unstable style will be stabilized only if issues with them are fixed. If bugs are discovered in a --preview feature, it is demoted to the --unstable style. To avoid thrash when a feature is demoted from the --preview to the --unstable style, users can use the --enable-unstable-feature flag to enable specific unstable features.

The unstable style additionally includes the following features:

hug_parens_with_braces_and_square_brackets: more compact formatting of nested brackets (see below)
string_processing: split long string literals and related changes (see below)

Improved multiline dictionary and list indentation for sole function parameter¶

For better readability and less verticality, Black now pairs parentheses (“(”, “)”) with braces (“{”, “}”) and square brackets (“[”, “]”) on the same line. For example:

foo(
    [
        1,
        2,
        3,
    ]
)

nested_array = [
    [
        1,
        2,
        3,
    ]
]

will be changed to:

foo([
    1,
    2,
    3,
])

nested_array = [[
    1,
    2,
    3,
]]

This also applies to list and dictionary unpacking:

foo(
    *[
        a_long_function_name(a_long_variable_name)
        for a_long_variable_name in some_generator
    ]
)

will become:

foo(*[
    a_long_function_name(a_long_variable_name)
    for a_long_variable_name in some_generator
])

You can use a magic trailing comma to avoid this compacting behavior; by default, Black will not reformat the following code:

foo(
    [
        1,
        2,
        3,
    ],
)

Improved string processing¶

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. f-strings will not be merged if they contain internal quotes and it would change their quotation mark style. Line continuation backslashes are converted into parenthesized strings. Unnecessary parentheses are stripped. The stability and status of this feature is tracked in this issue.