-## Change Log
+# Change Log
-### 21.4b0
+## Unreleased
-#### _Black_
+### Highlights
+
+<!-- Include any especially major or disruptive changes here -->
+
+### Style
+
+<!-- Changes that affect Black's 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
+
+<!-- Changes that affect Black's 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)
+
+### _Blackd_
+
+<!-- Changes to blackd -->
+
+### Configuration
+
+<!-- Changes to how Black can be configured -->
+
+### Documentation
+
+<!-- Major changes to documentation and policies. Small docs changes
+ don't need a changelog entry. -->
+
+- 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)
+- Recommend using BlackConnect in IntelliJ IDEs (#3150)
+
+### Integrations
+
+<!-- For example, Docker, GitHub Actions, pre-commit, editors -->
+
+### Output
+
+<!-- Changes to Black's terminal output and error messages -->
+
+- Change from deprecated `asyncio.get_event_loop()` to create our event loop which
+ removes DeprecationWarning (#3164)
+
+### Packaging
+
+<!-- Changes to how Black is packaged, such as dependency requirements -->
+
+### Parser
+
+<!-- Changes to the parser or to version autodetection -->
+
+- 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
+
+<!-- Changes that improve Black's performance. -->
+
+## 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](https://peps.python.org/pep-0654/#except) syntax (for example,
+ `except *ExceptionGroup:`) is now supported (#3016)
+- [PEP 646](https://peps.python.org/pep-0646) 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)
+
+## 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](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).
+
+## 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](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)
+
+## 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)
+
+## 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)
+
+## 21.10b0
+
+### _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)
+
+## 21.9b0
+
+### Packaging
+
+- Fix missing modules in self-contained binaries (#2466)
+- Fix missing toml extra used during installation (#2475)
+
+## 21.8b0
+
+### _Black_
+
+- Add support for formatting Jupyter Notebook files (#2357)
+- Move from `appdirs` dependency to `platformdirs` (#2375)
+- Present a more user-friendly error if .gitignore is invalid (#2414)
+- The failsafe for accidentally added backslashes in f-string expressions has been
+ hardened to handle more edge cases during quote normalization (#2437)
+- Avoid changing a function return type annotation's type to a tuple by adding a
+ trailing comma (#2384)
+- Parsing support has been added for unparenthesized walruses in set literals, set
+ comprehensions, and indices (#2447).
+- Pin `setuptools-scm` build-time dependency version (#2457)
+- Exclude typing-extensions version 3.10.0.1 due to it being broken on Python 3.10
+ (#2460)
+
+### _Blackd_
+
+- Replace sys.exit(-1) with raise ImportError as it plays more nicely with tools that
+ scan installed packages (#2440)
+
+### Integrations
+
+- The provided pre-commit hooks no longer specify `language_version` to avoid overriding
+ `default_language_version` (#2430)
+
+## 21.7b0
+
+### _Black_
+
+- Configuration files using TOML features higher than spec v0.5.0 are now supported
+ (#2301)
+- Add primer support and test for code piped into black via STDIN (#2315)
+- Fix internal error when `FORCE_OPTIONAL_PARENTHESES` feature is enabled (#2332)
+- Accept empty stdin (#2346)
+- Provide a more useful error when parsing fails during AST safety checks (#2304)
+
+### Docker
+
+- Add new `latest_release` tag automation to follow latest black release on docker
+ images (#2374)
+
+### Integrations
+
+- The vim plugin now searches upwards from the directory containing the current buffer
+ instead of the current working directory for pyproject.toml. (#1871)
+- The vim plugin now reads the correct string normalization option in pyproject.toml
+ (#1869)
+- The vim plugin no longer crashes Black when there's boolean values in pyproject.toml
+ (#1869)
+
+## 21.6b0
+
+### _Black_
+
+- Fix failure caused by `fmt: skip` and indentation (#2281)
+- Account for += assignment when deciding whether to split string (#2312)
+- Correct max string length calculation when there are string operators (#2292)
+- Fixed option usage when using the `--code` flag (#2259)
+- Do not call `uvloop.install()` when _Black_ is used as a library (#2303)
+- Added `--required-version` option to require a specific version to be running (#2300)
+- Fix incorrect custom breakpoint indices when string group contains fake f-strings
+ (#2311)
+- Fix regression where `R` prefixes would be lowercased for docstrings (#2285)
+- Fix handling of named escapes (`\N{...}`) when `--experimental-string-processing` is
+ used (#2319)
+
+### Integrations
+
+- The official Black action now supports choosing what version to use, and supports the
+ major 3 OSes. (#1940)
+
+## 21.5b2
+
+### _Black_
+
+- A space is no longer inserted into empty docstrings (#2249)
+- Fix handling of .gitignore files containing non-ASCII characters on Windows (#2229)
+- Respect `.gitignore` files in all levels, not only `root/.gitignore` file (apply
+ `.gitignore` rules like `git` does) (#2225)
+- Restored compatibility with Click 8.0 on Python 3.6 when LANG=C used (#2227)
+- Add extra uvloop install + import support if in python env (#2258)
+- Fix --experimental-string-processing crash when matching parens are not found (#2283)
+- Make sure to split lines that start with a string operator (#2286)
+- Fix regular expression that black uses to identify f-expressions (#2287)
+
+### _Blackd_
+
+- Add a lower bound for the `aiohttp-cors` dependency. Only 0.4.0 or higher is
+ supported. (#2231)
+
+### Packaging
+
+- Release self-contained x86_64 MacOS binaries as part of the GitHub release pipeline
+ (#2198)
+- Always build binaries with the latest available Python (#2260)
+
+### Documentation
+
+- Add discussion of magic comments to FAQ page (#2272)
+- `--experimental-string-processing` will be enabled by default in the future (#2273)
+- Fix typos discovered by codespell (#2228)
+- Fix Vim plugin installation instructions. (#2235)
+- Add new Frequently Asked Questions page (#2247)
+- Fix encoding + symlink issues preventing proper build on Windows (#2262)
+
+## 21.5b1
+
+### _Black_
+
+- Refactor `src/black/__init__.py` into many files (#2206)
+
+### Documentation
+
+- Replaced all remaining references to the
+ [`master`](https://github.com/psf/black/tree/main) branch with the
+ [`main`](https://github.com/psf/black/tree/main) branch. Some additional changes in
+ the source code were also made. (#2210)
+- Sigificantly reorganized the documentation to make much more sense. Check them out by
+ heading over to [the stable docs on RTD](https://black.readthedocs.io/en/stable/).
+ (#2174)
+
+## 21.5b0
+
+### _Black_
+
+- Set `--pyi` mode if `--stdin-filename` ends in `.pyi` (#2169)
+- Stop detecting target version as Python 3.9+ with pre-PEP-614 decorators that are
+ being called but with no arguments (#2182)
+
+### _Black-Primer_
+
+- Add `--no-diff` to black-primer to suppress formatting changes (#2187)
+
+## 21.4b2
+
+### _Black_
+
+- Fix crash if the user configuration directory is inaccessible. (#2158)
+
+- Clarify
+ [circumstances](https://github.com/psf/black/blob/master/docs/the_black_code_style.md#pragmatism)
+ in which _Black_ may change the AST (#2159)
+
+- Allow `.gitignore` rules to be overridden by specifying `exclude` in `pyproject.toml`
+ or on the command line. (#2170)
+
+### _Packaging_
+
+- Install `primer.json` (used by `black-primer` by default) with black. (#2154)
+
+## 21.4b1
+
+### _Black_
+
+- Fix crash on docstrings ending with "\\ ". (#2142)
+
+- Fix crash when atypical whitespace is cleaned out of dostrings (#2120)
+
+- Reflect the `--skip-magic-trailing-comma` and `--experimental-string-processing` flags
+ in the name of the cache file. Without this fix, changes in these flags would not take
+ effect if the cache had already been populated. (#2131)
+
+- Don't remove necessary parentheses from assignment expression containing assert /
+ return statements. (#2143)
+
+### _Packaging_
+
+- Bump pathspec to >= 0.8.1 to solve invalid .gitignore exclusion handling
+
+## 21.4b0
+
+### _Black_
- Fixed a rare but annoying formatting instability created by the combination of
optional trailing commas inserted by `Black` and optional parentheses looking at
- Fixed "Black produced code that is not equivalent to the source" when formatting
Python 2 docstrings (#2037)
-#### _Packaging_
+### _Packaging_
- Self-contained native _Black_ binaries are now provided for releases via GitHub
Releases (#1743)
-### 20.8b1
+## 20.8b1
-#### _Packaging_
+### _Packaging_
- explicitly depend on Click 7.1.2 or newer as `Black` no longer works with versions
older than 7.0
-### 20.8b0
+## 20.8b0
-#### _Black_
+### _Black_
- re-implemented support for explicit trailing commas: now it works consistently within
any bracket pair, including nested structures (#1288 and duplicates)
this is an undocumented and unsupported feature, you lose Internet points for
depending on it (#1609)
-#### Vim plugin
+### Vim plugin
- prefer virtualenv packages over global packages (#1383)
-### 19.10b0
+## 19.10b0
- added support for PEP 572 assignment expressions (#711)
- `blackd` can now output the diff of formats on source code when the `X-Diff` header is
provided (#969)
-### 19.3b0
+## 19.3b0
- new option `--target-version` to control which Python versions _Black_-formatted code
should target (#618)
- `blackd` now supports CORS (#622)
-### 18.9b0
+## 18.9b0
- numeric literals are now formatted by _Black_ (#452, #461, #464, #469):
- hexadecimal digits are always uppercased (e.g. `0xBADC0DE`)
-- added `blackd`, see [its documentation](#blackd) for more info (#349)
+- added `blackd`, see
+ [its documentation](https://github.com/psf/black/blob/18.9b0/README.md#blackd) for
+ more info (#349)
- adjacent string literals are now correctly split into multiple lines (#463)
- note: the Vim plugin stopped registering `,=` as a default chord as it turned out to
be a bad idea (#415)
-### 18.6b4
+## 18.6b4
- hotfix: don't freeze when multiple comments directly precede `# fmt: off` (#371)
-### 18.6b3
+## 18.6b3
- typing stub files (`.pyi`) now have blank lines added after constants (#340)
- fixed a crash due to symbolic links pointing outside of the project directory (#338)
-### 18.6b2
+## 18.6b2
- added `--config` (#65)
- fixed unnecessary slowdown in comment placement calculation on lines without comments
-### 18.6b1
+## 18.6b1
- hotfix: don't output human-facing information on stdout (#299)
- hotfix: don't output cake emoji on non-zero return code (#300)
-### 18.6b0
+## 18.6b0
- added `--include` and `--exclude` (#270)
- _Black_ now preserves line endings when formatting a file in place (#258)
-### 18.5b1
+## 18.5b1
- added `--pyi` (#249)
- fixed extra empty line between a function signature and an inner function or inner
class (#196)
-### 18.5b0
+## 18.5b0
- call chains are now formatted according to the
[fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface) style (#67)
- fixed crash when dead symlinks where encountered
-### 18.4a4
+## 18.4a4
- don't populate the cache on `--check` (#175)
-### 18.4a3
+## 18.4a3
- added a "cache"; files already reformatted that haven't changed on disk won't be
reformatted again (#109)
- fixed missing splits of ternary expressions (#141)
-### 18.4a2
+## 18.4a2
- fixed parsing of unaligned standalone comments (#99, #112)
- fixed unstable formatting when encountering unnecessarily escaped quotes in a string
(#120)
-### 18.4a1
+## 18.4a1
- added `--quiet` (#78)
- fixed removing backslash escapes from raw strings (#100, #105)
-### 18.4a0
+## 18.4a0
- added `--diff` (#87)
- only allow up to two empty lines on module level and only single empty lines within
functions (#74)
-### 18.3a4
+## 18.3a4
- `# fmt: off` and `# fmt: on` are implemented (#5)
[Sphinx auto-attribute comments](http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-autoattribute)
(#68)
-### 18.3a3
+## 18.3a3
- don't remove single empty lines outside of bracketed expressions (#19)
- even better handling of numpy-style array indexing (#33, again)
-### 18.3a2
+## 18.3a2
- changed positioning of binary operators to occur at beginning of lines instead of at
the end, following
- fixed spurious space after star-based unary expressions (#31)
-### 18.3a1
+## 18.3a1
- added `--check`
- fixed spurious space after unary operators when the operand was a complex expression
(#15)
-### 18.3a0
+## 18.3a0
- first published version, Happy 🍰 Day 2018!
- alpha quality
-- date-versioned (see: https://calver.org/)
+- date-versioned (see: <https://calver.org/>)
projects / etc / vim.git / blobdiff