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

• remove_redundant_guard_parens Parenthesize match..case if guards #13513
• parens_for_long_if_clauses_in_case_block (related to remove_redundant_guard_parens): See #10969 Parenthesize match..case if guards #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]
  • format: different behavior with black for hug_parens_with_braces_and_square_brackets and generators #11375
• wrap_long_dict_values_in_parens: We decided not to support this style for now because it introduces new parentheses.
• 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

• f_string_formatting (style improvement)
  • Improve backport friendliness of quotes in Python 3.12 f-string placeholders #11056
  • formatter should change f strings using single quotes with nested double quotes to use double quotes when target-version is py312 #13237
  • F-String formatting in assignment positions #13813
  • F-string formatting: Invalid syntax for format-spec with double quotes when targeting pre Python 3.12 #14608
  • fixes [ruff] Formatting hex codes changes output with f-string debug #14766
• comprehension_leading_expression_comments_same_line (bugfix)
• with_single_item_pre_39_enabled (style improvement)
• f_string_implicit_concatenated_string_literal_quotes (bugfix)

Ruff improvements

• Unnecessary parentheses around return-type annotations Fix parentheses around return type annotations #13381
• Implicit string formatting
• 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

• 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
• 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

Needs fixing

• 0.8.1 regression - formatter removes strings causing a syntax error on multiline fstring with implicitly concatenated strings and an if expression inside it #14778

[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 #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]

@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?

• formatter should change f strings using single quotes with nested double quotes to use double quotes when target-version is py312 #13237
• Style decision regarding indentation: F-String Formatting Style #9785 (comment)
• Improve backport friendliness of quotes in Python 3.12 f-string placeholders #11056 which depends on Emit diagnostics for new syntax as per the target Python version #6591
• F-String formatting in assignment positions #13813

[MichaReiser]

Regarding f-string formatting. We should look into whether it plays nicely with

ruff/crates/ruff_python_formatter/src/other/arguments.rs

Line 221 in ae9c6a9

fn is_huggable_string_argument(

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. psf/black#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.