Skip to content

Commit efbc862

Browse files
committed
Mention style changes that are likely to be part of Black 2025
1 parent 790ba1c commit efbc862

File tree

1 file changed

+49
-8
lines changed

1 file changed

+49
-8
lines changed

docs/formatter/black.md

Lines changed: 49 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -215,7 +215,7 @@ c = "\U0001f977"
215215
d = "\N{CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I}"
216216
```
217217

218-
TODO: Is this part of Black's 2025 style guide?
218+
Ruff's formatting matches Black's preview formatting, and we expect it to be part of [Black's 2025 style guide](https://github.com/psf/black/issues/4522).
219219

220220
### Module docstrings
221221

@@ -236,9 +236,9 @@ Ruff formats module docstrings similar to class or function docstrings, whereas
236236
"""Module docstring"""
237237

238238
```
239-
TODO: Is this part of Black's 2025 style guide?
239+
Ruff's formatting matches Black's preview formatting, and we expect it to be part of [Black's 2025 style guide](https://github.com/psf/black/issues/4522).
240240

241-
### F-string formatting
241+
### F-strings
242242

243243
Ruff formats expression parts in f-strings whereas Black does not:
244244

@@ -253,7 +253,7 @@ f'test{inner + "nested_string"} including math {5 ** 3 + 10}'
253253
f"test{inner + 'nested_string'} including math {5**3 + 10}"
254254
```
255255

256-
### Implicit concatenated string formatting
256+
### Implicit concatenated strings
257257

258258
Ruff merges implicitly concatenated strings if the entire string fits on a single line:
259259

@@ -299,9 +299,9 @@ a = (
299299
)
300300
```
301301

302-
This makes the formatter compatible with `ISC001` ([#8272](https://github.com/astral-sh/ruff/issues/8272)).
302+
This ensures compatibility with `ISC001` ([#8272](https://github.com/astral-sh/ruff/issues/8272)).
303303

304-
### `assert` formatting
304+
### `assert` statements
305305

306306
Unlike Black, Ruff prefers breaking the message over breaking the assertion, similar to how both Ruff and Black prefer breaking the assignment value over breaking the assignment target:
307307

@@ -323,6 +323,47 @@ assert len(policy_types) >= priority + num_duplicates, (
323323
)
324324
```
325325

326+
### Parentheses around `if`-guards in `match` statements
327+
Ruff automatically parenthesizes overlong `if` guards and it also removes parentheses if they're no longer required.
328+
329+
```python
330+
# Input
331+
match some_variable:
332+
case "short-guard" if (
333+
other_condition
334+
):
335+
pass
336+
337+
case "long-guard" if other_condition or some_long_call_expression(with_may, arguments) or last_condition:
338+
pass
339+
340+
341+
# Black
342+
match some_variable:
343+
case "short-guard" if (other_condition):
344+
pass
345+
346+
case "long-guard" if other_condition or some_long_call_expression(
347+
with_may, arguments
348+
) or last_condition:
349+
pass
350+
351+
352+
# Ruff
353+
match some_variable:
354+
case "short-guard" if other_condition:
355+
pass
356+
357+
case "long-guard" if (
358+
other_condition
359+
or some_long_call_expression(with_may, arguments)
360+
or last_condition
361+
):
362+
pass
363+
```
364+
365+
Ruff's formatting matches Black's preview formatting, and we expect it to be part of [Black's 2025 style guide](https://github.com/psf/black/issues/4522).
366+
326367
### `global` and `nonlocal` names are broken across multiple lines by continuations
327368

328369
If a `global` or `nonlocal` statement includes multiple names, and exceeds the configured line
@@ -371,7 +412,7 @@ class IntFromGeom(GEOSFuncFactory):
371412
errcheck = staticmethod(check_minus_one)
372413
```
373414

374-
TODO: Is this part of Black's 2025 style guide?
415+
Ruff's formatting matches Black's preview formatting, and we expect it to be part of [Black's 2025 style guide](https://github.com/psf/black/issues/4522).
375416

376417
### Trailing own-line comments on imports are not moved to the next line
377418

@@ -590,7 +631,7 @@ def func(
590631

591632
Ruff will instead insert a trailing comma in all such cases for consistency.
592633

593-
TODO: Is this part of Black's 2025 style guide?
634+
Ruff's formatting matches Black's preview formatting, and we expect it to be part of [Black's 2025 style guide](https://github.com/psf/black/issues/4522).
594635

595636
### Parentheses around call-chain assignment values are not preserved
596637

0 commit comments

Comments
 (0)