Setting the 2025 stable style

[JelleZijlstra]

Refer to #4042 for 2024, #3407 for 2023, #4501 for some previous discussion

It's almost 2025, time to decide what Black's stable style will look like for next year. Any comments are welcome to help decide whether we should stabilize these changes.

My expectation is that we'll stabilize all of the features currently in the preview style, but not those in the unstable style. Here are the current preview rules, sorted in my estimate of most to least controversial:

hex_codes_in_unicode_sequences: normalize casing of Unicode escape characters in strings

#2916.

See also #3568, #2067. Tried this on our codebase at work and it changed a lot of uppercase escapes to lowercase. We already deferred this last year.

remove_lone_list_item_parens: remove redundant parentheses around lone list items

#4312.

Seems fine but was added only recently and probably affects a fair amount of code.

always_one_newline_after_import: Always force one blank line after import statements

#4489.

Again, seems fine but was added recently and probably has significant impact.

unify_docstring_detection: fix inconsistencies in whether certain strings are detected as docstrings

#4095.

This is a bugfix but changed quite a bit of code in our codebase.

typed_params_trailing_comma: consistently add trailing commas to typed function parameters

#4164.

Bugfix, did cause some churn in our codebase.

remove_redundant_guard_parens: Removes redundant parentheses in if guards for case blocks.

#4214.

Remove some redundant parentheses in match/case.

parens_for_long_if_clauses_in_case_block: Adds parentheses to if clauses in case blocks when the line is too long

#4269.

And add them.

no_normalize_fmt_skip_whitespace: whitespace before # fmt: skip comments is no longer normalized

#4146.

Edge case, expect little impact.

is_simple_lookup_for_doublestar_expression: fix line length computation for certain expressions that involve the power operator

#4154.

Rare edge case bugfix.

docstring_check_for_newline: checks if there is a newline before the terminating quotes of a docstring

#4185.

Edge case bugfix.

pep646_typed_star_arg_type_var_tuple: fix type annotation spacing between * and more complex type variable tuple

#4440.

Bug fix for a rare case.

[hauntsaninja]

Would also be good to try and get in a PR for #4071 , would be sad to not have it fixed for a whole one more year

[MichaReiser]

Thanks for writing this up and pinging me. For anyone interested, here a link to what we plan on stabilizing in Ruff astral-sh/ruff#13371

hex_codes_in_unicode_sequences: normalize casing of Unicode escape characters in strings

Ruff ended up stabilizing this last year, whoops. We haven't received much feedback around the change, but some users assumed that changing the casing changes the runtime values (astral-sh/ruff#13859) and some users wished that Ruff defaults to lowercase (astral-sh/ruff#10432)

remove_lone_list_item_parens: remove redundant parentheses around lone list items

Hmm, I missed this when going through the black changes, and I don't think I can prioritize implementing this for Ruff 2025. That said, I think it's fine if the two formatters diverge here because it's a very local change.

always_one_newline_after_import: Always force one blank line after import statements

I didn't do a good job this year because I also missed this change. Two empty lines after imports isn't an uncommon configuration with isort. I worry that enforcing exactly 1 empty line is unnecessarily restrictive. I don't think we'd implement this change in Ruff because it introduces new incompatibilities between our tools.

unify_docstring_detection

Ruff already implements this. I remember a few users who were surprised that Ruff changed their module-level docstrings (astral-sh/ruff#10550).

parens_for_long_if_clauses_in_case_block: Adds parentheses to if clauses in case blocks when the line is too long
remove_redundant_guard_parens: Removes redundant parentheses in if guards for case blocks.

I like these a lot

Bugfixes...

Most bug fixes match Ruff's formatting.

[JelleZijlstra]

I missed this when going through the black changes

I merged both this one and the next one yesterday, so don't feel bad that you missed them :)

Two empty lines after imports isn't an uncommon configuration with isort. I worry that enforcing exactly 1 empty line is unnecessarily restrictive.

I do feel it's within Black's domain to make a decision here. However, especially given this was so recently merged, I'd be open to deferring this change.

[speco29]

hi, im new here and would love to contribute on this project. if you dont mind, can you brief me about it, so that i can understand it better and contribute