Black

Highlights

This release introduces the new 2025 stable style (4558), stabilizing
the following changes:

- Normalize casing of Unicode escape characters in strings to lowercase (2916)
- Fix inconsistencies in whether certain strings are detected as docstrings (4095)
- Consistently add trailing commas to typed function parameters (4164)
- Remove redundant parentheses in if guards for case blocks (4214)
- Add parentheses to if clauses in case blocks when the line is too long (4269)
- Whitespace before ` fmt: skip` comments is no longer normalized (4146)
- Fix line length computation for certain expressions that involve the power operator (4154)
- Check if there is a newline before the terminating quotes of a docstring (4185)
- Fix type annotation spacing between `*` and more complex type variable tuple (4440)

The following changes were not in any previous release:

- Remove parentheses around sole list items (4312)
- Generic function definitions are now formatted more elegantly: parameters are
split over multiple lines first instead of type parameter definitions (4553)

Stable style

- Fix formatting cells in IPython notebooks with magic methods and starting or trailing
empty lines (4484)
- Fix crash when formatting `with` statements containing tuple generators/unpacking
(4538)

Preview style

- Fix/remove string merging changing f-string quotes on f-strings with internal quotes
(4498)
- Collapse multiple empty lines after an import into one (4489)
- Prevent `string_processing` and `wrap_long_dict_values_in_parens` from removing
parentheses around long dictionary values (4377)
- Move `wrap_long_dict_values_in_parens` from the unstable to preview style (4561)

Packaging

- Store license identifier inside the `License-Expression` metadata field, see
[PEP 639](https://peps.python.org/pep-0639/). (#4479)

Performance

- Speed up the `is_fstring_start` function in Black's tokenizer (4541)

Integrations

- If using stdin with `--stdin-filename` set to a force excluded path, stdin won't be
formatted. (4539)

Highlights

- Black is now officially tested with Python 3.13 and provides Python 3.13
mypyc-compiled wheels. (4436) (4449)
- Black will issue an error when used with Python 3.12.5, due to an upstream memory
safety issue in Python 3.12.5 that can cause Black's AST safety checks to fail. Please
use Python 3.12.6 or Python 3.12.4 instead. (4447)
- Black no longer supports running with Python 3.8 (4452)

Stable style

- Fix crashes involving comments in parenthesised return types or `X | Y` style unions.
(4453)
- Fix skipping Jupyter cells with unknown `%%` magic (4462)

Preview style

- Fix type annotation spacing between * and more complex type variable tuple (i.e. `def
fn(*args: *tuple[*Ts, T]) -> None: pass`) (4440)

Caching

- Fix bug where the cache was shared between runs with and without `--unstable` (4466)

Packaging

- Upgrade version of mypyc used to 1.12 beta (4450) (4449)
- `blackd` now requires a newer version of aiohttp. (4451)

Output

- Added Python target version information on parse error (4378)
- Add information about Black version to internal error messages (4457)

Stable style

- Fix crash when ` fmt: off` is used before a closing parenthesis or bracket. (4363)

Packaging

- Packaging metadata updated: docs are explictly linked, the issue tracker is now also
linked. This improves the PyPI listing for Black. (4345)

Parser

- Fix regression where Black failed to parse a multiline f-string containing another
multiline string (4339)
- Fix regression where Black failed to parse an escaped single quote inside an f-string
(4401)
- Fix bug with Black incorrectly parsing empty lines with a backslash (4343)
- Fix bugs with Black's tokenizer not handling `\{` inside f-strings very well (4422)
- Fix incorrect line numbers in the tokenizer for certain tokens within f-strings
(4423)

Performance

- Improve performance when a large directory is listed in `.gitignore` (4415)

_Blackd_

- Fix blackd (and all extras installs) for docker container (4357)

This is a bugfix release to fix two regressions in the new f-string parser introduced in
24.4.1.

Parser

- Fix regression where certain complex f-strings failed to parse (4332)

Performance

- Fix bad performance on certain complex string literals (4331)

Highlights

- Add support for the new Python 3.12 f-string syntax introduced by PEP 701 (3822)

Stable style

- Fix crash involving indented dummy functions containing newlines (4318)

Parser

- Add support for type parameter defaults, a new syntactic feature added to Python 3.13
by PEP 696 (4327)

Integrations

- Github Action now works even when `git archive` is skipped (4313)

Stable style

- Fix unwanted crashes caused by AST equivalency check (4290)

Preview style

- `if` guards in `case` blocks are now wrapped in parentheses when the line is too long.
(4269)
- Stop moving multiline strings to a new line unless inside brackets (4289)

Integrations

- Add a new option `use_pyproject` to the GitHub Action `psf/black`. This will read the
Black version from `pyproject.toml`. (4294)