GitHub Actions 集成¶

您可以在 GitHub Actions 工作流程中使用 Black，而无需设置自己的 Python 环境。非常适合强制您的代码符合 Black 代码风格。

兼容性¶

已知此操作支持所有 GitHub 托管的运行器操作系统。此外，仅支持已发布的 Black 版本（即 PyPI 上可用的版本）。

最后，此操作使用 colorama 附加项安装 Black，因此 --color 标志应该可以正常工作。

用法¶

在您的存储库中创建一个名为 .github/workflows/black.yml 的文件，其中包含

name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: psf/black@stable

我们建议使用 @stable 标签，但如果您更喜欢的话，也存在每个版本的标签。请注意，您选择的动作版本独立于动作将使用的 Black 版本。

动作将使用的 Black 版本可以通过 version 配置，或从 pyproject.toml 文件中读取。 version 可以是任何有效的版本说明符，或者如果您想要一个确切的版本，则可以是版本号。要从 pyproject.toml 文件中读取版本，请将 use_pyproject 设置为 true。这将首先查看 tool.black.required-version 字段，然后查看 project.dependencies 数组，最后查看 project.optional-dependencies 表格。动作默认使用 PyPI 上可用的最新版本。仅支持从 PyPI 获取的版本，因此不支持任何提交 SHA 或分支名称。

如果您想包含 Jupyter Notebooks，则必须使用 jupyter 附加项安装 Black。可以通过 jupyter 配置安装附加项和包含 Jupyter Notebook 文件（默认值为 false）。

您还可以通过 options（默认为 '--check --diff'）和 src（默认为 '.'）配置传递给 Black 的参数。请注意，--check 标志是必需的，以便如果 Black 发现需要格式化的文件，则工作流程会失败。

以下是一个示例配置

- uses: psf/black@stable
  with:
    options: "--check --verbose"
    src: "./src"
    jupyter: true
    version: "21.5b1"

如果您想匹配 Black 的稳定性策略所涵盖的版本，您可以使用兼容的版本运算符（~=）

- uses: psf/black@stable
  with:
    options: "--check --verbose"
    src: "./src"
    version: "~= 22.0"

如果您想从 pyproject.toml 中读取版本，请将 use_pyproject 设置为 true

- uses: psf/black@stable
  with:
    options: "--check --verbose"
    src: "./src"
    use_pyproject: true