Blackish

Preview style

- Code cell separators `%%` are now standardised to ` %%` (2919)
- Remove unnecessary parentheses from `except` statements (2939)
- Remove unnecessary parentheses from tuple unpacking in `for` loops (2945)
- Avoid magic-trailing-comma in single-element subscripts (2942)

Configuration

- Do not format `__pypackages__` directories by default (2836)
- Add support for specifying stable version with `--required-version` (2832).
- Avoid crashing when the user has no homedir (2814)
- Avoid crashing when md5 is not available (2905)
- Fix handling of directory junctions on Windows (2904)

Documentation

- Update pylint config documentation (2931)

Integrations

- Move test to disable plugin in Vim/Neovim, which speeds up loading (2896)

Output

- In verbose, mode, log when _Black_ is using user-level config (2861)

Packaging

- Fix Black to work with Click 8.1.0 (2966)
- On Python 3.11 and newer, use the standard library's `tomllib` instead of `tomli`
(2903)
- `black-primer`, the deprecated internal devtool, has been removed and copied to a
[separate repository](https://github.com/cooperlees/black-primer) (#2924)

Parser

- Black can now parse starred expressions in the target of `for` and `async for`
statements, e.g `for item in *items_1, *items_2: pass` (2879).

At long last, _Black_ is no longer a beta product! This is the first non-beta release
and the first release covered by our new
[stability policy](https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy).

Highlights

- **Remove Python 2 support** (2740)
- Introduce the `--preview` flag (2752)

Style

- Deprecate `--experimental-string-processing` and move the functionality under
`--preview` (2789)
- For stubs, one blank line between class attributes and methods is now kept if there's
at least one pre-existing blank line (2736)
- Black now normalizes string prefix order (2297)
- Remove spaces around power operators if both operands are simple (2726)
- Work around bug that causes unstable formatting in some cases in the presence of the
magic trailing comma (2807)
- Use parentheses for attribute access on decimal float and int literals (2799)
- Don't add whitespace for attribute access on hexadecimal, binary, octal, and complex
literals (2799)
- Treat blank lines in stubs the same inside top-level `if` statements (2820)
- Fix unstable formatting with semicolons and arithmetic expressions (2817)
- Fix unstable formatting around magic trailing comma (2572)

Parser

- Fix mapping cases that contain as-expressions, like `case {"key": 1 | 2 as password}`
(2686)
- Fix cases that contain multiple top-level as-expressions, like `case 1 as a, 2 as b`
(2716)
- Fix call patterns that contain as-expressions with keyword arguments, like
`case Foo(bar=baz as quux)` (2749)
- Tuple unpacking on `return` and `yield` constructs now implies 3.8+ (2700)
- Unparenthesized tuples on annotated assignments (e.g
`values: Tuple[int, ...] = 1, 2, 3`) now implies 3.8+ (2708)
- Fix handling of standalone `match()` or `case()` when there is a trailing newline or a
comment inside of the parentheses. (2760)
- `from __future__ import annotations` statement now implies Python 3.7+ (2690)

Performance

- Speed-up the new backtracking parser about 4X in general (enabled when
`--target-version` is set to 3.10 and higher). (2728)
- _Black_ is now compiled with [mypyc](https://github.com/mypyc/mypyc) for an overall 2x
speed-up. 64-bit Windows, MacOS, and Linux (not including musl) are supported. (1009,
2431)

Configuration

- Do not accept bare carriage return line endings in pyproject.toml (2408)
- Add configuration option (`python-cell-magics`) to format cells with custom magics in
Jupyter Notebooks (2744)
- Allow setting custom cache directory on all platforms with environment variable
`BLACK_CACHE_DIR` (2739).
- Enable Python 3.10+ by default, without any extra need to specify
`--target-version=py310`. (2758)
- Make passing `SRC` or `--code` mandatory and mutually exclusive (2804)

Output

- Improve error message for invalid regular expression (2678)
- Improve error message when parsing fails during AST safety check by embedding the
underlying SyntaxError (2693)
- No longer color diff headers white as it's unreadable in light themed terminals
(2691)
- Text coloring added in the final statistics (2712)
- Verbose mode also now describes how a project root was discovered and which paths will
be formatted. (2526)

Packaging

- All upper version bounds on dependencies have been removed (2718)
- `typing-extensions` is no longer a required dependency in Python 3.10+ (2772)
- Set `click` lower bound to `8.0.0` (2791)

Integrations

- Update GitHub action to support containerized runs (2748)

Documentation

- Change protocol in pip installation instructions to `https://` (#2761)
- Change HTML theme to Furo primarily for its responsive design and mobile support
(2793)
- Deprecate the `black-primer` tool (2809)
- Document Python support policy (2819)

_Black_

- Fix determination of f-string expression spans (2654)
- Fix bad formatting of error messages about EOF in multi-line statements (2343)
- Functions and classes in blocks now have more consistent surrounding spacing (2472)

Jupyter Notebook support

- Cell magics are now only processed if they are known Python cell magics. Earlier, all
cell magics were tokenized, leading to possible indentation errors e.g. with
`%%writefile`. (2630)
- Fix assignment to environment variables in Jupyter Notebooks (2642)

Python 3.10 support

- Point users to using `--target-version py310` if we detect 3.10-only syntax (2668)
- Fix `match` statements with open sequence subjects, like `match a, b:` or
`match a, *b:` (2639) (2659)
- Fix `match`/`case` statements that contain `match`/`case` soft keywords multiple
times, like `match re.match()` (2661)
- Fix `case` statements with an inline body (2665)
- Fix styling of starred expressions inside `match` subject (2667)
- Fix parser error location on invalid syntax in a `match` statement (2649)
- Fix Python 3.10 support on platforms without ProcessPoolExecutor (2631)
- Improve parsing performance on code that uses `match` under `--target-version py310`
up to ~50% (2670)

Packaging

- Remove dependency on `regex` (2644) (2663)

_Black_

- Bumped regex version minimum to 2021.4.4 to fix Pattern class usage (2621)

_Black_

- Warn about Python 2 deprecation in more cases by improving Python 2 only syntax
detection (2592)
- Add experimental PyPy support (2559)
- Add partial support for the match statement. As it's experimental, it's only enabled
when `--target-version py310` is explicitly specified (2586)
- Add support for parenthesized with (2586)
- Declare support for Python 3.10 for running Black (2562)

Integrations

- Fixed vim plugin with Python 3.10 by removing deprecated distutils import (2610)
- The vim plugin now parses `skip_magic_trailing_comma` from pyproject.toml (2613)

_Black_

- Document stability policy, that will apply for non-beta releases (2529)
- Add new `--workers` parameter (2514)
- Fixed feature detection for positional-only arguments in lambdas (2532)
- Bumped typed-ast version minimum to 1.4.3 for 3.10 compatibility (2519)
- Fixed a Python 3.10 compatibility issue where the loop argument was still being passed
even though it has been removed (2580)
- Deprecate Python 2 formatting support (2523)

_Blackd_

- Remove dependency on aiohttp-cors (2500)
- Bump required aiohttp version to 3.7.4 (2509)

_Black-Primer_

- Add primer support for --projects (2555)
- Print primer summary after individual failures (2570)

Integrations

- Allow to pass `target_version` in the vim plugin (1319)
- Install build tools in docker file and use multi-stage build to keep the image size
down (2582)