常见问题解答¶

此常见问题解答汇总了用户面临的最常见问题和疑难解答。

为什么是空格？我更喜欢制表符¶

PEP 8 建议使用空格而不是制表符，并且大多数 Python 社区都使用空格。Black 不提供任何选项来配置缩进风格，并且不会考虑对此类选项的请求。

但是，我们认识到使用制表符是一个可访问性问题。虽然该选项永远不会添加到 Black 中，但视障开发者可能会发现诸如 expand/unexpand（适用于 Linux）之类的转换工具在为 Python 项目贡献代码时非常有用。工作流程可能包括例如设置适当的预提交和合并后 git 钩子，以及编写 unexpand 脚本，使其在应用 Black 后运行。

Black 有 API 吗？¶

还没有。Black 从根本上来说是一个命令行工具。提供了许多集成，但 Python 接口并非其中之一。不过，一个简单的 API 正在计划中。

使用 Black 安全吗？¶

是的。Black 严格来说只处理格式化，没有其他功能。Black 努力确保在格式化后，AST 会检查，并有少数例外情况，允许代码略有不同。如果发现问题，则会引发错误，并且文件保持不变。可能会移动影响 linter 和其他工具的魔法注释，例如 # noqa。有关更多详细信息，请参见下文。

Black 的风格有多稳定？¶

稳定。Black 旨在仅强制执行一种风格，并留有余地供务实考虑。有关更多详细信息，请参见Black 代码风格。

从 2022 年开始，同一年的发布的格式化输出是稳定的（不包括无意的错误）。每年年初，第一个版本都会对稳定的风格进行更改。您可以使用 --preview 标志选择加入最新的格式化风格。

为什么我的文件没有格式化？¶

很可能是因为它在 .gitignore 中被忽略或通过配置被排除在外。有关详细信息，请参见文件收集和发现。

为什么我的 Jupyter Notebook 单元格没有格式化？¶

Black 在格式化 Jupyter Notebook 时非常谨慎。包含以下任何内容的单元格将不会被格式化

自动魔法（例如 pip install black）
非 Python 单元格魔法（例如 %%writefile）。这些可以使用标志 --python-cell-magics 添加，例如 black --python-cell-magics writefile hello.ipynb。
多行魔法，例如
```
%timeit f(1, \
        2, \
        3)
```
代码，IPython 的 TransformerManager 会将魔法代码转换为，例如
```
get_ipython().system('ls')
```
无效语法，因为它在没有运行的 IPython 内核的情况下无法与自动魔法区分开来。

为什么 Flake8 报告警告？¶

Flake8 的一些规则与 Black 的风格冲突。我们建议禁用这些规则。参见将 Black 与其他工具一起使用。

Black 支持哪些 Python 版本？¶

当前，运行时需要 Python 3.8-3.11。格式化支持包含 Python 3.3 到 3.11 语法的文件。我们承诺至少支持所有尚未达到生命周期终结的 Python 版本。这适用于运行 Black 和格式化代码。

版本 22.0 中删除了对格式化 Python 2 代码的支持。虽然我们目前还没有计划立即停止支持旧的 Python 3 次要版本，但它们的支持可能会在将来某个时候被删除，而不会有弃用期。

版本 23.7.0 中删除了对 3.7 的运行时支持。

为什么我的 linter 或类型检查器在格式化代码后抱怨？¶

一些 linter 和其他工具使用魔法注释（例如，# noqa，# type: ignore）来影响它们的行为。虽然 Black 尽力识别这些注释并将其放置在正确的位置，但这种检测并不完美，也不可能完美。因此，在使用 Black 格式化代码库后，您有时需要手动将这些注释移动到正确的位置。

我可以用 PyPy 运行 Black 吗？¶

是的，支持 PyPy 3.8 及更高版本。

为什么 Black 没有检测到我的代码中的语法错误？¶

Black 是一款自动格式化工具，而不是 Python linter 或解释器。检测所有语法错误并非其目标。它可以格式化 CPython 接受的所有代码（如果您发现存在不符合该条件的示例，请报告错误！），但它也可能格式化 CPython 不接受的一些代码。

版本输出中的 `compiled: yes/no` 到底是什么意思？¶

虽然 Black 确实是一个纯 Python 项目，但我们使用 mypyc 将 Black 编译成 C Python 扩展，通常可以将性能提高一倍。这些编译后的 wheel 可用于所有支持的 CPython 版本的 Windows、Linux（通过 manylinux 标准）和 macOS 的 64 位版本。

目前，包括基于 musl 的和/或 ARM Linux 发行版，以及 ARM Windows 在内的平台不支持。这些平台将回退到 PyPI 上提供的较慢的纯 Python wheel。

如果您遇到非常奇怪的问题，甚至出现段错误，可以尝试在您的 pip install 调用中传递 --no-binary black。此标志会排除所有 wheel（包括纯 Python wheel），因此此命令将使用sdist。