基础知识¶

关于为 Black 项目做出贡献的概述。

技术细节¶

优先使用最新版本的 Python 进行开发。您可以使用任何操作系统。

在您选择的虚拟环境中安装开发依赖项，例如

$ python3 -m venv .venv
$ source .venv/bin/activate # activation for linux and mac
$ .venv\Scripts\activate # activation for windows

(.venv)$ pip install -r test_requirements.txt
(.venv)$ pip install -e ".[d]"
(.venv)$ pre-commit install

在提交拉取请求之前，使用以下命令从 black 仓库的根目录运行 lint 和测试

# Linting
(.venv)$ pre-commit run -a

# Unit tests
(.venv)$ tox -e py

# Optional Fuzz testing
(.venv)$ tox -e fuzz

# Format Black itself
(.venv)$ tox -e run_self

开发¶

调用测试的更多示例

# Run all of the above mentioned, in parallel
(.venv)$ tox --parallel=auto

# Run tests on a specific python version
(.venv)$ tox -e py39

# pass arguments to pytest
(.venv)$ tox -e py -- --no-cov

# print full tree diff, see documentation below
(.venv)$ tox -e py -- --print-full-tree

# disable diff printing, see documentation below
(.venv)$ tox -e py -- --print-tree-diff=False

测试¶

Black 风格的所有方面都应该经过测试。通常，测试应作为文件创建在 tests/data/cases 目录中。这些文件最多包含三个部分

以 # flags: 开头的行，后面跟着一组命令行选项。例如，如果该行是 # flags: --preview --skip-magic-trailing-comma，则测试用例将在预览模式开启且魔术尾部逗号关闭的情况下运行。接受的选项大多是 Black 本身的选项的子集，除了 --minimum-version= 标志，该标志应在测试仅在较新版本的 Python 中才有效的语法功能时使用。此标志确保我们不会尝试在较旧版本上验证 AST，并且会测试在使用该功能时我们是否正确地自动检测了 Python 版本。有关接受的具体标志，请参阅 tests/util.py 中的 get_flags_parser 函数。如果省略此行，则使用默认选项。
用作格式化程序输入的 Python 代码块。
行 # output，后面跟着在之前代码块上运行 Black 后的输出。如果省略，则测试断言 Black 将保持输入代码不变。

Black 有两个 pytest 命令行选项，用于影响 tests/data/ 中的测试文件，这些文件被分成输入部分和输出部分，以 # output 行分隔。这些可以通过 tox 传递给 pytest，或者如果未使用 tox，则直接传递给 pytest。

`--print-full-tree`¶

在测试失败时，打印完整的具体语法树 (CST)，就像它在处理输入（“实际”）后的样子，以及在解析输出（“预期”）后产生的树。请注意，测试可能会在具有相同 CST 的情况下因不同的输出而失败。这曾经是默认值，但现在默认值为 False。

`--print-tree-diff`¶

在测试失败时，打印上面描述的树的差异。这是默认值。要将其关闭，请传递 --print-tree-diff=False。

新闻/变更日志要求¶

Black 具有 CI，它将检查 CHANGES.md 中是否有与您的 PR 相对应的条目。如果您认为此 PR 不需要变更日志条目，请在评论中说明，维护人员可以添加 skip news 标签以使 CI 通过。否则，请确保您有一行，格式如下

- `Black` is now more awesome (#X)

请注意，X 应为您的 PR 号码，而不是问题编号！要找出 X，请使用下一个 PR 号码。这并不完美，但节省了大量的发布开销，因为现在发布者无需再回去为每个版本找出要添加到 CHANGES.md 中的内容。

样式变更¶

如果变更会影响广告代码风格，请修改文档（Black 代码风格）以反映该变更。尽管修复格式化中意外错误的补丁不需要单独提及。如果变更使用 --preview 标志实现，请将变更包含在未来风格文档中，并在专门的“预览变更”标题下编写变更日志条目。

文档测试¶

如果您对文档进行了更改，您也可以测试它们是否仍可以在本地构建。

(.venv)$ pip install -r docs/requirements.txt
(.venv)$ pip install -e .[d]
(.venv)$ sphinx-build -a -b html -W docs/ docs/_build/

卫生¶

如果您正在修复错误，请添加测试。首先运行它以确认它失败，然后修复错误，再次运行它以确认它确实已修复。

如果添加新功能，请添加测试。实际上，始终添加测试。但是，在添加任何大型功能之前，请先为我们打开一个问题以先讨论想法。

最后¶

再次感谢您对改进项目的兴趣！当大多数人选择坐下来观看时，您正在采取行动。