基于pre-commit的Python代码规范落地实践

# 简介

pre-commit 是一个开源工具，用于管理和执行 Git 钩子，确保代码库的一致性和质量。通过在提交代码前自动运行代码风格检查（Linting）和格式修正（Formatting），它有助于保持项目代码的统一标准。本文将通过一个 Python 项目的实例，展示如何配置 pre-commit 工作流。

本文旨在介绍使用 pre-commit 对 Python 项目进行代码检查的方法，以提前发现并解决代码中的问题，提高代码的整体质量。文中提及的所有代码示例可以在 pre-commit-demo (opens new window) 找到。

# 使用

安装

首先，安装 pre-commit：

pip install pre-commit

安装成功后，您可以通过以下命令验证安装是否成功：

$ pre-commit --version 
pre-commit 4.2.0

1
2

接下来，设置 Git 钩子脚本：

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

1
2

创建配置文件在项目的根目录下创建 .pre-commit-config.yaml 文件，并推荐使用最新稳定版：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v2.3.0
    hooks:
      - id: check-yaml
      - id: check-json
      - id: check-toml
      - id: end-of-file-fixer
      - id: trailing-whitespace
  - repo: https://github.com/psf/black
    rev: 22.10.0
    hooks:
      - id: black
  - repo: https://github.com/PyCQA/isort
    rev: 5.13.2
    hooks:
      - id: isort
  - repo: https://github.com/PyCQA/flake8
    rev: 7.2.0
    hooks:
      - id: flake8

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

配置文件说明:

repos: 包含要使用的仓库列表。
repo: 每个仓库的 URL。
rev: 版本号，建议使用最新稳定版。
hooks: 需要执行的钩子列表。
id: 各个钩子的标识符。

每个钩子 ID 的具体作用可参考相应仓库的官方文档。

执行与应用

在执行 commit 命令时，会自动调用配置文件中定义的钩子脚本，检查代码是否符合规范。例如：

$ pre-commit_demo % git add *
$ pre-commit_demo % git commit -m "add main.py"
Check Yaml...........................................(no files to check)Skipped
Check JSON...........................................(no files to check)Skipped
Check Toml...........................................(no files to check)Skipped
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
[main 27890fe] add main.py
 1 file changed, 1 insertion(+)
 create mode 100644 main.py

1
2
3
4
5
6
7
8
9
10
11
12
13

默认情况下，仅检查新添加或修改的文件。若需手动检查所有文件，可以使用如下命令：

$ pre-commit run --all-files
Check Yaml...............................................................Passed
Check JSON...........................................(no files to check)Skipped
Check Toml...............................................................Passed
Fix End of Files.........................................................Passed
Trim Trailing Whitespace.................................................Passed
black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed

1
2
3
4
5
6
7
8
9

如需临时跳过校验，可在 commit 命令中加上 --no-verify 参数：

$ git commit -m "add main.py" --no-verify

# 最佳实践

将.pre-commit-config.yaml纳入版本控制，确保团队配置一致
定期运行pre-commit autoupdate保持工具最新版本
优先修复而不是--no-verify，让规范成为肌肉记忆.

# 总结

通过本文的实践，我们已经为Python项目搭建了自动化代码质检流水线。pre-commit 就像一位尽职的代码审查员，帮我们做到：

规范守护者：自动执行代码格式化（Black/isort）和静态检查（flake8）
效率加速器：拦截问题在提交前，避免CI/CD环节反复返工
团队协作者：统一项目代码风格，降低多人协作成本

#编码工具

上次更新: 2025/05/13, 09:42:32