基础¶
有关使用和配置 Black 的基础知识。
Black 是一个行为良好的 Unix 风格命令行工具
如果它没有找到要格式化的源文件，它将不会做任何事情；
如果使用
-作为文件名，它将从标准输入读取并写入标准输出；它只向用户在标准错误中输出消息；
退出代码为 0，除非发生内部错误或 CLI 选项提示它。
用法¶
Black 将就地重新格式化整个文件。要立即使用合理的默认值开始
black {source_file_or_directory}
如果将 Black 作为脚本运行不起作用，则可以将其作为包运行
python -m black {source_file_or_directory}
忽略部分¶
Black 不会重新格式化包含 # fmt: skip 的行或以 # fmt: off 开头并以 # fmt: on 结尾的块。 # fmt: skip 可以与其他代码段/注释混合使用，可以使用多个注释（例如 # fmt: skip # pylint # noqa）或作为分号分隔的列表（例如 # fmt: skip; pylint; noqa）。 # fmt: on/off 必须位于相同的缩进级别和同一个块中，这意味着它们之间的缩进不能超出初始缩进级别。 Black 还出于对跨越代码的礼貌，识别 YAPF 的块注释，作用相同。
命令行选项¶
可以通过运行 black --help 来显示 Black 的 CLI 选项。所有选项在下面也进行了更详细的介绍。
虽然 Black 现在有很多旋钮，但它仍然是主观的，因此风格选项有意限制，并且很少添加。
请注意，上面列出的所有命令行选项也可以使用 pyproject.toml 文件进行配置（稍后将对此进行介绍）。
-h, --help¶
显示可用的命令行选项并退出。
-c, --code¶
格式化作为字符串传递的代码。
$ black --code "print ( 'hello, world' )"
print("hello, world")
-l, --line-length¶
每行允许多少个字符。默认值为 88。
另请参阅 风格文档.
-t, --target-version¶
Black 输出应支持的 Python 版本。您可以运行 black --help 并查找 --target-version 选项以查看支持的完整版本列表。您应该包含代码支持的所有版本。如果您支持 Python 3.8 到 3.11，您应该编写
$ black -t py38 -t py39 -t py310 -t py311
在 配置文件 中，您可以编写
target-version = ["py38", "py39", "py310", "py311"]
默认情况下，Black 将从 pyproject.toml 中的项目元数据推断目标版本，特别是 [project.requires-python] 字段。如果这没有产生确定的结果，Black 将使用逐文件自动检测。
Black 使用此选项来决定使用哪种语法来解析您的代码。此外，它可能会使用它来决定使用哪种风格。例如，在 Python 3.5 中添加了对函数调用中 *args 后面的尾部逗号的支持，因此 Black 只有在目标版本全部为 Python 3.5 或更高版本时才会添加此逗号
$ black --line-length=10 --target-version=py35 -c 'f(a, *args)'
f(
a,
*args,
)
$ black --line-length=10 --target-version=py34 -c 'f(a, *args)'
f(
a,
*args
)
$ black --line-length=10 --target-version=py34 --target-version=py35 -c 'f(a, *args)'
f(
a,
*args
)
--pyi¶
无论文件扩展名如何，都像类型存根一样格式化所有输入文件。这在将源代码管道到标准输入时很有用。
--ipynb¶
无论文件扩展名如何，都像 Jupyter 笔记本一样格式化所有输入文件。这在将源代码管道到标准输入时很有用。
--python-cell-magics¶
在处理 Jupyter 笔记本时，将给定魔术添加到已知 python-magics 的列表中。用于格式化具有自定义 python magic 的单元格。
-x, --skip-source-first-line¶
跳过源代码的第一行。
-S, --skip-string-normalization¶
默认情况下，Black 对所有字符串使用双引号并规范化字符串前缀，如 风格文档 中所述。如果给出此选项，则字符串将保持不变。
-C, --skip-magic-trailing-comma¶
默认情况下，Black 使用现有的尾部逗号作为短行应保持分开的指示，如 风格文档 中所述。如果给出此选项，则忽略魔术尾部逗号。
--preview¶
启用可能破坏性的风格更改，我们预计将在下一个主要版本中将其添加到 Black 的主要功能中。如果您想体验一下明年的风格，请使用它。
阅读更多关于 我们的预览风格.
此标志在不同版本之间产生的代码风格没有保证。
--unstable¶
启用 --preview 中的所有风格更改，以及我们最终希望做出的其他更改，但这些更改存在已知问题，需要修复才能移回 --preview 风格。如果您想尝试这些更改并帮助解决它们的问题，请使用它。
此标志在不同版本之间产生的代码风格没有保证。
--enable-unstable-feature¶
启用 --unstable 风格中的特定功能。查看 预览风格文档 以获取支持的功能列表。此标志只能在启用 --preview 时使用。如果用户使用 --preview 风格，并且影响其代码的功能从 --preview 移至 --unstable 风格，但他们希望避免因撤消此更改而产生的混乱，则鼓励他们使用此标志。
这些功能的行为，甚至它们的出现，在不同版本之间都没有保证。
--check¶
不要将文件写回，只返回状态。Black 将退出代码为
代码 0 如果没有任何变化；
代码 1 如果某些文件将被重新格式化；或者
代码 123 如果发生内部错误
如果与 --quiet 结合使用，则只返回退出代码，除非发生内部错误。
$ black test.py --check
All done! ✨ 🍰 ✨
1 file would be left unchanged.
$ echo $?
0
$ black test.py --check
would reformat test.py
Oh no! 💥 💔 💥
1 file would be reformatted.
$ echo $?
1
$ black test.py --check
error: cannot format test.py: INTERNAL ERROR: Black produced code that is not equivalent to the source. Please report a bug on https://github.com/psf/black/issues. This diff might be helpful: /tmp/blk_kjdr1oog.log
Oh no! 💥 💔 💥
1 file would fail to reformat.
$ echo $?
123
--diff¶
不要将文件写回，只输出差异以指示 Black 将会进行哪些更改。它们被打印到标准输出，因此捕获它们很简单。
如果您想要彩色差异，您可以使用 --color 启用它们。
$ black test.py --diff
--- test.py 2021-03-08 22:23:40.848954+00:00
+++ test.py 2021-03-08 22:23:47.126319+00:00
@@ -1 +1 @@
-print ( 'hello, world' )
+print("hello, world")
would reformat test.py
All done! ✨ 🍰 ✨
1 file would be reformatted.
--color / --no-color¶
显示（或不显示）彩色差异。仅在给出 --diff 时适用。
--line-ranges¶
当指定时，Black 将尽力只格式化这些行。
此选项可以多次指定，并且将格式化这些行的并集。每个范围必须指定为两个由 - 连接的整数：<START>-<END>。 <START> 和 <END> 整数索引从 1 开始，并且在两端都是包含的。
Black 仍然可以格式化多行语句范围之外的代码行。使用此选项格式化多个文件或任何 ipynb 文件不受支持。此选项不能在 pyproject.toml 配置中指定。
例如：black --line-ranges=1-10 --line-ranges=21-30 test.py 将格式化从 1 到 10 和从 21 到 30 的代码行。
此选项主要用于编辑器集成，例如“格式化选定内容”。
注意
由于 #4052，当存在具有完全相同内容的未格式化代码行时，--line-ranges 可能会格式化范围之外的额外代码行。它还会在 --safe 模式下禁用 Black 的格式化稳定性检查。
--fast / --safe¶
默认情况下，Black 在格式化代码后会执行 AST 安全检查。 --fast 标志会关闭此检查，而 --safe 标志会显式启用它。
--required-version¶
要求运行特定版本的 Black。这对于确保您的项目的所有贡献者都使用相同的版本非常有用，因为不同版本的 Black 可能会以略微不同的方式格式化代码。此选项可以在配置文件中设置，以确保跨环境的一致结果。
$ black --version
black, 24.8.0 (compiled: yes)
$ black --required-version 24.8.0 -c "format = 'this'"
format = "this"
$ black --required-version 31.5b2 -c "still = 'beta?!'"
Oh no! 💥 💔 💥 The required version does not match the running version!
您也可以只传递主版本
$ black --required-version 22 -c "format = 'this'"
format = "this"
$ black --required-version 31 -c "still = 'beta?!'"
Oh no! 💥 💔 💥 The required version does not match the running version!
由于我们的 稳定性策略，这将保证稳定的格式，但仍允许您利用不会影响格式的改进。
--exclude¶
一个正则表达式，用于匹配在递归搜索中应排除的文件和目录。空值表示不排除任何路径。在所有平台（包括 Windows）上，请对目录使用正斜杠。默认情况下，Black 还忽略 .gitignore 中列出的所有路径。更改此值将覆盖所有默认排除项。
如果正则表达式包含换行符，则它将被视为 详细正则表达式。这通常在 pyproject.toml 配置文件中设置这些选项时很有用；有关更多信息，请参阅 配置格式。
--extend-exclude¶
类似于 --exclude，但会在默认值的基础上添加额外的文件和目录，而不是覆盖它们。
--force-exclude¶
类似于 --exclude，但与该正则表达式匹配的文件和目录将被排除，即使它们被显式地作为参数传递。当以编程方式在更改的文件上调用 Black 时，这很有用，例如在 pre-commit 钩子或编辑器插件中。
--stdin-filename¶
通过 stdin 传递文件时的文件名。这对于确保 Black 尊重一些依赖于使用 stdin 的编辑器的 --force-exclude 选项非常有用。
--include¶
一个正则表达式，用于匹配在递归搜索中应包含的文件和目录。空值表示无论文件名如何都包含所有文件。在所有平台（包括 Windows）上，请对目录使用正斜杠。覆盖所有排除项，包括来自 .gitignore 和命令行选项的排除项。
-W, --workers¶
当 Black 格式化多个文件时，它可能会使用进程池来加速格式化。此选项控制并行工作程序的数量。这也可以通过 BLACK_NUM_WORKERS 环境变量指定。默认值为系统中的 CPU 数量。
-q, --quiet¶
停止发出所有非关键输出。错误消息仍然会发出（可以通过 2>/dev/null 静默）。
$ black src/ -q
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
-v, --verbose¶
发出有关未更改的文件或由于排除模式而被忽略的文件的消息。如果 Black 正在使用配置文件，则会发出详细说明它正在使用哪个配置文件的消息。
$ black src/ -v
Using configuration from /tmp/pyproject.toml.
src/blib2to3 ignored: matches the --extend-exclude regular expression
src/_black_version.py wasn't modified on disk since last run.
src/black/__main__.py wasn't modified on disk since last run.
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
reformatted src/black_primer/lib.py
reformatted src/blackd/__init__.py
reformatted src/black/__init__.py
Oh no! 💥 💔 💥
3 files reformatted, 2 files left unchanged, 1 file failed to reformat
--version¶
您可以使用 --version 标志检查已安装的 Black 版本。
$ black --version
black, 24.8.0
--config¶
从配置文件读取配置选项。有关配置文件的更多详细信息，请参阅 下面。
环境变量选项¶
Black 支持通过环境变量进行以下配置。
BLACK_CACHE_DIR¶
Black 应该存储其缓存的目录。
BLACK_NUM_WORKERS¶
Black 应该使用的并行工作程序的数量。命令行选项 -W / --workers 优先于此环境变量。
代码输入替代方案¶
Black 支持通过 stdin 格式化代码，并将结果打印到 stdout。只需让 Black 知道 - 作为路径即可。
$ echo "print ( 'hello, world' )" | black -
print("hello, world")
reformatted -
All done! ✨ 🍰 ✨
1 file reformatted.
提示：如果您需要 Black 将 stdin 输入视为直接通过 CLI 传递的文件，请使用 --stdin-filename。这对于确保 Black 尊重一些依赖于使用 stdin 的编辑器的 --force-exclude 选项非常有用。
您也可以使用 --code 选项将代码作为字符串传递。
写回和报告¶
默认情况下，Black 会就地重新格式化给定的文件和/或找到的文件。有时您需要 Black 只是告诉您它会做什么，而不会实际重写 Python 文件。
此模式有两个变体，它们由各自的标志独立启用
--check（如果任何文件将被重新格式化，则退出代码为 1）--diff（打印差异而不是重新格式化文件）
两种变体都可以同时启用。
输出详细程度¶
Black 通常尝试产生适当数量的输出，在实用性和简洁性之间取得平衡。默认情况下，Black 会发出已修改的文件和错误消息，以及简短的摘要。
$ black src/
error: cannot format src/black_primer/cli.py: Cannot parse: 5:6: mport asyncio
reformatted src/black_primer/lib.py
reformatted src/blackd/__init__.py
reformatted src/black/__init__.py
Oh no! 💥 💔 💥
3 files reformatted, 2 files left unchanged, 1 file failed to reformat.
--quiet 和 --verbose 标志控制输出详细程度。
通过文件进行配置¶
Black 能够从 pyproject.toml 文件中读取项目特定的命令行选项默认值。这对于为您的项目指定自定义 --include 和 --exclude/--force-exclude/--extend-exclude 模式特别有用。
专业提示：如果您在问自己“我是否需要配置任何内容？”，答案是“不”。Black 都是关于合理的默认值。应用这些默认值将使您的代码符合许多其他 Black 格式化的项目。
什么是 pyproject.toml 文件？¶
PEP 518 将 pyproject.toml 定义为一个配置文件，用于存储 Python 项目的构建系统要求。借助 Poetry、Flit 或 Hatch 等工具，它可以完全取代对 setup.py 和 setup.cfg 文件的需要。
Black 在哪里查找文件？¶
默认情况下，Black 会从命令行传递的所有文件和目录的公共基目录开始，查找包含 [tool.black] 部分的 pyproject.toml。如果没有找到，它会查找父目录。当找到文件或 .git 目录或 .hg 目录或文件系统根目录时，它会停止查找，以先发生者为准。
如果您正在格式化标准输入，Black 将从当前工作目录开始查找配置。
您可以使用存储在主目录中特定位置的“全局”配置。这将用作备用配置，也就是说，仅当Black 未找到上述任何配置时才会使用它。根据您的操作系统，此配置文件应存储为
Windows:
~\.black类 Unix（Linux、MacOS 等）：
$XDG_CONFIG_HOME/black（如果未设置XDG_CONFIG_HOME环境变量，则为~/.config/black）
请注意，这些是 TOML 文件本身的路径（这意味着它们不应命名为 pyproject.toml），而不是存储配置的目录。这里，~ 指向您的主目录的路径。在 Windows 上，这将类似于 C:\\Users\UserName。
您也可以使用 --config 显式指定要使用的特定文件的路径。在这种情况下，Black 将不会查找任何其他文件。
如果您使用 --verbose 运行，如果找到并使用了文件，您将看到一条消息。
请注意 blackd 将不会使用 pyproject.toml 配置。
配置格式¶
正如文件扩展名所暗示的，pyproject.toml 是一个 TOML 文件。它包含用于不同工具的单独部分。Black 使用 [tool.black] 部分。选项键与命令行上选项的长名称相同。
请注意，您必须在 TOML 中对正则表达式使用单引号字符串。它等同于 Python 中的 r 字符串。Black 将多行字符串视为详细的正则表达式。使用 [ ] 来表示一个重要的空格字符。
示例 pyproject.toml
[tool.black]
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
# 'extend-exclude' excludes files or directories in addition to the defaults
extend-exclude = '''
# A regex preceded with ^/ will apply only to files and directories
# in the root of the project.
(
^/foo.py # exclude a file named foo.py in the root of the project
| .*_pb2.py # exclude autogenerated Protocol Buffer files anywhere in the project
)
'''
查找层次结构¶
命令行选项具有默认值，您可以在 --help 中看到。一个 pyproject.toml 可以覆盖这些默认值。最后，用户在命令行上提供的选项将覆盖两者。
Black 在整个运行过程中只会使用一个 pyproject.toml 文件。它不会查找多个文件，也不会从文件层次结构的不同级别组合配置。
下一步¶
下一步是配置自动发现，这样 black . 就足够了，而不必费力地列出每个文件或目录。您可以通过前往 文件收集和发现 开始。
另一个不错的选择是设置您选择的 编辑器集成 或 用于源代码版本控制的 pre-commit。