mirrors/ruff
1
0
Fork 0
mirror of https://github.com/astral-sh/ruff.git synced 2025-07-07 21:25:08 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Update black deviations (#15928)

Browse source
This commit is contained in:
Micha Reiser 2025-02-04 14:04:24 +00:00 • committed by GitHub
parent cc60701b59
commit ff87ea8d42
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 23 additions and 147 deletions
Download patch file Download diff file Expand all files Collapse all files

170
docs/formatter/black.md
View file

@ -197,46 +197,6 @@ if x:
Currently, we are concerned that allowing blank lines at the start of a block leads [to unintentional blank lines when refactoring or moving code](https://github.com/astral-sh/ruff/issues/8893#issuecomment-1867259744). However, we will consider adopting Black's formatting at a later point with an improved heuristic. The style change is tracked in [#9745](https://github.com/astral-sh/ruff/issues/9745). Currently, we are concerned that allowing blank lines at the start of a block leads [to unintentional blank lines when refactoring or moving code](https://github.com/astral-sh/ruff/issues/8893#issuecomment-1867259744). However, we will consider adopting Black's formatting at a later point with an improved heuristic. The style change is tracked in [#9745](https://github.com/astral-sh/ruff/issues/9745).
### Hex codes and Unicode sequences
Ruff normalizes hex codes and Unicode sequences in strings ([#9280](https://github.com/astral-sh/ruff/pull/9280)). Black intended to ship this change as part of the 2024 style but accidentally didn't.
```python
# Black
a = "\x1B"
b = "\u200B"
c = "\U0001F977"
d = "\N{CYRILLIC small LETTER BYELORUSSIAN-UKRAINIAN I}"
# Ruff
a = "\x1b"
b = "\u200b"
c = "\U0001f977"
d = "\N{CYRILLIC SMALL LETTER BYELORUSSIAN-UKRAINIAN I}"
```
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).
### Module docstrings
Ruff formats module docstrings similar to class or function docstrings, whereas Black does not.
```python
# Input
"""Module docstring
"""
# Black
"""Module docstring
"""
# Ruff
"""Module docstring"""
```
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).
### F-strings ### F-strings
@ -326,47 +286,6 @@ assert len(policy_types) >= priority + num_duplicates, (
) )
``` ```
### Parentheses around `if`-guards in `match` statements
Ruff automatically parenthesizes overlong `if` guards and it also removes parentheses if they're no longer required.
```python
# Input
match some_variable:
case "short-guard" if (
other_condition
):
pass
case "long-guard" if other_condition or some_long_call_expression(with_may, arguments) or last_condition:
pass
# Black
match some_variable:
case "short-guard" if (other_condition):
pass
case "long-guard" if other_condition or some_long_call_expression(
with_may, arguments
) or last_condition:
pass
# Ruff
match some_variable:
case "short-guard" if other_condition:
pass
case "long-guard" if (
other_condition
or some_long_call_expression(with_may, arguments)
or last_condition
):
pass
```
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).
### `global` and `nonlocal` names are broken across multiple lines by continuations ### `global` and `nonlocal` names are broken across multiple lines by continuations
If a `global` or `nonlocal` statement includes multiple names, and exceeds the configured line If a `global` or `nonlocal` statement includes multiple names, and exceeds the configured line
@ -385,38 +304,6 @@ global \
analyze_size_model analyze_size_model
``` ```
### Newlines are inserted after all class docstrings
Black typically enforces a single newline after a class docstring. However, it does not apply such
formatting if the docstring is single-quoted rather than triple-quoted, while Ruff enforces a
single newline in both cases:
```python
# Input
class IntFromGeom(GEOSFuncFactory):
"Argument is a geometry, return type is an integer."
argtypes = [GEOM_PTR]
restype = c_int
errcheck = staticmethod(check_minus_one)
# Black
class IntFromGeom(GEOSFuncFactory):
"Argument is a geometry, return type is an integer."
argtypes = [GEOM_PTR]
restype = c_int
errcheck = staticmethod(check_minus_one)
# Ruff
class IntFromGeom(GEOSFuncFactory):
"Argument is a geometry, return type is an integer."
argtypes = [GEOM_PTR]
restype = c_int
errcheck = staticmethod(check_minus_one)
```
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).
### Trailing own-line comments on imports are not moved to the next line ### Trailing own-line comments on imports are not moved to the next line
Black enforces a single empty line between an import and a trailing own-line comment. Ruff leaves Black enforces a single empty line between an import and a trailing own-line comment. Ruff leaves
@ -601,40 +488,6 @@ cases:
Adding parentheses around single-element tuples adds visual distinction and helps avoid "accidental" Adding parentheses around single-element tuples adds visual distinction and helps avoid "accidental"
tuples created by extraneous trailing commas (see, e.g., [#17181](https://github.com/django/django/pull/17181)). tuples created by extraneous trailing commas (see, e.g., [#17181](https://github.com/django/django/pull/17181)).
### Trailing commas are inserted when expanding a function definition with a single argument
When a function definition with a single argument is expanded over multiple lines, Black
will add a trailing comma in some cases, depending on whether the argument includes a type
annotation and/or a default value.
For example, Black will add a trailing comma to the first and second function definitions below,
but not the third:
```python
def func(
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa,
) -> None:
...
def func(
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa=1,
) -> None:
...
def func(
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa: Argument(
"network_messages.pickle",
help="The path of the pickle file that will contain the network messages",
) = 1
) -> None:
...
```
Ruff will instead insert a trailing comma in all such cases for consistency.
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).
### Parentheses around call-chain assignment values are not preserved ### Parentheses around call-chain assignment values are not preserved
@ -866,3 +719,26 @@ with tempfile.TemporaryDirectory() as d1:
): ):
pass pass
``` ```
### Preserving parentheses around single-element lists
Ruff preserves at least one parentheses around list elements, even if the list only contains a single element. The Black 2025 or newer, on the other hand, removes the parentheses
for single-element lists if they aren't multiline and doing so does not change semantics:
```python
# Input
items = [(True)]
items = [(((((True)))))]
items = {(123)}
# Black
items = [True]
items = [True]
items = {123}
# Ruff
items = [(True)]
items = [(True)]
items = {(123)}
```