graylint 2.0.0

是什么？

这个实用工具会在Python源代码文件上运行代码检查器。然而，当在Git仓库中运行时，它会在旧的和新的源树修订版本中运行代码检查器。然后，它只会报告在修订版本之间的源代码文件修改后出现的代码检查消息。

要集成Graylint到您的IDE或与pre-commit，请参阅以下文档的相关部分。

为什么？

您想以更严格或更宽松的代码检查规则来检查您的代码。您的代码库已知违反了其中一些代码检查规则。

在运行代码检查器时，您只想看到与主分支分支点相比在您的开放功能分支中出现的新违规。

当向不受您完全控制的代码库贡献时，这也很有用。

请注意，此工具旨在用于处理现有代码库的特殊情况。您应该只在从头开始一个项目时力求100%符合代码检查规则。

如何？

要安装或升级，请使用

pip install --upgrade graylint~=2.0.0

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

conda install -c conda-forge graylint~=0.0.1
conda update -c conda-forge graylint

注意：建议为Graylint使用“~=”“兼容版本”的版本指定符。有关更多信息，请参阅防止代码检查兼容性破坏。

例如，使用graylint --lint pylint <myfile.py>或graylint --lint pylint <directory>命令会读取原始文件（s），在当前提交的原始状态下运行Pylint，然后再次在工作树中运行Pylint，最后过滤出两次运行中出现的消息。

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

默认情况下，graylint不会运行任何代码检查工具。您可以使用-L <linter> / --lint <linter>命令行选项启用单个代码检查工具。

示例

此示例将指导您了解Graylint的最小实际用法。

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

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

在该目录的根目录下，创建一个Python文件our_file.py，该文件违反了Pylint的一个规则

first_name = input("Enter your first name: ")
if first_name == "Guido":
    print("I know you")
else:
    print("Nice to meet you")

$ pylint our_file.py
************* Module our_file
our_file.py:1:0: C0114: Missing module docstring (missing-module-docstring)

------------------------------------------------------------------
Your code has been rated at 7.50/10 (previous run: 7.50/10, +0.00)

提交该文件

$ 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

现在修改该文件的第四行

first_name = input("Enter your first name: ")
if first_name == "Guido":
    print("I know you")
elif True:
    print("Nice to meet you")

$ pylint our_file.py
************* Module our_file
our_file.py:1:0: C0114: Missing module docstring (missing-module-docstring)
our_file.py:4:5: W0125: Using a conditional statement with a constant value (using-constant-test)

------------------------------------------------------------------
Your code has been rated at 6.00/10 (previous run: 7.50/10, -1.50)

您可以要求Graylint仅显示新出现的代码检查违规

$ graylint --lint pylint our_file.py
our_file.py:4:5: W0125: Using a conditional statement with a constant value (using-constant-test) [pylint]

您还可以要求Graylint运行仓库中所有Python文件的代码检查

$ graylint --lint pylint .

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

$ graylint --lint pylint --revision main .

自定义graylint和代码检查工具行为

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

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

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

-r REV，--revision REV

要比较的修订版。默认是HEAD..:WORKTREE:，它比较最新提交与工作树。标签、分支名称、提交散列以及其他如HEAD~5的表达式在这里有效。还可以使用范围如main...HEAD或main...来比较最佳共同祖先。使用魔法值:PRE-COMMIT:，Graylint以预提交兼容模式工作。Graylint期望从PRE_COMMIT_FROM_REF和PRE_COMMIT_TO_REF环境变量中获取修订范围。如果没有找到这些，Graylint将针对HEAD工作。有关:STDIN:特殊值，请参阅--stdin-filename=。

--stdin-filename PATH

通过stdin传递文件时的路径。这对于Graylint可以找到Git中的上一个版本非常有用。仅与--revision=<rev1>..:STDIN:（如果启用--stdin-filename，则为默认值HEAD..:STDIN:）一起使用。

-c PATH，--config PATH

从PATH读取Graylint配置。请注意，Graylint运行的代码检查工具不会读取此配置文件。

-v，--verbose

显示执行步骤并总结修改

-q，--quiet

减少输出量

--color

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

--no-color

即使对于终端输出，也禁用语法高亮。覆盖环境变量PY_COLORS=1

-W WORKERS，--workers WORKERS

允许多少个并行工作进程，或 0 表示每个核心一个 [默认：1]

-L CMD，--lint CMD

在更改的文件上运行一个检查器。 CMD 可以是检查器二进制文件的名或路径，或者是一个完整的带命令和选项的命令行。检查器按照常规读取它们的配置，不受 -c / --config 的影响。如果是在终端上运行或在显式启用的情况下（参见 --color），检查器输出将进行语法高亮。

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

[tool.graylint]
src = [
    "src/mypackage",
]
revision = "master"
lint = [
    "pylint",
]
log_level = "INFO"

编辑器集成

许多编辑器都有运行检查器的插件或配方。您可能可以将它们修改为与 graylint 一起使用。目前我们没有针对任何编辑器的特定说明，但我们欢迎对该文档的贡献。

作为预提交钩子使用

要将 Graylint 本地作为 Python 项目的 Git 预提交钩子使用，请执行以下操作

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

2. 创建一个基本预提交配置

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

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

   - repo: https://github.com/akaihola/graylint
     rev: 1.0.0
     hooks:
       - id: graylint

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

   pre-commit install
   pre-commit autoupdate

在自动更新时，我们会注意保护您免受由检查器更新引入的可能不兼容性。有关更多信息，请参阅 防止检查器兼容性中断。

如果您希望不更新但保持稳定的 pre-commit 设置，可以将您使用的检查器锁定到已知兼容的版本，例如

- repo: https://github.com/akaihola/graylint
  rev: 1.0.0
  hooks:
    - id: graylint
      args:
        - --isort
        - --lint
        - mypy
        - --lint
        - flake8
        - --lint
        - pylint
      additional_dependencies:
        - mypy==0.990
        - flake8==5.0.4
        - pylint==2.15.5

- repo: https://github.com/akaihola/graylint
  rev: 1.0.0
  hooks:
    - id: graylint
      args: [--lint "ruff check"]
      additional_dependencies:
        - ruff~=0.3.2

GitHub Actions 集成

您可以在不设置自己的 Python 环境的情况下在 GitHub Actions 工作流程中使用 Graylint。非常适合强制执行没有引入检查器回退。

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/graylint@2.0.0
        with:
          options: "-v"
          src: "./src"
          version: "~=2.0.0"
          lint: "flake8,pylint==2.13.1"

使用 linters

Graylint 支持以下格式之一输出结果的任何 linter

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

特别值得注意的是，以下 linters/checkers 已经过验证与 Graylint 兼容

• Mypy 用于静态类型检查

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

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

• cov_to_lint.py 用于测试覆盖率

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

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

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

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

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

注意：Windows 上尚未完全测试完整命令行。有关可能的错误（在 Graylint 代码起源地 Darker 中的错误）的详细信息，请参阅问题 #456。

Graylint 还将 linter 输出分组为由空行分隔的连续行块。以下是一个 cov_to_lint.py 输出的示例

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

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

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

语法高亮

如果 Graylint 在终端上运行并且已安装 Pygments 包，则会自动启用 -L/--lint 选项的语法高亮。

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

• 在 Python 项目的根目录下 pyproject.toml 文件的 [tool.graylint] 部分中使用 color = true 选项，

• 设置环境变量 PY_COLORS=1，以及

• 在 graylint 的命令行选项中使用 --color。

您还可以使用以下方法在终端输出中强制禁用语法高亮：

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

• 设置环境变量 PY_COLORS=0，以及

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

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

防止代码检查工具兼容性问题

Graylint 依赖于使用已知的命令行参数调用代码检查工具，并期望它们的输出符合定义的格式。如果这两个因素中的任何一个发生变化，Graylint 可能会与代码检查工具的未来版本不兼容。

为了保护用户免受此类中断的影响，我们每天都会测试 Graylint 与支持代码检查工具的主分支，并努力通过此过程主动修复任何潜在的不兼容性。如果一个提交到代码检查工具 main 分支的更改与 Graylint 不兼容，我们将发布第一个补丁版本以防止升级该代码检查工具，并发布第二个补丁版本以修复不兼容性。以下是一个假设的例子

1. Graylint 9.0.0; Pylint 35.12.0 -> OK

2. Graylint 9.0.0; Pylint main (35.12.0 之后) -> CI 工作流程中出错 test-future

3. Graylint 9.0.1 发布，约束条件 Pylint<=35.12.0 -> OK

4. Pylint 36.1.0 发布，但 Graylint 9.0.1 阻止升级；Pylint 35.12.0 -> OK

5. Graylint 9.0.2 发布，兼容性修复，约束条件删除；Pylint 36.1.0 -> OK

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

1. Graylint 9.0.0; Pylint 35.12.0 -> OK

2. Graylint 9.0.0; Pylint 36.1.0 -> ERROR

3. Graylint 9.0.1，约束条件 Pylint<=35.12.0；降级到 Pylint 35.12.0 -> OK

4. Graylint 9.0.2 发布，兼容性修复，约束条件删除；Pylint 36.1.0 -> OK

为了确保完全安全，您可以将 Graylint 和 Pylint 都锁定到已知的好版本，但这可能会阻止您接收 Black 的改进。

建议为 Graylint 使用 “~=” “兼容发布” 版本说明符，以确保在下一个可能引起兼容性问题的重大发布之前，您拥有最新版本。

有关更多信息，请参阅 Darker（该功能起源于该处）中的问题 #382 和 PR #430。

它是如何工作的？

Graylint 在您的存储库的两个不同修订版上运行代码检查工具，记录当前文件中哪些行已被编辑或添加，并跟踪它们在旧版本中的对应行。然后，它过滤掉在匹配行上出现在两个版本中的任何代码检查工具错误。最后，只显示新版本中剩余的错误。

许可证

BSD。请参阅 LICENSE.rst。

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

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

• Darker – 仅在修改的代码块中重新格式化代码

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

• xenon – 监控代码复杂度

贡献者 ✨

查看贡献者列表，请见 README.rst。

本项目遵循all-contributors规范。欢迎所有类型的贡献！

GitHub星标趋势