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 some local formatting

Preview Styles

Black preview styles

• remove_redundant_guard_parens
• parens_for_long_if_clauses_in_case_block (related to remove_redundant_guard_parens): See #10969
• no_normalize_fmt_skip_whitespace: Don't normalize leading whitespace before fmt: skip comments.
• 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
• [hug_parens_with_braces_and_square_brackets]
  • format: different behavior with black for hug_parens_with_braces_and_square_brackets and generators #11375

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
• comprehension_leading_expression_comments_same_line (bugfix)
• with_single_item_pre_39_enabled (style improvement)

Ruff improvements

• Unnecessary parentheses around return-type annotations
• 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)
• 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

[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.