Skip to content

Commit

Permalink
Update black deviations (#15928)
Browse files Browse the repository at this point in the history
  • Loading branch information
@MichaReiser
MichaReiser authored Feb 4, 2025
1 parent cc60701 commit ff87ea8
Showing 1 changed file with 23 additions and 147 deletions.
170 changes: 23 additions & 147 deletions docs/formatter/black.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).

### 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

Expand Down Expand Up @@ -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

If a `global` or `nonlocal` statement includes multiple names, and exceeds the configured line
Expand All @@ -385,38 +304,6 @@ global \
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

Black enforces a single empty line between an import and a trailing own-line comment. Ruff leaves
Expand Down Expand Up @@ -601,40 +488,6 @@ cases:
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)).

### 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

Expand Down Expand Up @@ -866,3 +719,26 @@ with tempfile.TemporaryDirectory() as d1:
):
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)}

```

0 comments on commit ff87ea8

Please sign in to comment.