Ruff 2025 style guide

[MichaReiser]

From Black's changelog. Last checked 16.09.2024, Last release: v24.8.0.

Goals:

• Close parity with Black when migrating from Black to Ruff
• Fix Ruff specific bugs
• Innovate on local formatting (to keep close parity with black)

Preview Styles

Black preview styles

• [x] remove_redundant_guard_parens https://github.com/astral-sh/ruff/pull/13513
• [x] parens_for_long_if_clauses_in_case_block (related to remove_redundant_guard_parens): See #10969 https://github.com/astral-sh/ruff/pull/13513
• [ ] no_normalize_fmt_skip_whitespace: Don't normalize leading whitespace before fmt: skip comments.

Black unstable styles

• [ ] [hug_parens_with_braces_and_square_brackets]
  • https://github.com/astral-sh/ruff/issues/11375
• [x] ~~wrap_long_dict_values_in_parens~~: We decided not to support this style for now because it introduces new parentheses.
• [x] ~~multiline_string_handling~~ non goal. Maybe a simplified version of it that only joins implicitly concatenated strings

Ruff preview styles

Ruff specific preview styles that we may want to stabilize

• [x] f_string_formatting (style improvement)
  • [x] https://github.com/astral-sh/ruff/issues/11056
  • [x] https://github.com/astral-sh/ruff/issues/13237
• [x] comprehension_leading_expression_comments_same_line (bugfix)
• [x] with_single_item_pre_39_enabled (style improvement)
• [x] f_string_implicit_concatenated_string_literal_quotes (bugfix)

Ruff improvements

• [x] Unnecessary parentheses around return-type annotations https://github.com/astral-sh/ruff/pull/13381
• [x] Implicit string formatting
• [x] Can omit parentheses layout for patterns: Related to remove_redundant_guard_parens and parens_for_long_if_clauses_in_case_block

Open Bugs

Existing bugs in the ruff formatter for which no preview style exists.

Require a new style guide

Bug fixes that change how existing code is formatted and require a

• [x] line length calculation for docstring code block is incorrect when using dynamic
• [ ] Handling of blank lines between module docstring and a comment (unclear if it requires a new style guide) @konstin
• [ ] Parenthesize assignment values that fit into the line length
• [ ] Handle over-long lambda expressions (possibly requires a new style guide)

Bug fixes that don't change existing formatting

Bug fixes that don't require a new style guide because they don't change existing cod

• [ ] Preserve trailing whitespace in docstring examples
• [ ] Incorrect docstring code block formatting for statement sequences
• [x] Trailing parenthesized function return type comment becomes leading comment
• [ ] Handling of empty lines after ;
• [ ] Suppressing statement sequences
• [ ] Using fmt:skip to suppress compound statements

Black Bug fixes

Black preview styles that are related to Black-specific bug fixes. Ruff already handles those cases correctly

• pep646_typed_star_arg_type_var_tuple
• unify_docstring_detection: Format module and single quoted docstrings
• typed_params_trailing_comma
• is_simple_lookup_for_doublestar_expression
• docstring_check_for_newline
• pep646_typed_star_arg_type_var_tuple

[MichaReiser]

If anyone's interested in picking up one item on this list, let me know :) Happy to help

[MichaReiser]

One open question is whether we want to support multiple formatter edition (or at least one old edition). It took the community a long time to upgrade to Ruff 0.2

[bnkc]

Hey @MichaReiser I'd be interested in picking up https://github.com/astral-sh/ruff/issues/11216. Let me know if this is alright. Thanks!

[MichaReiser]

Hey @MichaReiser I'd be interested in picking up #11216. Let me know if this is alright. Thanks!

Sure. Feel free to give it a go. I don't know what changes are necessary for it but feel free to comment on that issue with ideas or go ahead with a PR and we can discuss there.

[MichaReiser]

@bnkc how is it going with the docstring bug? Do you need help or did you decide not to work on it (which is fine)? I'm asking because I'm considering to look into it myself because it is probably the most "sever" bug.

[MichaReiser]

@dhruvmanila, do you remember what the open decisions were on the f-string formatting and what the remaining work is for it to be stabilized? Do you know if black implemented a similar formatting style?

[dhruvmanila]

@dhruvmanila, do you remember what the open decisions were on the f-string formatting and what the remaining work is for it to be stabilized? Do you know if black implemented a similar formatting style?

• https://github.com/astral-sh/ruff/issues/13237
• Style decision regarding indentation: https://github.com/astral-sh/ruff/discussions/9785#discussioncomment-8470590
• https://github.com/astral-sh/ruff/issues/11056 which depends on https://github.com/astral-sh/ruff/issues/6591
• https://github.com/astral-sh/ruff/issues/13813

[MichaReiser]

Regarding f-string formatting. We should look into whether it plays nicely with https://github.com/astral-sh/ruff/blob/ae9c6a9255294cb5cc884726fcbfbcd441f2f76c/crates/ruff_python_formatter/src/other/arguments.rs#L221

From looking at the is_multiline implementation I get the impression that it is an over-approximation and a string that was a multiline string might collapse (but maybe that's fine?)

[MichaReiser]

Black's plan is to stabilize all preview styles, but none of the unstable features which aligns with what I outlined in the summary. https://github.com/psf/black/issues/4501

[alechouse97]

Are there any plans to incorporate allowing empty new lines after certain code blocks from #9745 ?

[MichaReiser]

Are there any plans to incorporate allowing empty new lines after certain code blocks from #9745 ?

No, allowing empty lines after clause header is not planned for the upcoming style guide

[trim21]

I'm late for this issue, can we have a stable output of https://docs.astral.sh/ruff/formatter/black/#call-expressions-with-a-single-multiline-string-argument ?

If it's too late for stable 2025 style, is it possible to be a preview style?

[MichaReiser]

I'm late for this issue, can we have a stable output of docs.astral.sh/ruff/formatter/black#call-expressions-with-a-single-multiline-string-argument ?

If it's too late for stable 2025 style, is it possible to be a preview style?

I'm not sure I understand what you mean. The feature itself is stable since last year. Please open a new issue if it isn't working for you together with an example.