无妥协的代码格式化工具

“您喜欢的任何颜色。”

Black 是无妥协的 Python 代码格式化工具。通过使用它，您同意放弃手动格式化的细节控制。作为回报，Black 会给您速度、确定性，并免除 pycodestyle 关于格式的唠叨。您可以为更重要的事情节省时间和精神能量。

无论您阅读的项目是什么，格式化后的代码看起来都一样。一段时间后，格式化就变得透明了，您就可以专注于内容。

Black 通过产生尽可能小的差异来使代码审查更快。

现在就试试 Black游乐场。观看 PyCon 2019 演讲 了解更多信息。

在ReadTheDocs上阅读文档！

安装和用法

安装

Black 可以通过运行 pip install black 来安装。它需要 Python 3.8+ 才能运行。如果您想格式化 Jupyter Notebooks，请使用 pip install "black[jupyter]" 安装。

如果您迫不及待想要安装最新版本并从 GitHub 安装，请使用以下命令：

pip install git+https://github.com/psf/black

用法

要立即开始使用合理的默认值

black {source_file_or_directory}

如果以脚本方式运行不工作，您可以将其作为包运行 Black

python -m black {source_file_or_directory}

更多信息可以在我们的文档中找到

• 用法和配置

Black 已经被许多项目，无论大小，成功使用。 Black 有一个全面的测试套件，包括高效的并行测试，以及我们自己的自动格式化和并行持续集成运行器。现在我们已经变得稳定，您不应该期望未来会有大的格式化变化。风格变化将主要是对错误报告的响应和对新 Python 语法的支持。有关更多信息，请参阅Black 代码风格。

此外，作为一项安全措施，以减慢处理速度，Black 将检查重新格式化后的代码仍然产生一个有效的 AST，该 AST 实际上与原始代码等效（有关详细信息，请参阅 实用主义 部分）。如果您感到自信，请使用 --fast。

Black 代码风格

Black 是一个符合 PEP 8 的有偏见的格式化工具。 Black 在原地重新格式化整个文件。风格配置选项被故意限制并很少添加。它不考虑先前的格式（有关例外，请参阅 实用主义）。

我们的文档涵盖了当前的 Black 代码风格，但对其的预期变更也已记录。两者都值得一看

• Black 代码风格：当前风格
• Black 代码风格：未来风格

Black 代码风格变更受稳定性政策的约束

• Black 代码风格：稳定性政策

在提交问题之前，请参阅此文档。看起来像错误的行为可能是故意的行为。

实用主义

Black 的早期版本在某种程度上是绝对主义的。它遵循其最初的作者。在当时这是可以接受的，因为它使实现更简单，而且用户本来就不多。没有报告很多边缘情况。作为一个成熟的工具，Black 在其他方面也会对规则做出一些例外。

• Black 代码风格：实用主义

在提交问题之前，请像上面的文档一样参考此文档。看似是错误的可能是有意为之的行为。

配置

Black 能够从 pyproject.toml 文件中读取其命令行选项的项目特定默认值。这对于指定项目自定义的 --include 和 --exclude/--force-exclude/--extend-exclude 模式非常有用。

更多详细信息请参阅我们的文档

• 基本概念：通过文件进行配置

如果您正在寻找更通用的配置文档

• 用法和配置

小贴士：如果您在问自己“我需要配置什么吗？”那么答案是“不”。 Black 专注于合理的默认值。应用这些默认值将使您的代码符合许多其他 Black 格式的项目。

使用情况

以下知名的开源项目信任 Black 来强制执行一致的代码风格：pytest、tox、Pyramid、Django、Django Channels、Hypothesis、attrs、SQLAlchemy、Poetry、PyPA 应用程序（Warehouse、Bandersnatch、Pipenv、virtualenv）、pandas、Pillow、Twisted、LocalStack、每个 Datadog Agent 集成、Home Assistant、Zulip、Kedro、OpenOA、FLORIS、ORBIT、WOMBAT，等等。

以下组织使用 Black：Facebook、Dropbox、KeepTruckin、Lyft、Mozilla、Quora、Duolingo、QuantumBlack、Tesla、Archer Aviation。

我们遗漏了谁吗？告诉我们。

客户评价

Mike Bayer，《SQLAlchemy》的作者

在我的整个编程生涯中，我无法想到任何工具能通过其引入带来如此大的生产力提升。我现在可以用大约1%的按键来完成之前在没有代码格式化的方法时需要的大量重构。

Dusty Phillips，作家

Black 有自己的观点，所以您不需要。

Hynek Schlawack，《attrs》的创建者，Twisted 和 CPython 的核心开发者

圣诞节的愿望就是一个不糟糕的自动格式化工具！

Carl Meyer，Django 核心开发者

至少名字不错。

Kenneth Reitz，requests 和 pipenv 的创建者

这极大地提高了我们代码的格式化。非常感谢！

展示您的风格

在项目的 README.md 中使用徽章

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

在 README.rst 中使用徽章

.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :target: https://github.com/psf/black

看起来像这样：

许可证

MIT 许可证

贡献

欢迎！很高兴看到您愿意让项目变得更好。您可以通过阅读以下内容开始

• 贡献：基本概念

您还可以查看其他贡献文档或与开发者交谈

• 贡献文档
• 在 Discord 上聊天

变更日志

日志已经相当长。它已经移动到自己的文件。

见 CHANGES。

作者

作者名单现在相当长，所以它住在自己的文件里。

见 AUTHORS.md

行为准则

所有参与 Black 项目的人，特别是参与问题跟踪、拉取请求和社交媒体活动的人，都应尊重他人，并更普遍地遵循 Python 社区行为准则 中阐述的指南。

同时，幽默是受到鼓励的。事实上，对 Monty Python 的《蒙提·派森飞行马戏团》的基本熟悉是期望的。我们不是野蛮人。

如果您真的需要打某人，请一边跳舞一边用鱼打。

变更日志

24.8.0

稳定风格

• 修复在括号或方括号之前使用 # fmt: off 时的崩溃问题。（#4363）

包装

• 包装元数据已更新：文档已明确链接，问题跟踪器也已链接。这改善了 Black 在 PyPI 上的列表。（#4345）

解析器

• 修复了 Black 无法解析包含另一个多行字符串的多行 f-string 的回归问题。（#4339）
• 修复了 Black 无法解析 f-string 内转义的单引号的回归问题。（#4401）
• 修复了 Black 错误解析包含反斜杠的空行的漏洞。（#4343）
• 修复了 Black 的词法分析器在 f-string 中处理 \{ 不好的漏洞。（#4422）
• 修复了词法分析器中某些 f-string 内的特定标记的行号错误。（#4423）

性能

• 当大目录在 .gitignore 中列出时，改进了性能。（#4415）

Blackd

• 修复了 Blackd（以及所有额外安装）在 Docker 容器中的问题。（#4357）

24.4.2

这是一个修复漏洞的版本，用于修复 24.4.1 中引入的新 f-string 解析器引入的两个回归问题。

解析器

• 修复了某些复杂 f-string 解析失败的回归问题。（#4332）

性能

• 修复了某些复杂字符串字面量性能不良的问题。（#4331）

24.4.1

亮点

• 添加了对由 PEP 701 引入的新 Python 3.12 f-string 语法支持。（#3822）

稳定风格

• 修复了涉及缩进哑函数和新行引起崩溃的问题。（#4318）

解析器

• 添加了对 Python 3.13 中由 PEP 696 添加的新语法特性类型参数默认值支持。（#4327）

集成

• Github Action 现在即使在跳过 git archive 的情况下也能工作。（#4313）

24.4.0

稳定风格

• 修复了由 AST 等价性检查引起的不希望崩溃的问题。（#4290）

预览样式

• 当行太长时，现在将 if 守卫括号包裹在圆括号中。（#4269）
• 除非在括号内，否则不要将多行字符串移动到新行。（#4289）

集成

• 将 GitHub Action psf/black 的新选项 use_pyproject 添加到其中。这将从 pyproject.toml 读取 Black 版本。（#4294）

24.3.0

亮点

此版本是一个里程碑：它修复了 Black 的第一个 CVE 安全漏洞。如果您在不受信任的输入上运行 Black，或者习惯性地在文档字符串中放置数千个前导制表符，则强烈建议您立即升级以修复 CVE-2024-21503。

此版本还修复了 Black 的 AST 安全检查中的漏洞，该漏洞允许 Black 对 Python 3.12 和更高版本中有效的某些 f-string 进行错误的更改。

稳定风格

• 不要将注释与分隔符一起移动，这可能会引起崩溃。（#4248）
• 加强 AST 安全检查以捕获更多不安全的字符串更改。Black 的早期版本会错误地格式化某些不寻常的 f-string 内容，这些 f-string 包含嵌套的具有相同引号类型的字符串。现在，Black 将在实现对新 f-string 语法的支持之前在这些字符串上崩溃。（#4270）
• 修复了超出最后一行代码的行范围不会按预期工作的问题。（#4273）

性能

• 修复了包含大量前导制表符的文档字符串上的灾难性性能问题。这修复了 CVE-2024-21503。（#4278）

文档

• 注意使用 --check 与 --quiet 时发生的情况。（#4236）

24.2.0

稳定风格

• 修复了错误地删除与冗余括号一起的注释的漏洞。（#4218）

预览样式

• 由于未解决的崩溃和提议的格式化调整，将 hug_parens_with_braces_and_square_brackets 功能移至不稳定样式。（#4198）
• 修复了基表达式导致三元表达式中的 ** 格式化不一致的问题。（#4154）
• 在文档字符串接近行限时在添加新行之前检查换行符。（#4185）
• 修复了在 case 语句的 if 守卫中删除冗余括号的问题。（#4214）。

配置

• 修复了在存在符号链接的情况下，Black 忽略输入文件的问题。（#4222）
• Black 现在在发现项目根和配置时，会忽略缺少 tool.black 部分的 pyproject.toml 文件。由于 Black 继续使用版本控制作为项目根的指示器，这主要会影响单仓库（monorepo）环境中的用户（理想情况下）。如果您希望保留之前的行为，只需在之前发现的 pyproject.toml 中添加一个空的 [tool.black] 即可（#4204）。

输出

• Black 在执行等价性检查时，会忽略由 ast 模块产生的任何 SyntaxWarning 或 DeprecationWarning（#4189）。

集成

• 添加 JSONSchema 并提供 validate-pyproject 入口点（#4181）。

24.1.1

修复了导致 Black 在某些对路径长度有严格限制的文件系统上无法使用的错误。

预览样式

• 始终在类型参数后添加尾随逗号（#4164）。

配置

• 缩短缓存文件名的长度以修复不支持长路径的文件系统上的崩溃（#4176）。

24.1.0

亮点

本版本引入了新的 2024 稳定样式（#4106），稳定了以下更改：

• 在 if-else 表达式周围添加括号（#2278）。
• 只包含 ... 的虚拟类和函数实现现在格式更紧凑（#3796）。
• 如果赋值语句太长，我们现在倾向于在右侧进行拆分（#3368）。
• Unicode 转义序列中的十六进制代码现在已标准化为小写（#2916）。
• 允许大多数块开头有空行（#3967，#4061）。
• 在长类型注解周围添加括号（#3899）。
• 强制在模块文档字符串后添加换行符（#3932，#4028）。
• 修复了处理返回类型时尾随逗号的错误（#3916）。
• 删除类文档字符串之前的空白行（#3692）。
• 如果在一个 with 语句中组合使用，则将多个上下文管理器用括号括起来（#3489）。
• 修复了功率运算的行长度计算中的错误（#3942）。
• 即使最后一个条目后有注释，也向集合字面量添加尾随逗号（#3393）。
• 当使用 --skip-magic-trailing-comma 或 -C 时，从具有多个元素的索引表达式中删除尾随逗号（#3209）。
• 在几种情况下，在存根中添加额外的空白行（#3564，#3862）。
• 接受原始字符串作为文档字符串（#3947）。
• 在情况块中拆分长行（#4024）。
• 停止从子脚本中的 walrus 运算符中删除空格（#3823）。
• 修复了某些异步语句的错误格式（#3609）。
• 允许将 # fmt: skip 与其他注释结合使用（#3959）。

在 --preview 样式中已有一些改进，这些改进将纳入 2025 稳定样式。尝试它们并 分享您的反馈。过去，预览样式包括了一些我们无法稳定的功能。今年，我们为具有已知问题的功能添加了单独的 --unstable 样式。现在，--preview 样式只包含我们真正期望纳入明年稳定样式的功能。

稳定风格

对转移到本版本稳定样式的功能进行了几个错误修复。

• 修复了在括号中括号化条件表达式时处理注释的错误（#4134）。
• 修复了在子脚本中括号化 walrus 运算符时没有添加空格的错误，这与其他二元运算符不同（#4109）。
• 在异步函数中删除文档字符串之前的空白行（#4132）。
• 解决了更改允许所有块开头有空行时缺失的情况，除了紧接在文档字符串之前（#4130）。
• 对于存根，修复了强制在嵌套类和体之后添加空行的逻辑（#4141）。

预览样式

• 添加 --unstable 样式，涵盖具有已知问题的预览功能，这些问题会阻止它们进入稳定样式。还添加了 --enable-unstable-feature 标志；例如，使用 --enable-unstable-feature hug_parens_with_braces_and_square_brackets 在 2024 年应用此预览功能，即使较新的 Black 发布版将此功能降级为不稳定（#4096）。
• 将模块文档字符串格式化为类和函数文档字符串（#4095）。
• 修复了在字典中使用 walrus 时的崩溃（#4155）。
• 修复了包装长字典时的不必要括号（#4135）。
• 在 # fmt: skip 注释之前停止正常化空格 (#4146)

配置

• 当 pyproject.toml 中的配置包含无效键时打印警告 (#4165)
• 修复符号链接处理，正确忽略指向根目录外部的符号链接 (#4161)
• 修复导致假阳性缓存命中的缓存 mtime 逻辑 (#4128)
• 移除长期弃用的 --experimental-string-processing 标志。目前可以通过 --preview --enable-unstable-feature string_processing 启用此功能。 (#4096)

集成

• 撤销仅在特定 git 钩子上运行 Black 的 pre-commit 集成的更改 (#3940)，以更好地与较旧版本的 pre-commit 兼容 (#4137)

23.12.1

包装

• 修复了一个默认包含 d 额外依赖项的 bug (#4108)

23.12.0

亮点

几乎到了 2024 年，这意味着是时候发布 Black 的稳定样式新版本了！随着这次发布，我们将发布 alpha 版本 24.1a1，展示 2024 年稳定样式的草案，我们将在 1 月发布中将其最终确定。请试一试，并在 分享您的反馈。

此版本（23.12.0）仍将生成 2023 年的样式。大多数更改（但并非全部）在 --preview 模式下将体现在 2024 年的稳定样式中。

稳定风格

• 修复了当与 --line-ranges 选项一起使用时，# fmt: off 自动缩进的问题，即使它不在指定的行范围内。 (#4084)
• 修复了对括号内上下文管理器的功能检测 (#4104)

预览样式

• 在拆分链式赋值时，优先使用更多等号前面的断行符 (#4010)
• 模块级别不再移除独立的形式馈送字符 (#4021)
• 现在对立即嵌套的元组、列表和字典的额外情况进行了较少的缩进 (#4012)
• 允许在所有块的开始处留有空行，除了立即在文档字符串之前 (#4060)
• 修复了在预览模式下使用短 --line-length 时的崩溃 (#4086)
• 如果它们不是函数或类定义，则保留仅由省略号组成的套件在其自己的行上 (#4066) (#4103)

配置

• --line-ranges 现在在 --safe 模式下跳过 Black 的内部稳定性检查。这避免了在罕见输入上发生崩溃，这些输入包含许多未格式化的相同内容的行。 (#4034)

包装

• 升级到 mypy 1.7.1 (#4049) (#4069)
• CPython 3.12 现在可用的编译过的轮子更快 (#4070)

集成

• 启用 3.12 CI (#4035)
• 并行构建 docker 镜像 (#4054)
• 使用 3.12 构建 docker 镜像 (#4055)

23.11.0

亮点

• 支持使用新的 --line-ranges 命令行选项格式化行范围 (#4020)

稳定风格

• 修复了格式化类似于文档字符串的字节字符串时的崩溃 (#4003)
• 修复了在文档字符串中换行符之前跟有空白时的崩溃 (#4008)
• 修复了在复杂块中独立注释导致 Black 崩溃的问题 (#4016)
• 修复了格式化如 await (a ** b) 的代码时的崩溃 (#3994)
• 不再将前导 f-strings 视为文档字符串。这与 Python 的行为相匹配并修复了崩溃 (#4019)

预览样式

• 作为函数的唯一参数的多行字典和列表现在缩进较少 (#3964)
• 作为函数的唯一参数的多行解包字典和列表现在也缩进较少 (#3992)
• 在 f-string 调试表达式中，现在保留在最终字符串中可见的引号类型 (#4005)
• 修复了长 case 块未拆分为多行的问题。还启用了 case 块上的通用尾随逗号规则 (#4024)
• 继续要求在模块级别的文档字符串和第一个函数或类定义之间保留两个空行 (#4028)
• 添加了对单行格式跳过以及同一行上其他注释的支持 (#3959)

配置

• 在解析符号链接之前始终一致地应用强制排除逻辑 (#4015)
• 修复了 --include 中绝对路径名称匹配的 bug (#3976)

性能

• 修复了在 macOS 上 arm64 上 mypyc 构建的 bug (#4017)

集成

• Black的预提交集成现在将仅运行适用于代码格式的git钩子（#3940）

23.10.1

亮点

• 维护版本发布以修复GitHub Action边缘情况（#3957）

预览样式

• 修复合并包含行内注释的隐式多行字符串（#3956）
• 允许在注释或复合语句之前在块开头的空行后为空（#3967）

包装

• 将Dockerfile改为hatch + 编译black（#3965）

集成

• 现在可以使用summary参数来抑制GitHub工作流程的摘要输出。 (#3958)
• 修复当Black检查未通过时操作失败的问题（#3957）

文档

• 已知Windows文档CI已损坏 https://github.com/psf/black/issues/3968

23.10.0

稳定风格

• 修复从括号内部移除注释的问题（#3909）

预览样式

• 修复在行长度之前分割具有幂运算符的长行（#3942）
• 长类型提示现在在多行之间包裹在括号中，并正确缩进（#3899）
• 现在尊重返回类型中的魔法尾逗号（#3916）
• 要求在模块级文档字符串后有一个空行（#3932）
• 将原始三引号字符串视为文档字符串（#3947）

配置

• 修复当设置BLACK_CACHE_DIR时缓存版本控制逻辑错误（#3937）

解析器

• 修复在match语句内部不接受名为type的属性时的错误（#3950）
• 添加对包含lambda和其他不寻常表达式的PEP 695类型别名支持（#3949）

输出

• Black不再尝试为尝试格式化Python 2代码提供特殊错误（#3933）
• Black现在在详细模式下会更一致地打印内部错误的堆栈跟踪（#3938）

集成

• 现在在作业摘要中显示的操作输出将包裹在Markdown中（#3914）

23.9.1

由于各种问题，上一个版本（23.9.0）没有包含编译的mypyc轮子，这使Black运行速度显著提高。这些问题现在已得到解决，本版本将再次提供编译的轮子。

由于mypyc中的错误，将没有Python 3.12的轮子。一旦修复mypyc错误，我们将在未来的版本中提供3.12轮子。

包装

• 升级到mypy 1.5.1（#3864）

性能

• 在Black的缓存中存储原始元组而不是命名元组，提高性能并减小缓存大小（#3877）

23.9.0

预览样式

• 简化虚拟实现格式化（#3796）
• 在stub文件中，在具有主体的语句（例如if sys.version_info > (3, x):）和同一级别的函数定义之间添加一个空行（#3862）
• 修复从下标中移除walrus运算符时删除空格的错误（#3823）

配置

• Black现在在解析符号链接之前应用排除和忽略逻辑（#3846）

性能

• 如果notebook单元不包含魔法，则避免导入IPython（#3782）
• 通过比较mtime和大小作为后备来改进缓存，比较文件哈希（#3821）

Blackd

• 修复blackd中单字符输入的问题（#3558）

集成

• Black现在有一个官方的pre-commit镜像。将您的.pre-commit-config.yaml中的https://github.com/psf/black更改为https://github.com/psf/black-pre-commit-mirror，Black的速度将提高约2倍（#3828）
• 在GitHub Action完成后，现在将移除由ENV_PATH指定的.black.env文件夹（#3759）

23.7.0

亮点

• 已删除对Python 3.7的运行时支持。在进一步通知之前，仍将支持格式化3.7代码（#3765）

稳定风格

• 修复使用PEP 604联合时添加非法尾逗号的错误（#3735）
• 修复在特定情况下删除或处理不当的stub文件中的注释的一些错误和崩溃（#3745）
• 修复多行魔法注释（如括号内的type: ignore）中的崩溃（#3740）
• 修复当Black移除类型注释中的尾空格时AST验证中的错误（#3773）

预览样式

• 用作函数参数的隐式连接字符串不再用括号括起来 (#3640)
• 移除类定义与其文档字符串之间的空白行 (#3692)

配置

• 现在可以通过 BLACK_NUM_WORKERS 环境变量指定 Black 的 --workers 参数 (#3743)
• .pytest_cache、.ruff_cache 和 .vscode 默认被排除 (#3691)
• 修复了当运行 --stdin-filename 时，如果找到的 pyproject.toml 不在当前工作目录中，Black 不会尊重 pyproject.toml 设置的问题 (#3719)
• Black 现在如果 exclude 和 extend-exclude 在 pyproject.toml 中有无效的数据类型，将报错，而不是默默地做错事 (#3764)

包装

• 将 mypyc 从 0.991 升级到 1.3 (#3697)
• 移除了对 Python 3.6 使用 LANG=C 时 Click 错误的修补 (#3768)

解析器

• 添加了对 Python 3.12 中的新 PEP 695 语法的支持 (#3703)

性能

• 当缓存满时，显著加快 Black 的速度 (#3751)
• 避免在不必要的情况下导入 IPython (#3748)

输出

• 内部使用意识 UTC 日期时间，避免在 Python 3.12 上的弃用警告 (#3728)
• 将详细日志记录改为与 Black 的源发现逻辑完全一致 (#3749)

Blackd

• 现在 blackd 参数解析器在帮助文本中显示选项的默认值 (#3712)

集成

• Black 现在用 PYTHONWARNDEFAULTENCODING = 1 进行测试 (#3763)
• 更新 GitHub Action 以在作业摘要中显示 black 输出 (#3688)

文档

• 在存储库根目录中添加一个 CITATION.cff 文件，其中包含有关如何引用此软件的元数据 (#3723)
• 更新开发者参考中的 classes 和 exceptions 文档，以匹配最新的代码库 (#3755)

23.3.0

亮点

这次发布修复了 Black 的 GitHub action 中长期存在的令人困惑的行为，其中动作的版本没有确定运行的 Black 的版本（问题 #3382）。此外，还有关于导入的小错误修复和预览样式的多项改进。

请尝试使用 black --preview 试用 预览样式 并告诉我们您的反馈。所有预览样式中的更改预计将在 2024 年 1 月成为 Black 的稳定样式的一部分。

稳定风格

• 带有 # fmt: skip 和 # fmt: off 的导入行不再在它们紧随另一个导入行时添加额外的空白行 (#3610)

预览样式

• 即使最后一个条目后有注释，也向集合字面量添加尾随逗号（#3393）。
• async def、async for 和 async with 语句的格式现在与其非异步版本保持一致 (#3609)
• 包含两个上下管理器的 with 语句将被一致地括在括号中 (#3589)
• 让字符串分隔符尊重 东亚宽度 (#3445)
• 现在长字符串字面量可以在东亚逗号和句号（、 U+3001 汉字逗号，。 U+3002 汉字句号，以及 ， U+FF0C 全角逗号）之后分割，除了在空格之前 (#3445)
• 对于存根，在包含除 ... 之外其他内容的嵌套类之后强制执行一个空白行 (#3564)
• 通过更改行分割行为改进多行字符串的处理 (#1879)

解析器

• 添加了对格式化具有无效类型注释的文件的支持 (#3594)

集成

• 更新 GitHub Action 以使用如果未指定版本则与动作版本等效的 Black 版本 (#3543)
• 修复了 vim 的自动加载脚本中缺失 Python 二进制路径的问题 (#3508)

文档

• 仅支持最近发布的版本以解决安全问题；漏洞应通过 Tidelift 报告 (#3612)

23.1.0

亮点

这是 2023 年的第一个版本，根据我们的 稳定性策略，它包含对我们稳定样式的多项改进，包括改进空行处理、删除多个上下文中的冗余括号以及突出显示隐式连接字符串的输出。

预览样式也发生了许多变化；请尝试使用 black --preview 并给我们反馈，帮助我们为明年设置稳定的样式。

除了样式变化外，Black 现在可以从您的 pyproject.toml 文件中自动推断支持的 Python 版本，从而无需单独设置 Black 的目标版本。

稳定风格

• 引入 2023 稳定样式，其中包含去年预览样式的几乎所有方面 (#3418)。具体更改
  • 强制在类和函数前使用粘性前导注释前的空行 (#3302) (22.12.0)
  • 将空文件和仅包含空白字符的文件重格式化为空文件（如果不存在换行符）或单个换行符（如果存在换行符） (#3348) (22.12.0)
  • 用作函数参数的隐式连接字符串现在被括号包裹 (#3307) (22.12.0)
  • 正确处理位于行首非嵌套括号内的行尾逗号 (#3370) (22.12.0)
  • --skip-string-normalization / -S 现在阻止按预期对文档字符串前缀进行规范化 (#3168) (自 22.8.0)
  • 当使用 --skip-magic-trailing-comma 或 -C 时，从具有多个元素的索引表达式中移除尾随逗号 (#3209) (22.8.0)
  • 列表、集合或元组中的隐式连接字符串现在被括号包裹 (#3162) (22.8.0)
  • 修复在隐式连接字符串的单独行中间存在注释时的字符串合并/拆分问题 (#3227) (22.8.0)
  • 如果会违反行长度限制，则不再移动文档字符串引号 (#3044, #3430) (22.6.0)
  • 现在管理返回注释周围的括号 (#2990) (22.6.0)
  • 移除围绕等待对象的无关括号 (#2991) (22.6.0)
  • 移除 with 语句中的无关括号 (#2926) (22.6.0)
  • 移除代码块开头的尾随新行 (#3035) (22.6.0)
  • 代码单元格分隔符 #%% 现在标准化为 # %% (#2919) (22.3.0)
  • 移除 except 语句中的无关括号 (#2939) (22.3.0)
  • 移除 for 循环中元组拆包中的无关括号 (#2945) (22.3.0)
  • 避免在单个元素子脚本中使用魔法尾随逗号 (#2942) (22.3.0)
• 修复在 # fmt: off 和 # fmt: on 之间标记冒号行时的崩溃 (#3439)

预览样式

• 在字符串字面量中的 Unicode 转义序列中格式化十六进制代码 (#2916)
• 在 if-else 表达式周围添加括号（#2278）。
• 改进包含许多字符串的大型表达式的性能 (#3467)
• 修复预览样式中断言 + 括号字符串时的崩溃 (#3415)
• 修复预览样式中使用 walrus 运算符在函数返回注释和 except 子句中使用的崩溃 (#3423)
• 修复预览高级字符串处理中，当混合隐式连接的正则表达式和 f-字符串以空跨度开头时的崩溃 (#3463)
• 修复预览高级字符串处理中，在字典的值之前放置独立注释时的崩溃 (#3469)
• 修复当装饰器应用 # fmt: skip 或装饰器之间存在独立注释时添加额外空行的问题 (#3470)
• 即使行太长，也不将文档字符串中的关闭引号放在单独的一行上 (#3430)
• 字典字面量中的长值现在用括号括起来；相应地，现在从字典字面量中的短值周围移除无关的括号；长字符串 lambda 值现在用括号括起来 (#3440)
• 修复预览样式中涉及文档字符串边缘情况的两个崩溃 (#3451)
• 从改进的字符串处理中排除字符串类型注释；修复当返回类型注释被字符串化并跨越多行时发生的崩溃 (#3462)
• 当针对 Python 3.9+ 时，将多个上下文管理器用括号括起来 (#3489)
• 修复预览样式中使用 with 语句或元组中的 walrus 运算符时出现的几个崩溃 (#3473)
• 修复 f-string 表达式中的无效引号转义错误，该错误生成了无效的代码。现在可以通过更改表达式中的引号将具有不同引号的隐式连接 f-字符串合并或规范化 (#3509)
• 修复当使用 mypyc 编译 Black 时 await (yield) 发生的崩溃 (#3533)

配置

• Black现在尝试从指定的pyproject.toml项目元数据中推断其--target-version (#3219)

包装

• 将mypy-c从0.971升级到0.991，以便在armv7上构建mypy化的Black (#3380)
  • 这也修复了在使用编译的Black和CPython的调试构建时出现的某些崩溃
• 在3.11 alpha版本中删除对tomli要求的特定支持，以解决可能导致该要求在任何非最终Python版本上未安装的bug (#3448)
• Black现在依赖于packaging版本22.0或更高版本。这是为了支持需要解析项目元数据部分的新功能 (#3219)

输出

• 多次调用black --help将每次返回相同的内容 (#3516)
• 详细日志现在显示pyproject.toml配置变量的值 (#3392)
• 修复了由于使用到项目根的不正确相对路径而导致的详细输出中的假符号链接检测消息 (#3385)

集成

• 由于所有依赖项都支持3.11，现在将3.11 CI移至正常流程 (#3446)
• Docker：添加新的latest_prerelease标签自动化，以跟踪Docker镜像上的最新Black alpha版本 (#3465)

文档

• 扩展vim-plug安装说明，提供更明确的选择 (#3468)

22.12.0

预览样式

• 强制在类和函数之前添加空行，如果存在粘性前导注释 (#3302)
• 格式化空文件和只包含空白字符的文件，如果没有换行符，则为空文件；如果有换行符，则为单个换行符 (#3348)
• 现在将用作函数参数的隐式连接字符串括在括号内 (#3307)
• 对于赋值语句，如果左侧适合单行，则优先分割右侧 (#3368)
• 正确处理位于行首非嵌套括号内的尾随逗号 (#3370)

配置

• 通过考虑.gitignore的位置和目标文件的相对路径来修复不正确应用的.gitignore规则 (#3338)
• 修复了指定多个源目录时忽略.gitignore存在的不正确情况 (#3336)

解析器

• 添加了对生成器表达式中用作函数参数的海象（walrus）的解析支持（例如，any(match := my_re.match(text) for text in texts)) (#3327)。

集成

• 在Vim插件中：通过let g:black_use_virtualenv = 0可选地允许使用Black的系统安装 (#3309)

22.10.0

亮点

• 已移除Python 3.6的运行时支持。格式化3.6代码将一直得到支持，直到另行通知。

稳定风格

• 修复了当使用不同块级别时使用# fmt: on导致的崩溃 (#3281)

预览样式

• 修复了格式化一些括号包围的长字符串键的字典时的崩溃 (#3262)

配置

• 默认排除.ipynb_checkpoints目录 (#3293)
• 添加--skip-source-first-line / -x选项，在格式化时忽略源代码的第一行 (#3299)

包装

• 使用PyInstaller制作的可执行文件在macOS上格式化多个文件时不会再崩溃。macOS的原生x86-64可执行文件现在再次可用。 (#3275)
• Hatchling现在用作构建后端。对于从PyPI使用wheel安装Black的用户，这不会产生影响。 (#3233)
• 现在可用于CPython 3.11的更快编译的wheel (#3276)

Blackd

• 将保留Windows样式（CRLF）的新行 (#3257)。

集成

• 在Vim插件中：添加标志（g:black_preview）以启用/禁用预览样式 (#3246)
• 更新GitHub Action以支持通过jupyter选项格式化Jupyter Notebook文件 (#3282)
• 更新GitHub Action以支持使用版本指定符（例如，<23）为Black版本 (#3265)

22.8.0

亮点

• 现在支持Python 3.11，但blackd除外，因为截至发布时aiohttp不支持3.11 (#3234)
• 这是最后一个支持在Python 3.6上运行Black的版本（格式化3.6代码将一直得到支持，直到另行通知）
• 将稳定性策略重新措辞，说明在极少数情况下，我们可能会对未经过Black格式化的代码进行更改（#3155）

稳定风格

• 修复在表达式或代码块中使用# fmt: on/off时出现的无限循环问题（#3158）
• 修复在冒号（:）行上对# fmt: skip的错误处理（#3148）
• 当一行在幂运算符周围删除了空格时，注释不再被删除（#2874）

预览样式

• 单字符文档字符串引号不再移到自己的行上，因为这是不合法的。这是在版本22.6.0中引入的错误（#3166）
• --skip-string-normalization / -S现在可以阻止文档字符串前缀按预期进行规范化（#3168）
• 当使用 --skip-magic-trailing-comma 或 -C 时，从具有多个元素的索引表达式中删除尾随逗号（#3209）。
• 列表、集合或元组中的隐式连接字符串现在被括号括起来（#3162）
• 修复了当隐式连接字符串位于其自己的行中的注释时出现的字符串合并/拆分问题（#3227）

Blackd

• blackd现在支持通过X-Preview头启用预览样式（#3217）

配置

• Black现在使用调试f字符串的存在来检测目标版本（#3215）
• 修复了涉及--stdin-filename时的项目根误检测和详细日志记录源的问题（#3216）
• 现在也尊重命令行上给出的源目录中的立即.gitignore文件，以前仅尊重项目根和自动发现的目录中的.gitignore文件（#3237）

文档

• 建议在IntelliJ IDE中使用BlackConnect（#3150）

集成

• Vim插件：将消息前缀为Black: ，以便清楚地表明它们来自Black（#3194）
• Docker：改为/opt/venv安装并添加到PATH，以便非root用户可用（#3202）

输出

• 从废弃的asyncio.get_event_loop()更改为创建我们的事件循环，这消除了DeprecationWarning（#3164）
• 从内部blib2to3库中删除日志记录，因为它会定期发出关于失败的缓存错误日志，这些日志可以并且应该被忽略（#3193）

解析器

• 类型注释现在始终包含在AST等价性检查中，因此意外的删除将引发错误。尽管由于标准库的限制，在PyPy 3.7上运行时无法跟踪类型注释。 (#2874)

性能

• 将格式化单个文件时的Black启动时间减少15-30%（#3211）

22.6.0

样式

• 修复涉及#fmt: skip和# fmt:skip注释的不稳定格式化（注意空格的缺失）（#2970）

预览样式

• 如果会违反行长度限制，则不再移动文档字符串引号（#3044）
• 现在管理返回注释周围的括号（#2990）
• 删除await对象周围的冗余括号（#2991）
• 删除with语句中的冗余括号（#2926）
• 删除代码块开头的换行符（#3035）

集成

• 将scripts/migrate-black.py脚本添加到Git项目中以简化Black的引入（#3038）

输出

• 作为--version标志的一部分输出Python版本和实现（#2997）

包装

• 在Python 3.11构建中使用tomli而不是tomllib，因为tomllib不可用（#2987）

解析器

• PEP 654语法（例如，except *ExceptionGroup:）现在受支持（#3016）
• PEP 646语法（例如，Array[Batch, *Shape]或def fn(*args: *T) -> None）现在受支持（#3071）

Vim插件

• 修复strtobool函数。它没有解析true/on/false/off。（#3025）

22.3.0

预览样式

• 代码单元分隔符#%%现在标准化为# %%（#2919）
• 从except语句中删除不必要的括号（#2939）
• 从for循环中的元组解包中删除不必要的括号（#2945）
• 避免在单元素子脚本中发生尾随逗号的魔术行为（#2942）

配置

• 默认情况下不格式化__pypackages__目录（#2836）
• 通过--required-version添加支持指定稳定版本（#2832）。
• 避免在用户没有主目录时崩溃（#2814）
• 避免在md5不可用时崩溃（#2905）
• 修复Windows上目录符号链接的处理（#2904）

文档

• 更新pylint配置文档（#2931）

集成

• 将测试移动到Vim/Neovim中禁用插件，这可以加快加载速度（#2896）

输出

• 在详细模式下，当Black使用用户级配置时记录日志（#2861）

包装

• 修复Black以兼容Click 8.1.0（#2966）
• 在Python 3.11及更高版本上，使用标准库的tomllib而不是tomli（#2903）
• black-primer，已弃用的内部开发工具，已被删除并复制到独立的仓库（#2924）

解析器

• 现在Black可以解析for和async for语句的目标中的带星号的表达式，例如for item in *items_1, *items_2: pass（#2879）。

22.1.0

终于，Black不再是一个Beta产品！这是第一个非Beta版本，也是第一个受我们新的稳定性策略覆盖的版本。

亮点

• 移除对Python 2的支持 (#2740)
• 引入--preview标志（#2752）

样式

• 弃用--experimental-string-processing并将功能移至--preview（#2789）
• 对于存根，如果至少有一个预存在的空行，则现在保留类属性和方法之间的一个空行（#2736）
• Black现在标准化字符串前缀顺序（#2297）
• 如果两个操作数都是简单的，则删除幂运算符周围的空格（#2726）
• 解决由尾随逗号引起的某些情况下的不稳定格式化问题的bug（#2807）
• 使用括号对十进制浮点数和整字面量进行属性访问（#2799）
• 不要为十六进制、二进制、八进制和复数字面量进行属性访问添加空格（#2799）
• 将存根中的空白行视为顶层if语句内部相同（#2820）
• 修复分号和算术表达式引起的不稳定格式化问题（#2817）
• 修复尾随逗号周围的不稳定格式化问题（#2572）

解析器

• 修复包含as表达式的情况，例如case {"key": 1 | 2 as password}（#2686）
• 修复包含多个顶层as表达式的情况，例如case 1 as a, 2 as b（#2716）
• 修复包含带关键字参数的as表达式的调用模式，例如case Foo(bar=baz as quux)（#2749）
• 在return和yield构造中的元组解包现在暗示3.8+（#2700）
• 在注解赋值中，无括号的元组现在暗示3.8+（例如values: Tuple[int, ...] = 1, 2, 3）（#2708）
• 修复处理独立match()或case()时的bug，当括号内有尾随换行符或注释时。 (#2760)
• from __future__ import annotations语句现在暗示Python 3.7+（#2690）

性能

• 新回溯解析器一般加速约4倍（当--target-version设置为3.10及以上时启用）。 (#2728)
• Black现在使用mypyc编译，整体速度提高2倍。支持64位Windows、MacOS和Linux（不包括musl）。 (#1009, #2431)

配置

• 在pyproject.toml中不接受裸换行符行结束符（#2408）
• 添加配置选项（python-cell-magics），以格式化Jupyter笔记本中的自定义魔法的单元格（#2744）
• 允许使用环境变量BLACK_CACHE_DIR在所有平台上设置自定义缓存目录（#2739）。
• 默认启用Python 3.10+，无需指定额外的--target-version=py310。 (#2758)
• 使通过SRC或--code强制且互斥（#2804）

输出

• 改进无效正则表达式的错误消息（#2678）
• 在AST安全检查期间解析失败时，改进错误消息，通过嵌入底层的SyntaxError（#2693）
• 不再将diff标题涂成白色，因为它在浅色主题终端中不可读（#2691）
• 在最终统计中添加文本着色（#2712）
• 详细模式还现在描述了项目根的发现方式和哪些路径将被格式化。 (#2526)

包装

• 已移除所有依赖项的上限版本（#2718）
• 在Python 3.10+中，typing-extensions不再是必需的依赖项（#2772）
• 将click的下限设置为8.0.0（#2791）

集成

• 更新GitHub动作以支持容器化运行（#2748）

文档

• 在pip安装说明中更改协议为https://（#2761）
• 将HTML主题更改为Furo，主要因为它具有响应式设计和移动支持（#2793）
• 弃用black-primer工具（#2809）
• 记录Python支持策略（#2819）

21.12b0

Black

• 修复f-string表达式范围的确定问题（#2654）
• 修复多行语句中关于EOF的错误消息的格式问题（#2343）
• 块中的函数和类现在具有更一致的周围间距（#2472）

Jupyter Notebook支持

• 现在只有已知的Python单元格魔法才会处理单元格魔法。之前，所有单元格魔法都被标记化，可能导致缩进错误，例如使用%%writefile。（#2630）
• 修复Jupyter Notebooks中的环境变量赋值问题（#2642）

支持Python 3.10

• 如果检测到3.10-only语法，建议用户使用--target-version py310（#2668）
• 修复具有开放序列主题的match语句，例如match a, b:或match a, *b:（#2639）（#2659）
• 修复包含多个match/case软关键词的match/case语句，例如match re.match()（#2661）
• 修复具有内联体的case语句（#2665）
• 修复match主题中星号表达式的样式（#2667）
• 修复在match语句中无效语法上的解析器错误位置（#2649）
• 修复没有ProcessPoolExecutor的平台上的Python 3.10支持（#2631）
• 在--target-version py310下使用match的代码上提高解析性能，最高可达约50%（#2670）

包装

• 删除对regex的依赖（#2644）（#2663）

21.11b1

Black

• 将regex版本最低要求提高到2021.4.4，以修复Pattern类使用问题（#2621）

21.11b0

Black

• 通过改进Python 2只语法检测来在更多情况下警告Python 2的弃用（#2592）
• 添加实验性PyPy支持（#2559）
• 添加对match语句的部分支持。由于它是实验性的，因此仅在显式指定--target-version py310时启用（#2586）
• 添加对括号化with语句的支持（#2586）
• 声明支持Python 3.10以运行Black（#2562）

集成

• 通过删除已弃用的distutils导入修复了Python 3.10的vim插件（#2610）
• 现在vim插件从pyproject.toml解析skip_magic_trailing_comma（#2613）

21.10b0

Black

• 记录稳定性策略，该策略将适用于非beta版本（#2529）
• 添加新的--workers参数（#2514）
• 修复了lambda中位置只参数的功能检测问题（#2532）
• 将typed-ast版本最低要求提高到1.4.3以实现3.10兼容性（#2519）
• 修复了Python 3.10兼容性问题，即使循环参数已被删除，循环参数仍然会被传递（#2580）
• 弃用Python 2格式化支持（#2523）

Blackd

• 删除对aiohttp-cors的依赖（#2500）
• 将所需的aiohttp版本提升到3.7.4（#2509）

Black-Primer

• 添加对--projects的primer支持（#2555）
• 在单个失败后打印primer摘要（#2570）

集成

• 允许在vim插件中传递target_version（#1319）
• 在docker文件中安装构建工具并使用多阶段构建以保持镜像大小（#2582）

21.9b0

包装

• 修复自包含二进制文件中缺少的模块（#2466）
• 修复安装期间缺少的toml额外依赖（#2475）

21.8b0

Black

• 添加对格式化Jupyter Notebook文件的支持（#2357）
• 将appdirs依赖项移至platformdirs（#2375）
• 如果.gitignore无效，则显示更用户友好的错误（#2414）
• 将f-string表达式中的意外添加的反斜杠的防护措施加固，以在引号归一化期间处理更多边缘情况（#2437）
• 通过添加尾随逗号，避免将函数返回类型注解的类型更改为元组（#2384）
• 已添加对集合字面量、集合推导式和索引中无括号的walruses的解析支持（#2447）。
• 将setuptools-scm的构建时依赖版本固定（#2457）
• 由于在Python 3.10上损坏，排除typing-extensions版本3.10.0.1（#2460）

Blackd

• 将sys.exit(-1)替换为raise ImportError，因为它与扫描已安装包的工具更兼容（#2440）

集成

• 提供的pre-commit钩子不再指定language_version，以避免覆盖default_language_version（#2430）

21.7b0

Black

• 现在支持使用高于spec v0.5.0的TOML功能的配置文件（#2301）
• 添加了对通过STDIN管道输入的代码的primer支持和测试（#2315）
• 修复了启用FORCE_OPTIONAL_PARENTHESES功能时的内部错误（#2332）
• 接受空stdin（#2346）
• 在AST安全性检查期间解析失败时提供更有用的错误（#2304）

Docker

• 添加新的latest_release标签自动化，以跟踪docker镜像上的最新black版本（#2374）

集成

• vim插件现在从包含当前缓冲区的目录向上搜索而不是从当前工作目录搜索pyproject.toml。（#1871）
• vim插件现在在pyproject.toml中读取正确的字符串规范化选项（#1869）
• vim插件不再在pyproject.toml中存在布尔值时崩溃Black（#1869）

21.6b0

Black

• 修复了由fmt: skip和缩进引起的失败（#2281）
• 在决定是否拆分字符串时考虑+=赋值（#2312）
• 当存在字符串运算符时，更正最大字符串长度计算（#2292）
• 修复了使用--code标志时选项的使用问题（#2259）
• 当Black作为库使用时，不要调用uvloop.install()（#2303）
• 添加了--required-version选项，要求运行特定版本（#2300）
• 修复了字符串组包含伪f-strings时的自定义断点索引不正确的问题（#2311）
• 修复了文档字符串中的R前缀被小写化的问题（#2285）
• 当使用--experimental-string-processing时，修复了对命名转义（\N{...}）的处理（#2319）

集成

• 官方Black动作现在支持选择要使用的版本，并支持主要3个OS。（#1940）

21.5b2

Black

• 不再在空文档字符串中插入空格（#2249）
• 修复了在Windows上包含非ASCII字符的.gitignore文件的处理（#2229）
• 尊重所有级别的.gitignore文件，而不仅仅是root/.gitignore文件（像git一样应用.gitignore规则）（#2225）
• 在LANG=C使用时，恢复了与Click 8.0在Python 3.6上的兼容性（#2227）
• 如果在Python环境中，则添加额外的uvloop安装+导入支持（#2258）
• 修复了找不到匹配括号时--experimental-string-processing崩溃的问题（#2283）
• 确保拆分以字符串运算符开头的行（#2286）
• 修复了Black用于识别f-expressions的正则表达式（#2287）

Blackd

• 为aiohttp-cors依赖项添加了下限。仅支持0.4.0或更高版本。（#2231）

包装

• 作为GitHub发布管道的一部分发布自包含的x86_64 MacOS二进制文件（#2198）
• 始终使用最新的可用Python构建二进制文件（#2260）

文档

• 在FAQ页面上添加了关于魔法注释的讨论（#2272）
• --experimental-string-processing将在未来默认启用（#2273）
• 修复了codespell发现的拼写错误（#2228）
• 修复了Vim插件安装说明（#2235）
• 添加了新的常见问题解答页面（#2247）
• 修复了编码+符号链接问题，这些问题阻止了Windows上的正确构建（#2262）

21.5b1

Black

• 将src/black/__init__.py重构为多个文件（#2206）

文档

• 将所有剩余的master分支引用替换为main分支。源代码中还做了其他一些更改。（#2210）
• 对文档进行了大幅重构，使其更具可读性。请前往RTD上的稳定文档查看。 (#2174)

21.5b0

Black

• 如果--stdin-filename以.pyi结尾，则设置--pyi模式。 (#2169)
• 停止检测目标版本为Python 3.9+，因为这些装饰器正在被调用但没有参数。 (#2182)

Black-Primer

• 将--no-diff添加到black-primer中，以抑制格式化更改。 (#2187)

21.4b2

Black

• 修复了用户配置目录不可访问时的崩溃问题。 (#2158)

• 阐明Black可能在哪些情况下更改AST的情况。 (#2159)

• 允许通过指定exclude在pyproject.toml或命令行中覆盖.gitignore规则。 (#2170)

包装

• 使用black安装primer.json（默认情况下由black-primer使用）。 (#2154)

21.4b1

Black

• 修复了文档字符串以"\ "结尾时的崩溃问题。 (#2142)

• 修复了从dostrings中清理典型空白时的崩溃问题。 (#2120)

• 在缓存文件名称中反映--skip-magic-trailing-comma和--experimental-string-processing标志。如果没有此修复，则更改这些标志不会生效，如果缓存已填充。 (#2131)

• 不要从包含assert / return语句的赋值表达式中的括号中删除必要的括号。 (#2143)

包装

• 将pathspec提升到>=0.8.1以解决无效.gitignore排除处理。 (#1655)

21.4b0

Black

• 修复了由Black插入的可选尾随逗号和查看现有“魔法”尾随逗号的可选括号组合引起的罕见但令人烦恼的格式化不稳定性。这修复了问题#1629及其许多重复问题。 (#2126)

• Black现在通过删除前导和尾随空格处理单行文档字符串，并在需要时添加填充空格以拆分""""。 (#1740)

• Black现在清理注释中的前导非换行空格 (#2092)

• Black现在在规范化多行文档字符串引号时尊重--skip-string-normalization (#1637)

• Black不再在格式化typing stubs时删除非函数代码和装饰器之间的所有空行。现在Black强制执行一个空行。 (#1646)

• Black不再在if/while语句中的括号赋值表达式后添加错误的空间 (#1655)

• 添加了--skip-magic-trailing-comma / -C以避免将尾随逗号用作拆分行的理由 (#1824)

• 修复了在POSIX上PWD=/时的崩溃 (#1631)

• 修复了使用--diff时的“在已关闭的文件上执行I/O操作”错误 (#1664)

• 防止彩色diff输出与多个文件交织 (#1673)

• 在python 3.9上添加了对PEP 614宽松装饰语法的支持 (#1711)

• 为Python 3.8及以上版本添加了解析支持，用于无括号元组和解包表达式的注解赋值 (#1835)

• 添加了--extend-exclude参数（PR #2005）

• 通过避免使用pathlib来加速缓存（#1950）

• --diff正确地指示文件是否以换行符结尾 (#1662)

• 添加了--stdin-filename参数，允许stdin尊重--force-exclude规则 (#1780)

• 现在，以fmt: skip结束的行将不会被格式化 (#1800)

• PR #2053：Black不再依赖于Python 3.8及以上的typed-ast

• PR #2053：Python 2支持现在是可选的，安装python3 -m pip install black[python2]以维持支持。

• 默认排除venv目录 (#1683)

• 修复了格式化Python 2文档字符串时“Black生成的代码与源代码不等价”的问题 (#2037)

包装

• 现在通过GitHub Releases提供自包含的本地Black二进制文件 (#1743)

20.8b1

包装

• 明确依赖于Click 7.1.2或更高版本，因为Black不再与低于7.0的版本一起工作 (#1664)

20.8b0

Black

• 重新实现了显式尾随逗号的支持：现在它在任何括号对中始终如一地工作，包括嵌套结构（#1288及其重复项）

• Black现在在重新格式化围绕其的代码时重新缩进文档字符串 (#1053)

• Black现在显示彩色diff (#1266)

• Black 现在采用带 'py3' 标签的 wheel 包封装 (#1388)

• Black 现在支持 Python 3.8 代码，例如 return 语句中的星号表达式 (#1121)

• Black 不再规范化大写的 R-string 前缀，因为它们有社区公认的意义 (#1244)

• Black 现在在指定的配置文件不存在时使用退出代码 2 (#1361)

• Black 现在可以在 AWS Lambda 上运行 (#1141)

• 添加了 --force-exclude 参数 (#1032)

• 移除了已弃用的 --py36 选项 (#1236)

• 修复了遇到文件结束符时 --diff 输出的问题 (#526)

• 修复了在装饰器周围处理 # fmt: off 的问题 (#560)

• 修复了一些 # type: ignore 注释导致的格式化不稳定 (#1113)

• 修复了在组织括号后跟索引时的无效删除 (#1575)

• 引入了 black-primer，这是一个 CI 工具，允许我们针对现有的 Black 开源用户运行回归测试 (#1402)

• 基于 Hypothesis 和 Hypothersmith 引入了基于属性的模糊测试到我们的测试套件 (#1566)

• 实现了实验性的长字符串重包装，默认情况下是禁用的 (#1132)，在开发过程中隐藏在 --experimental-string-processing 标志下；这是一个未记录且不受支持的功能，依赖它将失去网络积分 (#1609)

Vim 插件

• 优先使用 virtualenv 包而不是全局包 (#1383)

19.10b0

• 添加了对 PEP 572 赋值表达式的支持 (#711)

• 添加了对 PEP 570 位置限定参数的支持 (#943)

• 添加了对异步生成器的支持 (#593)

• 添加了对通过在内部放置显式尾逗号来预分割集合的支持 (#826)

• 添加了 black -c 作为从命令行传递代码进行格式化的方式 (#761)

• --safe 现在可以与 Python 2 代码一起工作 (#840)

• 修复了 Python 2 特定代码的语法选择问题 (#765)

• 修复了函数定义和调用位置尾随逗号的特性检测问题 (#763)

• 在同一代码块内多次放置 # fmt: off/# fmt: on 注释对现在表现正确 (#1005)

• Black 在 Windows 机器上不再因超过 61 个核心而崩溃 (#838)

• Black 在以反斜杠开头的独立注释中不再崩溃 (#767)

• Black 在 from ... import 块中的注释中不再崩溃 (#829)

• Black 在某些平台配置上的 Python 3.7 中不再崩溃 (#494)

• Black 在 from-imports 中的注释中不再失败 (#671)

• Black 在文件以反斜杠开头时不再失败 (#922)

• Black 不再将普通注释与类型注释合并 (#1027)

• Black 不再分割包含类型注释的长行 (#997)

• 删除了围绕 yield 表达式的冗余括号 (#834)

• 在解包赋值时添加了围绕长元组的括号 (#832)

• 当它们由一元运算符前缀时，添加了围绕复杂幂的括号 (#646)

• 修复了导致 Black 使用行长度目标为 1 格式化某些代码的 Bug (#762)

• Black 在字符串边界上不再在 f-string 子表达式中引入引号 (#863)

• 如果 Black 将括号放在单个表达式中，它将注释移到包裹的表达式而不是括号之后 (#872)

• blackd 现在在响应头中返回 Black 的版本 (#1013)

• blackd 现在可以在提供 X-Diff 头部时输出源代码的格式化 diff (#969)

19.3b0

• 新选项 --target-version 用于控制 Black 格式化代码应针对哪些 Python 版本 (#618)

• 弃用 --py36（使用 --target-version=py36 代替） (#724)

• Black不再将数字字面量转换为包含_分隔符的形式（#696）

• 长的del语句现在被拆分成多行（#698）

• 类型注释不再在函数签名中混淆

• 改进了深度嵌套数据结构的格式化性能（#509）

• Black现在可以在Windows上并行正确格式化多个文件（#632）

• Black现在以原子方式创建缓存文件，允许其在并行管道（如xargs -P8）中使用（#673）

• Black现在正确缩进先前使用制表符格式化的文件中的注释（#262）

• blackd现在支持CORS（#622）

18.9b0

• 数字字面量现在由Black格式化（#452, #461, #464, #469）

  • 在Python 3.6+代码中，数字字面量被转换为包含_分隔符的形式

  • 添加了--skip-numeric-underscore-normalization来禁用上述行为，并保留输入中的数字下划线

  • 包含_的数字字面量被识别为Python 3.6+

  • 大多数数字字面量中的字母都是小写的（例如，在1e10，0x01中）

  • 十六进制数字始终大写（例如，0xBADC0DE）

• 添加了blackd，有关更多信息，请参阅其文档（#349）

• 相邻的字符串字面量现在被正确地拆分成多行（#463）

• 现在为单行导入添加了尾随逗号（#250）

• 当--check成功时，现在会在文件中填充缓存，这可以加快连续检查正确格式且未更改的文件的速度（#448）

• 现在移除了文件开头的空白字符（#399）

• 修复了和Spyder IDE特殊注释的混淆（#532）

• 修复了解包大元组时的不稳定格式化（#267）

• 修复了解析带重命名的__future__导入（#389）

• 修复了直接在yield和其他节点之前# fmt: off的作用域（#385）

• 修复了带默认参数的lambda表达式的格式化（#468）

• 修复了async for语句：Black不再将其拆分为单独的行（#372）

• 注意：Vim插件停止注册,=为默认和弦，因为事实证明这是一个坏主意（#415）

18.6b4

• 热修复：当多个注释直接在# fmt: off之前时，不要冻结（#371）

18.6b3

• 类型存根文件（.pyi）现在在常量后面添加了空行（#340）

• # fmt: off和# fmt: on现在更加可靠

  • 它们现在也可以在括号对内部工作（#329）

  • 它们现在可以正确地跨越函数/类边界（#335）

  • 它们现在可以在缩进块以空行或错位的注释开始时工作（#334）

• 使Click在不合法的环境中不失败；请注意，Click是正确的，但我们需要在处理Python源代码时访问非ASCII文件路径的可能性很低（#277）

• 修复了包含嵌套表达式中的引号的f字符串的不当格式化（#322）

• 修复了在文件中发现长列表字面量时的不必要的减速

• 修复了具有非常多个兄弟姐妹的AST节点上的不必要的减速

• 修复了字符串规范化期间的贪婪反斜杠

• 修复了由于符号链接指向项目目录外部而导致的崩溃（#338）

18.6b2

• 添加了--config（#65）

• 添加了-h等价于--help（#316）

• 修复了使用-S时不当的未更改文件缓存

• 修复了字符串解包中的额外空格（#305）

• 修复了空的三引号字符串的格式化（#313）

• 修复了在没有注释的行上计算注释位置时的不必要的减速（#313）

18.6b1

• 热修复：不要在stdout上输出面向人类的信息（#299）

• 热修复：不要在非零返回代码上输出蛋糕表情符号（#300）

18.6b0

• 添加了--include和--exclude（#270）

• 添加了--skip-string-normalization（#118）

• 添加了 --verbose 选项 (#283)

• 现在在 --diff 选项中输出的头信息实际上符合统一的差异规范

• 修复了被不必要括号包裹的长简单赋值 (#273)

• 修复了当一行包含多行字符串时出现的不必要括号 (#232)

• 修复了在旧版 Click 中使用时 stdin 处理不正确的问题 (#276)

• Black 现在在原地格式化文件时保留行尾 (#258)

18.5b1

• 添加了 --pyi 选项 (#249)

• 添加了 --py36 选项 (#249)

• Python 语法 pickle 缓存与格式化缓存一起存储，使 Black 能够在 site-packages 不可写的情况下工作 (#192)

• Black 现在强制执行类级别文档字符串（和/或字段）及第一个方法之后的 PEP 257 空行

• 修复了在省略大表达式行分割时，尾部注释中存在独立注释时产生的无效代码 (#237)

• 修复了在 # fmt: off 部分中移除可选括号的问题 (#224)

• 修复了在非常长的导入中，星星被错误地包裹在可选括号中时产生的无效代码 (#234)

• 修复了在大表达式行分割时省略的尾部注释中，行内注释被移动后的不稳定的格式化问题 (#238)

• 修复了类声明和第一个方法之间没有类文档字符串或字段时出现的额外空行 (#219)

• 修复了函数签名和内部函数或内部类之间出现的额外空行 (#196)

18.5b0

• 调用链现在按照 流畅接口 风格进行格式化 (#67)

• 数据结构字面量（元组、列表、字典和集合）现在也像导入一样，当它们不能放在一行中时总是展开 (#152)

• 切片现在按照 PEP 8 进行格式化 (#178)

• 现在也自动管理赋值和返回语句右侧的括号 (#140)

• 数学运算符现在使用各自的优先级来界定多行表达式 (#148)

• 现在省略了以括号开头或结尾且仅包含单个运算符的表达式中的可选括号 (#177)

• 类定义中的空括号现在被移除 (#145, #180)

• 字符串前缀现在标准化为小写，并且在 Python 3.6+ 代码以及 Python 2.7+ 代码中使用 unicode_literals 未来导入时移除 u (#188, #198, #199)

• 类型存根文件（.pyi）现在按照 PEP 484 的一致风格进行格式化 (#207, #210)

• 重新格式化多个文件时的进度现在会逐个报告

• 修复了在缩进关闭括号之后不必要的将其内容（带有括号的）拆分到单独行的问题 (#119)

• 修复了在导入中有时留下无效的尾随逗号的问题 (#185)

• 修复了使用多个可移除括号对时的非确定性格式化问题 (#183)

• 修复了在长赋值中不必要地将多行字符串包裹在可选括号中 (#215)

• 修复了不分割只有单个名称的长 from-imports 的问题

• 修复了通过检查函数调用（带有解包的）来查找 Python 3.6+ 文件的问题。这修复了如果尾随逗号在带有星号的函数签名和带有星号的函数调用中都使用，但前者会被重新格式化为一行的情况。

• 修复了处理可选括号时的崩溃问题 (#193)

• 修复了 "is", "is not", "in", 和 "not in" 在分割目的上没有被考虑为运算符的问题

• 修复了遇到死符号链接时的崩溃问题

18.4a4

• 在 --check 选项中不填充缓存 (#175)

18.4a3

• 添加了“缓存”；已重新格式化但未更改的文件不会再次重新格式化 (#109)

• --check 和 --diff 选项不再互斥 (#149)

• 泛化了星号表达式处理，包括双星号；这修复了乘法使表达式对尾随逗号“不安全”的问题 (#132)

• Black 不再强制在控制流语句后放置空行（#90）

• Black 现在像 isort 的“模式 3 + 逗号后跟”那样分割导入（#127）

• 修复了独立注释关闭代码块时的注释缩进问题（#16, #32）

• 修复了在类、def 或装饰器之前立即出现的独立注释接收额外空行的问题（#56, #154）

• 修复了 --diff 不显示整个路径（#130）

• 修复了函数调用中星号和双星号之后的复杂表达式解析（#2）

• 修复了 lambda 参数中逗号上的无效分割（#133）

• 修复了三重条件表达式的缺失分割（#141）

18.4a2

• 修复了未对齐的独立注释的解析（#99, #112）

• 修复了字典字面量中字典拆包的位置（#111）

• Vim 插件现在在 Windows 上也能工作

• 修复了在字符串中遇到不必要的转义引号时的不稳定格式化（#120）

18.4a1

• 添加了 --quiet（#78）

• 添加了自动括号管理（#4）

• 添加了 pre-commit 集成（#103, #104）

• 修复了多个文件使用 --check 时的报告问题（#101, #102）

• 修复了从原始字符串中移除反斜杠转义符（#100, #105）

18.4a0

• 添加了 --diff（#87）

• 在所有分隔符之前添加换行符（除了逗号等），以更好地符合 PEP 8（#73）

• 将字符串字面量标准化为双引号（几乎）处处使用（#75）

• 修复了嵌套括号表达式中的独立注释处理；Black 将不再生成超长行或把所有独立注释放在表达式的末尾（#22）

• 修复了 18.3a4 回退：不要在带有尾随空白的空行上崩溃和燃烧（#80）

• 修复了 18.3a4 回退：使用 # yapf: disable 作为尾随注释会导致 Black 不输出文件的其余部分（#95）

• 在格式化许多文件时按下 CTRL+C，Black 不会因为与 asyncio 相关的异常而大惊失色

• 在模块级别只允许最多两个空行，并且在函数内部只允许单个空行（#74）

18.3a4

• # fmt: off 和 # fmt: on 已实现（#5）

• 自动检测格式化文件中已弃用的 Python 2 的 print 语句和 exec 语句的形式（#49）

• 在带类型的函数参数的默认值中使用适当的空格表示复杂表达式（#60）

• 当使用 --check 时，只返回退出代码 1（#50）

• 不要从方括号索引中移除单个尾随逗号（#59）

• 如果前一个因子叶不是数学运算符，则不要省略空白（#55）

• 如果它是第一个参数，则在关键字参数拆包中省略额外的空格（#46）

• 在 Sphinx 自动属性注释 中省略额外的空格（#68）

18.3a3

• 不要移除括号表达式之外的空白行（#19）

• 添加了从 stdin 到 stdin 的管道格式化能力（#25）

• 恢复了使用旧式 async 作为名称的格式化代码的能力（#20, #42）

• 进一步改进了 numpy 风格的数组索引处理（#33，再次）

18.3a2

• 将二进制运算符的位置更改为行首而不是行尾，遵循 PEP 8 最近的变更（#21）

• 在分割时忽略空括号对。这避免了非常奇怪的外观格式化（#34, #35）

• 如果调用只有一个参数，则删除尾随逗号

• 如果顶层函数由注释分隔，则在上方函数后不要放置四个空行

• 修复了导入后的新行的不稳定格式化

• 修复了如果最后一条语句是简单语句，则将后记独立注释意外折叠到最后一条语句的问题（#18, #28）

• 修复了 numpy 风格数组索引中的缺失空格（#33）

• 修复了基于星号的算术表达式后的多余空格（#31）

18.3a1

• 添加了 --check（#52）

• 仅在函数签名和调用中放置尾随逗号，如果这样做是安全的话。如果文件是Python 3.6+，则始终安全，否则只有在签名或调用中没有使用*args或**kwargs时才安全。（#8）

• 修复了相对导入中点的不正确间隔（#6，#13）

• 修复了for循环中解包变量后面逗号的不正确拆分（#23）

• 修复了括号内的集合表达式中多余的空间（#7）

• 修复了在默认参数中开括号后和默认参数中的多余空间（#14，#17）

• 修复了当操作数是一个复杂数表达式时一元运算符后面的多余空间（#15）

18.3a0

• 首次发布版本，2018年快乐🍰日！

• alpha质量

• 按日期版本化（见：https://calver.org/）