Ruff 24 style guide

[MichaReiser]

Black’s 2024 style heavily inspires Ruff’s 2024 style, but there are a few differences. This discussion describes Ruff's 24 style changes and should aim as a place to provide feedback before we stabilize the changes in an upcoming release.

The work is tracked in #8678

[MichaReiser]

hug_parens_with_braces_and_square_brackets

This style is not part of Black 24 because there are some open questions about whether the style should be applied recursively. We think it's a significant improvement and intend to ship it as part of Ruff 24. Making the style apply recursively (see below) is a fine-tuning that we can do as part of next year's style guide if necessary.

For better readability and less verticality, the style pairs parentheses ((, )) with braces ({, }) and square brackets ([, ]) on the same line for single
argument function calls.

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

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

Ruff's style does not apply recursively, contrary to Black's preview style implementation:

# Ruff
entity_map = CommentedMap([
    (
        entity["entity"],
        entity["value_longer_to_make_it_exceed_the_line_width_and_more"],
    )
])

# Black preview
entity_map = CommentedMap([(
    entity["entity"],
    entity["value_longer_to_make_it_exceed_the_line_width_and_more"],
)])

[MichaReiser]

prefer_splitting_right_hand_side_of_assignments

Prefer splitting the right-hand side (the value) of an assignment over splitting the target or type annotation:

# Stable
for shard, node in nodes:
    params["shard"] = shard
    if base_backup:
        query_settings[
            "base_backup"
        ] = f"S3('{base_backup}/{shard}', '{aws_key}', '{aws_secret}')"
                
# Preview
for shard, node in nodes:
    params["shard"] = shard
    if base_backup:
        # The target no longer breaks    
        query_settings["base_backup"] = (
            f"S3('{base_backup}/{shard}', '{aws_key}', '{aws_secret}')"
        )

[MichaReiser]

no_blank_lines_before_class_docstring

Ruff now removes blank lines between the class's header and its docstring.

# Stable
class C:

    """The line above stays."""

# Preview
class C:
    """The line above stays."""

This aligns the formatting with the docstring formatting of functions.

[MichaReiser]

wrap_multiple_context_managers_in_parens

Ruff now parenthesizes long with items when targeting Python 3.9 or newer or when the with items are already parenthesized instead of using line continuations.

# Stable
with \
     make_context_manager1() as cm1, \
     make_context_manager2() as cm2, \
     make_context_manager3() as cm3, \
     make_context_manager4() as cm4 \
:
    pass

# Preview
with (
    make_context_manager1() as cm1,
    make_context_manager2() as cm2,
    make_context_manager3() as cm3,
    make_context_manager4() as cm4,
):
    pass

Ruff uses the same formatting for async with statements (improved_async_statements_handling)

[MichaReiser]

blank_line_after_nested_stub_class (matches Black 24)

Ruff now adds one blank line after a nested class in stub files (except when the class has an ellipsis body).

# Stable
class Outer:
    class InnerStub: ...
    outer_attr_after_inner_stub: int

    class Inner:
        inner_attr: int
    outer_attr: int
    
# Preview
class Outer:
  class InnerStub: ...
  outer_attr_after_inner_stub: int
  class Inner:
    inner_attr: int

  outer_attr: int

[MichaReiser]

dummy_implementations (matches Black 24)

This preview style improves the formatting of class and function definitions with a dummy (...) body.

• If the body of a class or function is just ..., put it on the same line directly after the colon (does not apply if the parent is any other compound statement).
• Don’t enforce blank lines between two function definitions if the preceding function definition has a dummy implementation body.

# Stable
def f(): 
  ...
def f(): 
  ...


def f():
  """Docstring"""
  ...
    
# Preview
def f(): ...
def f(): ...


def f():
  """Docstring"""
  ...

[MichaReiser]

module_docstring_newlines (matches Black 24)

Ruff now enforces an empty line after the module’s docstring.

# Stable
"""Test docstring"""
a = 1

# Preview
"""Test docstring"""

a = 1

[MichaReiser]

This preview style leads to an incompatibility with reorder-python-imports. See Black's for details. It seems most users migrate to isort because of it.

[MichaReiser]

This leads to a lot of changes in the Airflow code base.

[MichaReiser]

parenthesize_long_type_hints

Ruff now parenthesizes long type annotations in assignments (matches Black 24):

# Stable
z: Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong | Loooooooooooooooooooooooong = x

# Preview
z: (
	Loooooooooooooooooooooooong
	| Loooooooooooooooooooooooong
	| Loooooooooooooooooooooooong
	| Loooooooooooooooooooooooong
) = x

Ruff diverges from Black when formatting long type annotations in function parameters:

# Ruff
def foo(
    i: int,
    x: Loooooooooooooooooooooooong
    | Looooooooooooooooong
    | Looooooooooooooooooooong
    | Looooooong,
    *,
    s: str,
) -> None:
    pass

# Black
def foo(
    i: int,
    x: (
        Loooooooooooooooooooooooong
        | Looooooooooooooooong
        | Looooooooooooooooooooong
        | Looooooong
    ),
    *,
    s: str,
) -> None:
    pass

We acknowledge that the stable style formatting is far from ideal but we aren't convinced that parenthesizing is the best solution when considering expression formatting holistically. That's why we decided to defer the implementation of the proposed style and explore alternatives to improve how nested expressions are formatted so that they are more consistent and avoid unnecessary parentheses. See psf/Black#4123 for an in-depth explanation.

[MichaReiser]

multiline_string_handling (not part of Black 24)

Black intended to ship this preview style but decided not to ship it as part of the 24 style guide because they received feedback that it is too disruptive and doesn't always lead to better formatting. We made some adjustments to how the style works that address the concerns and intend to ship the style as part of Ruff's 24 style guide.

The style, as defined by Black, consists of two changes:

First, black no longer expands call expressions following a multiline string.

# Black 23
MULTILINE = """
foobar
""".replace(
    "\n", ""
)

# Ruff Stable
MULTILINE = """
foobar
""".replace("\n", "")

This is no change to Ruff's formatting because we decided to ship this as part of Ruff's stable style guide last year.

The second part is that Black no longer indents multiline strings if they're the only argument to a call expression.

# Stable 
textwrap.dedent(
    """\
    This is a
    multiline string
"""
)

# Preview
textwrap.dedent("""\
    This is a
    multiline string
""")

This change is motivated by the fact that it is more compact and especially useful with dedent (or other functions that are not whitespace sensitive).

The reason why Black deferred rolling out the change is that it reformats every call expression with a single multiline string argument, and it breaks the alignment of the opening and closing quotes:

# Stable
dedent(
    """
    value
    """
)

# Black's Preview
dedent("""
    value
    """)

We tuned Black's style by using the same heuristic as Prettier (JavaScript formatter) to determine if a multiline string should be indented or not by leaving the choice to the developer. A multiline string is intended if there's a line break between the ( and the string's opening quotes (preserve the indentation). The multline string is hugged if no line breaks between the ( and the opening quotes.

# Does not get indented because there's no line break between the `(` and `"""`
textwrap.dedent("""
    This is a
    multiline string
""")

# Does get indented because there's a line break between the `(` and the `"""`
dedent(
    """
    value
    """
)

The advantage of the heuristic is that it leads to no formatting changes to existing code and allows developers to choose what formatting works best based on the function they're calling. See #9637 for an in-depth discussion of the heuristic.

[MichaReiser]

Not implemented Black 24 preview styles

Ruff does not implement the following style changes that are part of Black’s 24 style guide

allow_empty_first_line_before_new_block_or_comment

Black now allows an empty line between the start of a block and a comment.

    # Here we go
    if x:

        # This is also now fine
        a = 123

Ruff (and Black 23) removes the empty line between the if x: and the # This is also now fine.

We’re concerned that allowing the empty line leads to less consistent formatting after moving code. For a more in-depth explanation, see this comment.

allow_form_feeds

Black now preserves form feeds even without using suppression comments. We’re interested in supporting this eventually but deprioritized it in favor of other work.

parenthesize_conditional_expressions

Black 24 now parenthesizes long conditional expressions.

# Black 23
[
    "____________________________",
    "foo",
    "bar",
    "baz" if some_really_looooooooong_variable else "some other looooooooooooooong value"
]

# Black 24
[
    "____________________________",
    "foo",
    "bar",
    (
        "baz"
        if some_really_looooooooong_variable
        else "some other looooooooooooooong value"
    ),
]

We agree that the conditional expression in the Black 23 (and Ruff's stable) style is difficult to read. However, we want to revisit nested expression formatting holistically and find a style that doesn't require parenthesizing to improve readability. You can read more about our aim in black#4123.

[MichaReiser]

hex_codes_in_unicode_sequences

Normalises hex codes in Unicode sequences to use lowercase (same as what repr uses)

# Stable
a = "\x1B"
b = "\u200B"
c = "\U0001F977"

# Preview
a = "\x1b"
b = "\u200b"
c = "\U0001f977"

According to the changelog, this shipped in Black 24, but I don't think they shipped the code changes because the playground doesn't reformat the hex codes. I'm in contact with the Black team to understand if that was intentional.