Lintrunner

概述

lintrunner 是一个运行代码检查器的工具。它负责

• 决定哪些文件需要检查。
• 按照通用协议调用代码检查器。
• 收集结果并向用户展示。

目的是提供一个通用的配置和调用代码检查器的方式，这对于大型多语言项目非常有用。

lintrunner 的设计受到了 Meta 内部项目 linttool 的强烈启发。

安装

pip install lintrunner

使用方法

首先，您需要将配置文件添加到您的仓库中。有关更多信息，请参阅 代码检查器配置 部分。

然后，只需运行 lintrunner 来检查您的更改即可！

如何控制 lintrunner 要检查的路径

在没有参数的情况下运行时，lintrunner 将检查

• 在 HEAD 提交中更改的文件。
• 用户工作树中更改的文件。

它 不会 检查

• 任何未由 git 跟踪的文件；将它们添加到 git add 以进行检查。

有多种方式可以自定义路径检查方式

将路径作为位置参数传递

例如

lintrunner foo.py bar.cpp

这自然与 xargs 一起使用，例如检查仓库中每个路径的规范方法是

git grep -Il . | xargs lintrunner

--configs/ --config

逗号分隔的lintrunner配置文件路径。多个文件将合并，后定义覆盖先定义。仅在您的机器上需要存在第一个。默认为 lintrunner.toml, lintrunner.private.toml。额外的配置，如 lintrunner.private.toml，可用于结合项目级和本地配置。

--paths-cmd

某些调用 xargs 的方式会导致运行多个 lintrunner 进程，增加lint时间（尤其是在大型路径集上）。作为控制并行化的替代方案，您可以使用 --paths-cmd。如果指定了 --paths-cmd，则 lintrunner 将执行该命令，并考虑其 stdout 的每一行作为一个要lint的文件。

例如，上面的相同命令将是

lintrunner --paths-cmd='git grep -Il .'

--paths-file

如果指定此选项，lintrunner 将从给定文件中读取路径，每行一个，并检查这些路径。如果需要一些复杂的逻辑来确定要检查的路径，这可能很有用。

--revision

此值可以是 <tree-ish>，它是 git diff-tree 接受的，如提交哈希或revspec。如果指定了此值，lintrunner 将检查

• <tree-ish> 到 HEAD 之间更改的所有路径
• 用户工作树中更改的所有路径。

--merge-base-with

类似于 --revision，但修订版是通过计算 HEAD 和提供的 <tree-ish> 的合并基础来确定的。这对于lint特定拉取请求中的所有提交很有用。例如，对于针对master的拉取请求，您可以运行

lintrunner -m master

--all-files

这将运行所有在 .lintrunner.toml 中指定的文件的lint。

--only-lint-under-config-dir

如果设置，则只会lint配置文件所在目录及其子目录下的文件。

lint器配置

lintrunner 通过查看配置文件来确定运行哪些linters以及如何运行，配置文件通常命名为 .lintrunner.toml。

以下是一个示例lint器配置

merge_base_with = 'main'

[[linter]]
name = 'FLAKE8'
include_patterns = [
  'src/**/*.py',  # unix-style globs supported
  'test/**/*.py',
]
exclude_patterns = ['src/my_bad_file.py']
command = [
  'python3',
  'flake8_linter.py',
  '—-',
  # {{PATHSFILE}} gets rewritten to a tmpfile containing all paths to lint
  '@{{PATHSFILE}}',
]

配置架构的完整描述可以在 这里 找到。

lint器协议

大多数lint器都有自己输出格式和参数。为了在lint器调用和输出上强制一致性，lintrunner 实现了一个它期望linters遵守的协议。在大多数情况下，需要一个小的脚本（称为 lint器适配器）来实现特定外部linters的协议。您可以在 examples/ 中查看一些示例适配器。

调用

linters将根据配置中指定的 command 调用。它们将在每次lint运行时被调用一次。

如果lint器需要知道要运行的路径，则应使用 {{PATHSFILE}} 参数。在调用期间，字符串 {{PATHSFILE}} 将被替换为包含lint器应运行的路径的临时文件名，每行一个路径。

在lint器适配器中实现此功能的一种常见方式是使用 argparse 的 fromfile_prefix_chars 功能。在上面的Flake8示例中，我们使用 @ 作为 fromfile_prefix_chars 参数，因此 argparse 将自动读取 {{PATHSFILE}} 并将其内容作为参数列表提供。

输出

lint器希望向用户传达的任何lint消息都必须表示为 LintMessage。lint器必须将 LintMessage 打印为 JSON Lines 到 stdout，每行一个消息。到 stderr 的输出将被忽略。

LintMessage 架构的完整描述可以在 这里 找到。

退出

代码检查器应该始终以代码 0 退出。即使报告了代码检查错误，也是如此；lintrunner 将根据代码检查器的报告自行决定如何退出。

为了指示一个通用的代码检查器失败（理想情况下不应发生！），代码检查器可以返回一个 LintMessage，其中 path = None。

如果代码检查器以非零退出，它将被 lintrunner 捕获，并以“通用代码检查器失败”的形式呈现，将 stdout/stderr 显示给用户。这应被视为代码检查器实现此协议的bug。

在新的项目中采用 lintrunner 的技巧

在采用 lintrunner 的先前未进行代码检查的项目中，可能会生成大量的代码检查消息。您可以使用 --output oneline 选项让 lintrunner 将每个代码检查消息单独显示一行，以便快速浏览。

此外，您可以使用 --take 选项选择性地运行特定的代码检查器，例如 --take RUFF,CLANGFORMAT，以专注于解决特定的代码检查错误，或者使用 --skip 跳过像 MYPY 这样的长时间运行的代码检查器。

GitHub Action

要在 GitHub 工作流中使用 lintrunner，您可以考虑使用 lintrunner-action。