Skip to content

future_style.md

Latest commit

 

History

History
296 lines (229 loc) · 8.18 KB

future_style.md

File metadata and controls

296 lines (229 loc) · 8.18 KB

The (future of the) Black code style

Preview style

(labels/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!

(labels/preview-features)=

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

  • wrap_comprehension_in: Wrap the in clause of list and dictionary comprehensions across lines if it would otherwise exceed the maximum line length. (see below)
  • simplify_power_operator_hugging: Use a simpler implementation of the power operator "hugging" logic (removing whitespace around ** in simple expressions), which applies also in the rare case the exponentiation is split into separate lines. (see below)
  • wrap_long_dict_values_in_parens: Add parentheses around long values in dictionaries. (see below)
  • fix_if_guard_explosion_in_case_statement: fixed exploding of the if guard in case patterns which have trailing commas in them, even if the guard expression fits in one line
  • pyi_overload_group_blank_lines: In .pyi stub files, improve heuristics around when blank lines should appear before, after and within decorated function groups. (see below)

(labels/pyi-overload-group)=

Improved heuristics for blank lines before, after and within decorated function groups in stub files

In .pyi stub files, Black now has improved heuristics regarding when blank lines should appear before, after or within groups of decorated functions that share the same name (such as @overload groups). Two rules are applied:

  1. Before a decorated function: a blank line is always inserted, unless the preceding statement is a same-name decorated function (i.e. part of an @overload group) or the function is the first statement in its block.
  2. After a decorated function: a blank line is always inserted, unless the following statement is a same-name decorated function.

These rules apply regardless of what the adjacent statement is — whether it's another function definition, a variable annotation, or any other statement.

Previously, Black could insert unwanted blank lines within an overload group when one of the overloads had a docstring, and did not consistently enforce blank lines at the boundaries of overload groups:

# Before

@overload
def foo(x: int) -> int:
    """Docs."""

@overload                    # unwanted blank line within group
def foo(x: str) -> str: ...
def bar(x): ...              # no blank line after group

With this feature enabled, the group is kept together and clearly separated from surrounding code:

# After (with --preview)

@overload
def foo(x: int) -> int:
    """Docs."""
@overload
def foo(x: str) -> str: ...

def bar(x): ...

(labels/wrap-comprehension-in)=

Wrapping long comprehension in clauses

When a list or dictionary comprehension has a long in clause that would exceed the maximum line length, Black will wrap it across multiple lines for better readability. This helps keep comprehensions readable when the iterable expression is complex or lengthy.

For example:

# Before
result = [
    very_very_very_very_very_long_item
    for very_very_very_very_very_long_item in some_very_very_very_very_very_very_long_function_name
]

will be formatted to:

# After
result = [
    very_very_very_very_very_long_item
    for very_very_very_very_very_long_item in (
        some_very_very_very_very_very_very_long_function_name
    )
]

This also applies to dictionary comprehensions:

# Before
mapping = {
    very_long_key: very_very_very_long_item
    for very_long_key, very_very_very_long_item in very_very_very_very_long_function_name
}

will be formatted to:

# After
mapping = {
    very_long_key: very_very_very_long_item
    for very_long_key, very_very_very_long_item in (
        very_very_very_very_long_function_name
    )
}

(labels/simplify-power-operator)=

Simplified power operator whitespace handling

Black's power operator "hugging" logic removes whitespace around ** in simple expressions (e.g., x**2 instead of x ** 2). This feature uses a simpler, more consistent implementation that also applies when exponentiation is split across lines.

For example:

# Simple expressions - whitespace is removed
result = x**2 + y**3
value = base**exponent

When the exponentiation is split across lines (rare), the simplified logic ensures consistent formatting:

# Complex expression split across lines
result = (
    some_very_long_base_expression
    **some_very_long_exponent_expression
    **some_very_long_third_expression
)

This feature primarily improves the internal consistency of Black's formatting logic rather than making dramatic visual changes to most code.

(labels/wrap-long-dict-values)=

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,
}

Unstable style

(labels/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.

(labels/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)

(labels/hug-parens)=

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

(labels/string-processing)=

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.