23.1a1

This release provides a preview of Black's 2023 stable style. Black's default formatting style includes the following changes:

• Enforce empty lines before classes and functions with sticky leading comments
  (#3302) (22.12.0)
• Reformat empty and whitespace-only files as either an empty file (if no newline is
  present) or as a single newline character (if a newline is present) (#3348)
  (22.12.0)
• Implicitly concatenated strings used as function args are now wrapped inside
  parentheses (#3307) (22.12.0)
• Correctly handle trailing commas that are inside a line's leading non-nested parens
  (#3370) (22.12.0)
• --skip-string-normalization / -S now prevents docstring prefixes from being
  normalized as expected (#3168) (since 22.8.0)
• When using --skip-magic-trailing-comma or -C, trailing commas are stripped from
  subscript expressions with more than 1 element (#3209) (22.8.0)
• Implicitly concatenated strings inside a list, set, or tuple are now wrapped inside
  parentheses (#3162) (22.8.0)
• Fix a string merging/split issue when a comment is present in the middle of
  implicitly concatenated strings on its own line (#3227) (22.8.0)
• Docstring quotes are no longer moved if it would violate the line length limit
  (#3044, #3430) (22.6.0)
• Parentheses around return annotations are now managed (#2990) (22.6.0)
• Remove unnecessary parentheses around awaited objects (#2991) (22.6.0)
• Remove unnecessary parentheses in with statements (#2926) (22.6.0)
• Remove trailing newlines after code block open (#3035) (22.6.0)
• Code cell separators #%% are now standardised to # %% (#2919) (22.3.0)
• Remove unnecessary parentheses from except statements (#2939) (22.3.0)
• Remove unnecessary parentheses from tuple unpacking in for loops (#2945) (22.3.0)
• Avoid magic-trailing-comma in single-element subscripts (#2942) (22.3.0)

Please try it out and give feedback here: #3407

A stable 23.1.0 release will follow in January 2023.

22.12.0

Preview style

• Enforce empty lines before classes and functions with sticky leading comments (#3302)
• Reformat empty and whitespace-only files as either an empty file (if no newline is
  present) or as a single newline character (if a newline is present) (#3348)
• Implicitly concatenated strings used as function args are now wrapped inside
  parentheses (#3307)
• Correctly handle trailing commas that are inside a line's leading non-nested parens
  (#3370)

Configuration

• Fix incorrectly applied .gitignore rules by considering the .gitignore location
  and the relative path to the target file (#3338)
• Fix incorrectly ignoring .gitignore presence when more than one source directory is
  specified (#3336)

Parser

• Parsing support has been added for walruses inside generator expression that are
  passed as function args (for example,
  any(match := my_re.match(text) for text in texts)) (#3327).

Integrations

• Vim plugin: Optionally allow using the system installation of Black via
  let g:black_use_virtualenv = 0(#3309)

22.10.0

22.10.0

Highlights

• Runtime support for Python 3.6 has been removed. Formatting 3.6 code will still be
  supported until further notice.

Stable style

• Fix a crash when # fmt: on is used on a different block level than # fmt: off
  (#3281)

Preview style

• Fix a crash when formatting some dicts with parenthesis-wrapped long string keys
  (#3262)

Configuration

• .ipynb_checkpoints directories are now excluded by default (#3293)
• Add --skip-source-first-line / -x option to ignore the first line of source code
  while formatting (#3299)

Packaging

• Executables made with PyInstaller will no longer crash when formatting several files
  at once on macOS. Native x86-64 executables for macOS are available once again.
  (#3275)
• Hatchling is now used as the build backend. This will not have any effect for users
  who install Black with its wheels from PyPI. (#3233)
• Faster compiled wheels are now available for CPython 3.11 (#3276)

Blackd

• Windows style (CRLF) newlines will be preserved (#3257).

Integrations

• Vim plugin: add flag (g:black_preview) to enable/disable the preview style (#3246)
• Update GitHub Action to support formatting of Jupyter Notebook files via a jupyter
  option (#3282)
• Update GitHub Action to support use of version specifiers (e.g. <23) for Black
  version (#3265)

22.8.0

Highlights

• Python 3.11 is now supported, except for blackd as aiohttp does not support 3.11 as of publishing (#3234)
• This is the last release that supports running Black on Python 3.6 (formatting 3.6 code will continue to be supported until further notice)
• Reword the stability policy to say that we may, in rare cases, make changes that affect code that was not previously formatted by Black (#3155)

Stable style

• Fix an infinite loop when using # fmt: on/off in the middle of an expression or code block (#3158)
• Fix incorrect handling of # fmt: skip on colon (:) lines (#3148)
• Comments are no longer deleted when a line had spaces removed around power operators (#2874)

Preview style

• Single-character closing docstring quotes are no longer moved to their own line as this is invalid. This was a bug introduced in version 22.6.0. (#3166)
• --skip-string-normalization / -S now prevents docstring prefixes from being normalized as expected (#3168)
• When using --skip-magic-trailing-comma or -C, trailing commas are stripped from subscript expressions with more than 1 element (#3209)
• Implicitly concatenated strings inside a list, set, or tuple are now wrapped inside parentheses (#3162)
• Fix a string merging/split issue when a comment is present in the middle of implicitly concatenated strings on its own line (#3227)

Blackd

• blackd now supports enabling the preview style via the X-Preview header (#3217)

Configuration

• Black now uses the presence of debug f-strings to detect target version (#3215)
• Fix misdetection of project root and verbose logging of sources in cases involving --stdin-filename (#3216)
• Immediate .gitignore files in source directories given on the command line are now also respected, previously only .gitignore files in the project root and automatically discovered directories were respected (#3237)

Documentation

• Recommend using BlackConnect in IntelliJ IDEs (#3150)

Integrations

• Vim plugin: prefix messages with Black: so it's clear they come from Black (#3194)
• Docker: changed to a /opt/venv installation + added to PATH to be available to non-root users (#3202)

Output

• Change from deprecated asyncio.get_event_loop() to create our event loop which removes DeprecationWarning (#3164)
• Remove logging from internal blib2to3 library since it regularly emits error logs about failed caching that can and should be ignored (#3193)

Parser

• Type comments are now included in the AST equivalence check consistently so accidental deletion raises an error. Though type comments can't be tracked when running on PyPy 3.7 due to standard library limitations. (#2874)

Performance

• Reduce Black's startup time when formatting a single file by 15-30% (#3211)

Full Changelog: 22.6.0...22.8.0

---

Thank you!

• @hauntsaninja for modernizing our type annotations and fixing a few bugs too
• @yilei for fixing our # fmt: off/on/skip code and continuing to improve the preview style, notably the (still) experimental string processing
• The many community contributions to the non-core parts of the project:
  • @tobast for improving the QOL of the Vim plugin by simply appending Black: to most emitted messages
  • @Mogost for adding preview style support to blackd (finally 🎉)
  • @n-borges for improving the Docker image
  • @ionite34 for removing a hack in the official Black GitHub Action's start up code
• @cooperlees for adding support for Python 3.11 and addressing DeprecationWarnings
• @graingert for adding PyPy 3.8 to our CI matrix so we know Black works in even more places
• @martinResearch for contributing a simple fix for such a silly and stupid .gitignore bug that we should've caught many moons ago
• @fabioz for contributing the original patch that reduced the start up overhead when formatting a single file by 15-30% (!)

... and everyone else who contributed documentation, tests, or other improvements to the Black project!

Finally congratulations to the first time contributors this time around!

• @dmerejkowsky made their first contribution in #3142
• @m-aciek made their first contribution in #3150
• @Panther-12 made their first contribution in #3167
• @onescriptkid made their first contribution in #3170
• @tobast made their first contribution in #3194
• @n-borges made their first contribution in #3202
• @Mogost made their first contribution in #3217
• @ionite34 made their first contribution in #3226
• @martinResearch made their first contribution in #3237

22.6.0

Style

• Fix unstable formatting involving #fmt: skip and # fmt:skip comments (notice the lack of spaces) (#2970)

Preview style

• Docstring quotes are no longer moved if it would violate the line length limit (#3044)
• Parentheses around return annotations are now managed (#2990)
• Remove unnecessary parentheses around awaited objects (#2991)
• Remove unnecessary parentheses in with statements (#2926)
• Remove trailing newlines after code block open (#3035)

Integrations

• Add scripts/migrate-black.py script to ease introduction of Black to a Git project (#3038)

Output

• Output Python version and implementation as part of --version flag (#2997)

Packaging

• Use tomli instead of tomllib on Python 3.11 builds where tomllib is not available (#2987)

Parser

• PEP 654 syntax (for example, except *ExceptionGroup:) is now supported (#3016)
• PEP 646 syntax (for example, Array[Batch, *Shape] or def fn(*args: *T) -> None) is now supported (#3071)

Vim Plugin

• Fix strtobool function. It didn't parse true/on/false/off. (#3025)

Full Changelog: 22.3.0...22.6.0

---

Thank you!

• @jpy-git for improving our parentheses formatting significantly
• @siuryan for fixing a fmt: skip bug, making it a little less annoying to use :)
• @isidentical for implementing support for PEP 654 and 646 syntax
• @defntvdm for fixing our vim plugin, especially as we (the maintainers) don't really know vim script sadly
• @idorrington92 for fixing the docstring bug where Black would move the closing quotes causing it to violate the line length limit (whoops!)
• @hbrunn for contributing the migrate-black script
• @saroad2 for improving newline handling after code blocks and test infrastructure improvements

... and everyone else who contributed documentation, tests, or other improvements to the Black project!

Finally congrats to first contributors!

• @kolibril13 made their first contribution in #2982
• @siuryan made their first contribution in #2970
• @dignissimus made their first contribution in #3007
• @JiriKr made their first contribution in #3023
• @defntvdm made their first contribution in #3025
• @naveensrinivasan made their first contribution in #3043
• @idorrington92 made their first contribution in #3044
• @laundmo made their first contribution in #3063
• @ysk24ok made their first contribution in #3070
• @hbrunn made their first contribution in #3038
• @vivekvashist made their first contribution in #3096
• @nateprewitt made their first contribution in #3125
• @yilei made their first contribution in #3135

22.3.0

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 (#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).

22.1.0

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.

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 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 as Black crashes on 7.1.2 (#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)

Full Changelog: 21.12b0...22.1.0

---

Thank you!

• @isidentical for their continued work on making our Python 3.10 support better than ever (we made them a co-maintainer 🎉)
• @hauntsaninja for their help improving our stub style
• @nipunn1313 making Black more stable (which has been a long running battle)
• .. and all of my fellow co-maintainers who have made working on this project a wonderful ride @JelleZijlstra @cooperlees @felix-hilden @ambv @zsol

And also congrats to first contributors!

• @mwtoews made their first contribution in #2701
• @gunungpw made their first contribution in #2733
• @joshowen made their first contribution in #2748
• @Shivansh-007 made their first contribution in #2526
• @cbows made their first contribution in #2761
• @jlazar17 made their first contribution in #2765
• @VanSHOE made their first contribution in #2712
• @emfdavid made their first contribution in #2786
• @mgmarino made their first contribution in #2744
• @RHammond2 made their first contribution in #2792
• @percurnicus made their first contribution in #2739
• @sobolevn made their first contribution in #2802

21.12b0

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)

---

Thank you!

• @isidentical for the polishing up 3.10 syntax support (which they contributed in the first place!)
• @MarcoGorelli for their ever-continuing work on Black's jupyter support
• @jalaziz for cleaning up our Pyinstaller CD workflow
• @hauntsaninja for helping us drop the regex dependency

And also congrats to first contributors!

• @MatthewScholefield made their first contribution in #2631
• @AshIsbitt made their first contribution in #2632
• @kalbasit made their first contribution in #2638
• @danieleades made their first contribution in #2653
• @danielsparing made their first contribution in #2630
• @tanvimoharir made their first contribution in #2343

21.11b1

Black

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

21.11b0

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)