更暗 2.1.1

是什么？

此实用工具可重新格式化和检查Python源代码文件。然而，在Git存储库中运行时，它将源树的老版本与较新版本（或工作树）进行比较。

• 它只在工作树的两个版本之间更改的区域中应用重新格式化，

• 并且只报告出现在源代码文件修改之后的linting消息。

支持的格式化器包括

• Black 用于代码重新格式化

• isort 用于排序导入

• flynt 用于将旧式格式字符串转换为f-strings

有关支持的linters列表，请参阅下文的使用linters。

要轻松地将Darker作为Pytest插件运行，请参阅pytest-darker。

要集成Darker到您的IDE或与pre-commit，请参阅本文件中相关的部分。

为什么？

您想使用Black在项目中开始统一代码样式。也许您还希望统一导入的排序方式，或对代码进行静态类型检查或其他静态分析。

然而，您不想在一次大提交中对整个代码库进行格式化，而是希望在修改代码的其他原因时才更改格式。

这在向您不完全控制的代码库贡献代码时也非常有用。

由于各种良好原因，Black 本身不支持部分格式化，迄今为止也没有实施该功能的计划（134，142，245，370，511，830）。然而，2021 年 9 月，Black 开发者开始暗示最终可能会添加此功能（1352）。这至少可以极大地简化 Darker 的算法。

但到目前为止，这正是 darker 的用武之地。这款工具是为那些希望立即进行部分格式化的人设计的。

请注意，此工具旨在处理现有代码库的特殊情况。您应该从头开始项目时直接使用 Black 和 isort。

您可能还需要考虑是否在一个提交中重新格式化整个代码库在您的情况下是有意义的。您可以使用 blame.ignoreRevsFile 配置选项或命令行上的 --ignore-rev 忽略重新格式化提交。有关此主题的深入了解，请参阅 Black 文档中的 Avoiding ruining git blame 或来自 Łukasz Langa（@ambv，Black 的创建者）的文章《Why does Black insist on reformatting my entire project?》。以下是摘录：

“当您进行这个单次重新格式化提交时，之后的所有内容都是 语义更改，因此您的提交历史在意义上是干净的，它实际上显示了意义上的更改，而不是风格。像 darker 这样的工具允许您只重新格式化自上次提交以来已修改的行。然而，通过这样做，您将永远暴露自己于混合了语义更改和风格更改的提交，这使得看到更改变得非常困难。”

如何？

要安装或升级，请使用

pip install --upgrade darker~=2.1.1

或者，如果您使用 Conda 进行包管理

conda install -c conda-forge darker~=2.1.1 isort
conda update -c conda-forge darker

注意：建议为 Darker 使用“~=”“兼容版本”版本说明符。有关更多信息，请参阅 Guarding against Black compatibility breakage。

darker <myfile.py> 或 darker <directory> 命令读取原始文件，使用 Black 对其进行格式化，根据编辑结合原始和格式化区域，并将它们写回到原始文件。

或者，您可以直接通过 python 可执行文件调用模块，这取决于您的设置。在这种情况下，请使用 python -m darker 而不是 darker。

默认情况下，darker 仅运行 Black 重新格式化代码。您可以使用命令行选项启用其他功能。

• -i / --isort: 使用 isort 重新排序导入。请注意，isort 必须在处理包的相同 Python 环境中运行，因为它会导入您的模块以确定它们是第一方模块还是第三方模块。

• -f / --flynt: 同时使用 flynt 包将字符串格式化转换为 f-strings

• -L <linter> / --lint <linter>: 运行受支持的代码检查器（参见使用代码检查器）

1.1.0 版本新增： -L / --lint 选项。1.2.2 版本新增： 包在 conda-forge 中可用。1.7.0 版本新增： -f / --flynt 选项

示例

本示例将指导您了解 Darker 的最小实际使用场景。

首先，创建一个空的 Git 仓库

$ mkdir /tmp/test
$ cd /tmp/test
$ git init
Initialized empty Git repository in /tmp/test/.git/

在该目录的根目录下，创建格式错误的 Python 文件 our_file.py

if True: print('hi')
print()
if False: print('there')

提交该文件

$ git add our_file.py
$ git commit -m "Initial commit"
[master (root-commit) a0c7c32] Initial commit
 1 file changed, 3 insertions(+)
 create mode 100644 our_file.py

现在修改该文件的第一行

if True: print('CHANGED TEXT')
print()
if False: print('there')

您可以要求 Darker 显示 diff 以进行最小格式化，使编辑的行符合 Black 规则

$ darker --diff our_file.py
--- our_file.py
+++ our_file.py
@@ -1,3 +1,4 @@
-if True: print('CHANGED TEXT')
+if True:
+    print("CHANGED TEXT")
print()
if False: print('there')

或者，Darker 可以输出完整的重新格式化文件（仅在命令行上提供一个 Python 文件时有效）

$ darker --stdout our_file.py

if True:
    print("CHANGED TEXT")
print()
if False: print('there')

如果您省略了 --diff 和 --stdout 选项，Darker 将替换命令行上列出的文件为部分格式化文件，如上所示

$ darker our_file.py

现在 our_file.py 的内容已更改。请注意，原始的 print() 和 if False: ... 行没有重新格式化，因为它们没有被编辑过！

if True:
    print("CHANGED TEXT")
print()
if False: print('there')

您也可以要求 Darker 重新格式化仓库中所有 Python 文件中编辑的行

$ darker .

或者，如果您想与另一个分支（实际上，任何提交）进行比较，而不是最后一个提交

$ darker --revision master .

自定义 darker、Black、isort、flynt 和代码检查器行为

darker 直接调用 Black 和 isort 的内部功能，而不是运行它们的二进制文件，因此它需要明确读取和传递配置选项给它们。项目的默认选项 darker 本身、Black 和 isort 从仓库根目录的 pyproject.toml 文件中读取。 isort 还会在其他一些地方查找配置。

Mypy、Pylint、Flake8 和其他兼容的代码检查器作为子进程由 darker 调用，因此这些工具的正常配置机制适用于每个工具。代码检查器也可以在命令行上配置，例如

darker -L "mypy --strict" .
darker --lint "pylint --errors-only" .

flynt（选项 -f / --flynt）也作为子进程调用，但当前不支持传递命令行选项给它。需要使用配置文件。

在递归目录时，Darker 在 Black 配置文件中尊重排除选项，但排除项仅适用于 Black 格式化。Isort 和代码检查工具仍然会在排除的文件上运行。此外，即使它们匹配排除模式，命令行上显式列出的单个文件仍然会被重新格式化。

更多详细信息，请参阅

• Black 关于 pyproject.toml 的文档

• isort 关于配置文件的文档

• 安装并运行 Darker 的公共 GitHub 仓库

• flynt 关于配置文件的文档

以下 命令行参数 也可以用来修改默认设置

-r REV, --revision REV

要比较的修订版本。默认为 HEAD..:WORKTREE:，这表示将最新提交与工作树进行比较。标签、分支名称、提交哈希以及其他如 HEAD~5 的表达式在这里都适用。还可以使用类似 main...HEAD 或 main... 的范围来比较最佳共同祖先。使用魔法值 :PRE-COMMIT:，Darker 会在 pre-commit 兼容模式下运行。Darker 期望从 PRE_COMMIT_FROM_REF 和 PRE_COMMIT_TO_REF 环境变量获取修订版本范围。如果这些未找到，Darker 将针对 HEAD 运行。另外，请参阅 --stdin-filename= 有关 :STDIN: 特殊值的说明。

--stdin-filename PATH

当通过 stdin 传递时文件的路径。这有助于 Darker 从 Git 中找到先前的版本。仅在 --revision=<rev1>..:STDIN:（如果启用了 --stdin-filename，默认为 HEAD..:STDIN:）中有效。

-c PATH, --config PATH

让 darker、black 和 isort 从 PATH 读取配置。请注意，像 flynt、mypy、pylint 或 flake8 这样的其他工具不会使用此配置文件。

-v, --verbose

显示采取的步骤并总结修改

-q, --quiet

减少输出量

--color

即使在非终端输出中也能启用语法高亮。覆盖环境变量 PY_COLORS=0

--no-color

即使在终端输出中也能禁用语法高亮。覆盖环境变量 PY_COLORS=1

-W WORKERS, --workers WORKERS

允许的并行工作进程数量，或 0 表示每个核心一个 [默认: 1]

--diff

不要写回文件，只为每个文件在 stdout 上输出一个 diff。如果在终端上且 pygments 包可用，或由配置启用，则突出显示语法。

-d, --stdout

强制将完整的格式化输出写入 stdout，而不是原地修改。仅当有一个文件要格式化时有效。如果在终端上且 pygments 包可用，或由配置启用，则突出显示语法。

--check

不要写回文件，只返回状态。返回码 0 表示没有任何更改。返回码 1 表示某些文件将被重新格式化。

-f, --flynt

还将字符串格式化转换为使用 f-strings，并使用 flynt 包

-i，--isort

同时使用 isort 包排序导入

-L CMD，--lint CMD

在更改的文件上运行一个代码检查器。 CMD 可以是代码检查器二进制文件的名称或路径，也可以是一个包含命令和选项的完整引号命令行。代码检查器按照常规读取它们的配置，并且不受 -c / --config 的影响。如果通过终端运行并在显式启用（请参阅 --color）的情况下运行，并且 pygments 包可用，则代码检查器的输出将以语法高亮显示。

-S，--skip-string-normalization

不要规范化字符串引号或前缀

--no-skip-string-normalization

规范化字符串引号或前缀。这可以用来覆盖 Black 配置文件中的 skip-string-normalization = true。

--skip-magic-trailing-comma

跳过向按逗号分割的表达式添加尾随逗号，其中每个元素都在其自己的行上。这包括函数签名。这可以用来覆盖 Black 配置文件中的 skip-magic-trailing-comma = true。

-l LENGTH，--line-length LENGTH

每行允许多少个字符 [默认: 88]

-t VERSION，--target-version VERSION

[py33|py34|py35|py36|py37|py38|py39|py310|py311|py312] Black 输出应支持的 Python 版本。 [默认: 文件自动检测]

要更改特定项目的这些选项的默认值，请在项目的根目录中的 pyproject.toml 文件中添加一个 [tool.darker] 部分，或使用 -c / --config 选项指定不同的 TOML 文件。

您应该使用各自的配置文件来配置调用的工具，如 Black、isort 和 flynt。

作为一个例外，[tool.darker] 中的 line-length 和 target-version 选项可以用来覆盖单个工具的相应选项。

请注意，当通过 darker 调用 Black 时，Black 仅遵守以下示例中列出的选项，因为 darker 读取 Black 配置并在通过其 Python API 直接调用 Black 时传递它。

示例 pyproject.toml 配置文件

[tool.darker]
src = [
    "src/mypackage",
]
revision = "master"
diff = true
check = true
isort = true
flynt = true
lint = [
    "pylint",
]
line-length = 80                  # Passed to isort and Black, override their config
target-version = ["py312"]        # Passed to Black, overriding its config
log_level = "INFO"

[tool.black]
line-length = 88                  # Overridden by [tool.darker] above
skip-magic-trailing-comma = false
skip-string-normalization = false
target-version = ["py38", "py39", "py310", "py311", "py312"]  # Overridden above
exclude = "test_*\.py"
extend_exclude = "/generated/"
force_exclude = ".*\.pyi"

[tool.isort]
profile = "black"
known_third_party = ["pytest"]
line_length = 88                  # Overridden by [tool.darker] above

请小心不要使用会产生其他工具意外输出的选项。例如，VSCode 只期望重格式化的 diff，所以不能与 lint = [ ... ] 一起使用。

自 1.0.0 版本新增

• 新增了 -c、-S 和 -l 命令行选项。

• isort 也使用 -c 和 -l 进行配置。

自 1.1.0 版本新增： 命令行选项

• -r / --revision

• --diff

• --check

• --no-skip-string-normalization

• -L / --lint

自 1.2.0 版本新增： 支持

• 在 -r / --revision 中的提交范围。

• 在 pyproject.toml 中的 [tool.darker] 部分。

1.2.2版本新增： 支持 -r :PRE-COMMIT: / --revision=:PRE_COMMIT:

1.3.0版本新增： 命令行选项 --skip-magic-trailing-comma 和 -d / --stdout

1.5.0版本新增： 命令行选项 -W / --workers，--color 和 --no-color

1.7.0版本新增： 命令行选项 -t / --target-version

1.7.0版本新增： 命令行选项 -f / --flynt

2.1.1版本新增： 在 [tool.darker] 中，弃用 Black 选项 skip_string_normalization 和 skip_magic_trailing_comma

编辑器集成

许多编辑器都有插件或配方来集成 Black。您可能可以将它们修改为与 darker 一起使用。请参阅 Black 文档中的编辑器集成。

set autoread
autocmd BufWritePost *.py silent :!darker %

(use-package reformatter
  :hook ((python-mode . darker-reformat-on-save-mode))
  :config
  (reformatter-define darker-reformat
    :program "darker"
    :stdin nil
    :stdout nil
    :args (list "-q" input-file))

用作pre-commit钩子

新版本1.2.1

要本地使用Darker作为Python项目的Git pre-commit钩子，请按照以下步骤操作

1. 在您的环境中安装pre-commit（有关详细信息，请参阅pre-commit安装）。

2. 创建基本pre-commit配置

   pre-commit sample-config >.pre-commit-config.yaml

3. 将以下行追加到创建的.pre-commit-config.yaml

   - repo: https://github.com/akaihola/darker
     rev: v2.1.1
     hooks:
       - id: darker

4. 安装Git钩子脚本并更新到最新版本

   pre-commit install
   pre-commit autoupdate

在自动更新时，会采取措施保护您免受Black更新引入的可能不兼容性。有关更多信息，请参阅防止Black兼容性破坏。

如果您想保持稳定但不更新pre-commit设置，可以将Black和其他您使用的重格式化/代码检查工具锁定到已知兼容版本，例如

- repo: https://github.com/akaihola/darker
  rev: v2.1.1
  hooks:
    - id: darker
      args:
        - --isort
        - --lint
        - mypy
        - --lint
        - flake8
        - --lint
        - pylint
      additional_dependencies:
        - black==22.12.0
        - isort==5.11.4
        - mypy==0.990
        - flake8==5.0.4
        - pylint==2.15.5

- repo: https://github.com/akaihola/darker
  rev: v2.1.1
  hooks:
    - id: darker
      args: [--isort]
      additional_dependencies:
        - isort~=5.9

GitHub Actions集成

您可以在不设置自己的Python环境的情况下，在GitHub Actions工作流中使用Darker。这对于强制您的代码修改和添加符合Black代码风格非常有用。

name: Lint

on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-python@v5
      - uses: akaihola/[email protected]
        with:
          options: "--check --diff --isort --color"
          src: "./src"
          version: "~=2.1.1"
          lint: "flake8,pylint==2.13.1"

使用代码检查工具

使用 Darker 的一种方法是通过过滤代码检查工具的输出，只显示在源代码文件修改之后出现的代码检查工具消息，以及关于修改行的旧消息。Darker 支持以下格式的任何代码检查工具的输出

<file>:<linenum>: <description>
<file>:<linenum>:<col>: <description>

以下代码检查工具已被验证可以与 Darker 一起使用

• Mypy 用于静态类型检查

• Pylint 用于代码的通用静态检查

• Flake8 用于强制执行风格指南

• cov_to_lint.py 用于测试覆盖率

版本 1.1.0 的新功能： 支持 Mypy、Pylint、Flake8 和兼容的代码检查工具。

版本 1.2.0 的新功能： 支持使用 cov_to_lint.py 输出测试覆盖率。

要运行代码检查工具，请使用 --lint / -L 命令行选项与代码检查工具命令或传递给代码检查工具的完整命令行。以下是一些示例

• -L flake8：使用Flake8强制执行Python风格指南

• -L "mypy --strict"：使用Mypy进行静态类型检查

• --lint="pylint --ignore='setup.py'"：使用Pylint分析代码

• -L cov_to_lint.py：读取.coverage并列出未覆盖的修改行

注意：在Windows上，完整的命令行并未完全测试。有关可能的错误，请参阅#456问题。

Darker还将linter输出分组为连续的行块，这些块由空白行分隔。以下为cov_to_lint.py输出的示例

$ darker --revision 0.1.0.. --check --lint cov_to_lint.py src
src/darker/__main__.py:94:  no coverage:             logger.debug("No changes in %s after isort", src)
src/darker/__main__.py:95:  no coverage:             break

src/darker/__main__.py:125: no coverage:         except NotEquivalentError:

src/darker/__main__.py:130: no coverage:             if context_lines == max_context_lines:
src/darker/__main__.py:131: no coverage:                 raise
src/darker/__main__.py:132: no coverage:             logger.debug(

语法高亮显示

如果运行在终端上并且已安装Pygments包，Darker会自动启用--diff、-d/--stdout和-L/--lint选项的语法高亮显示。

您可以使用以下方法强制在非终端输出上启用语法高亮显示

• 在Python项目根目录的pyproject.toml中的[tool.darker]部分的color = true选项中，

• PY_COLORS=1环境变量，以及

• darker的--color命令行选项。

您可以使用以下方法在终端输出上强制禁用语法高亮显示

• 在pyproject.toml中的color = false选项，

• PY_COLORS=0环境变量，以及

• --no-color命令行选项。

在上面的列表中，后者的配置方法覆盖了先前的配置方法，因此命令行选项始终具有最高优先级。

防止与Black兼容性破坏

Darker访问了一些不属于其公共API的Black内部功能。因此，Darker可能会与Black的未来版本不兼容。

为了保护用户免受此类破坏，我们每天都会对Darker进行测试，以针对Black主分支，并努力通过此过程积极修复任何潜在的不兼容性。如果Black主分支的提交与Darker不兼容，我们将发布Darker的第一个补丁版本，以阻止升级Black，并发布第二个补丁版本以修复不兼容性。以下是一个假设的示例

1. Darker 9.0.0; Black 35.12.0 -> OK

2. Darker 9.0.0; Black main（在35.12.0之后）-> CI 测试未来工作流程中的ERROR

3. Darker 9.0.1已发布，约束条件为Black<=35.12.0 -> OK

4. Black 36.1.0已发布，但Darker 9.0.1阻止了升级；Black 35.12.0 -> OK

5. Darker 9.0.2已发布，并包含兼容性修复，移除约束条件；Black 36.1.0 -> OK

如果在修复它的第二个Darker补丁版本之前，Black的发布引入了与Darker的不兼容性，则第一个Darker补丁版本将降级Black到最新兼容版本

1. Darker 9.0.0; Black 35.12.0 -> OK

2. Darker 9.0.0; Black 36.1.0 -> ERROR

3. Darker 9.0.1，约束条件为Black<=35.12.0；降级到Black 35.12.0 -> OK

4. Darker 9.0.2已发布，并包含兼容性修复，移除约束条件；Black 36.1.0 -> OK

为了完全安全，您可以将Darker和Black都固定在已知良好的版本上，但这可能会阻止您接收Black的改进。

建议使用Darker的“~=”“兼容版本”指定符，以确保在下一个可能引起兼容性问题的主要版本发布之前，您拥有最新版本。

有关更多信息，请参阅问题#382和PR#430。

它是如何工作的？

为了应用Black重排格式，并使更改行的格式字符串现代化，Darker执行以下操作：

• 使用--revision=REV1..REV2选项指定，对Python文件在REV1和REV2之间进行git diff。

• 记录在这些修订之间编辑或添加的行的当前行号。

• 如果用户启用了Flynt，则在编辑和添加的文件上运行flynt。

• 在编辑和添加的文件上运行Black。

• 比较格式化前后的差异，注意每个连续重排行的块。

• 丢弃没有编辑/添加行落在其上的重排块。

• 保留落在其上的某些编辑/添加行的重排块。

当指定了--isort选项时，对导入进行排序，Darker按照以下方式进行：

• 在应用Black之前，对每个编辑和添加的文件运行isort。

• 只有当编辑或添加的行中任何一行落在由isort修改的第一行和最后一行之间时，才保留这些修改。

• 如果由isort修改的第一行和最后一行之间的所有行在两个修订之间都没有变化，则丢弃该文件的导入排序修改。

有关linting支持工作原理的详细信息，请参阅Graylint文档。

局限性和解决方案

Black不支持原生部分格式化。因此，Darker允许Black重排整个文件。然后，根据两个修订之间是否有任何行被编辑或添加，Darker接受或拒绝Black接触到的连续行块。

由于该算法的性质，Darker通常无法像开发者手动那样仔细地最小化Black所做的更改数量。此外，根据对代码所做的更改类型，diff结果可能导致Darker以无效的方式应用重排。幸运的是，Darker始终检查重排结果是否转换为与原始代码相同的AST。如果不是这样，Darker将扩展块，直到找到有效的重排。因此，可能比必要的更大块代码被重排。

解决这些限制的最合理的方法是在将更改提交到存储库之前，审查Darker所做的更改，并取消任何不希望更改的更改。

许可证

BSD。请参阅LICENSE.rst。

先前的艺术作品

• black-macchiato

• darken（已弃用，改为使用Darker；感谢Carreau的灵感！）

值得关注的有趣代码格式化和分析项目

以下项目以某种方式与Black或Darker相关。其中一些我们可能希望集成到Darker运行中。

• blacken-docs – 在文档文件中的Python代码块上运行Black

• blackdoc – 在文档代码片段上运行Black

• velin – 格式化遵循 numpydoc 规范的 docstrings

• diff-cov-lint – 仅针对 git diff 的 Pylint 和覆盖率报告

• xenon – 监控代码复杂性

• pyupgrade – 升级语言新版本的语法（见 #51）

• yapf – Google 的 Python 格式化器

• yapf_diff – 仅对修改过的行应用 yapf 或其他格式化器

贡献者 ✨

查看贡献者名单，请参阅 README.rst。

本项目遵循 all-contributors 规范。欢迎任何形式的贡献！

GitHub 星标趋势