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]

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

• 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