2. Python 项目开发工具

• 1. 常见工具
• 2. 工程化工具
  • 2.1 代码格式化
  • 2.2 pre-commit Git 钩子

1. 常见工具

2. 工程化工具

2.1 代码格式化

推荐全局安装 pipx 工具：

pip install pipx

项目如果使用了 black 和 isort 工具，建议使用 pre-commit 工具来管理，请参考下文。

Black 忽略文件

如果是 Qt 项目，则生成资源脚本（如 resources_rc.py）可能非常大，而 black 在大文件上的处理速度非常慢，可能导致程序假死。此时建议只用 Ruff 来格式化，或者在 black 中指定跳过格式化的文件，如：

black . --extend-exclude resources_rc.py

注意不要使用 --exclude 参数，因为这个参数不使用默认的排除列表，可能导致整个虚拟环境文件夹被格式化。

2.2 pre-commit Git 钩子

pre-commit 是一个用于管理 Git 钩子的工具，可以在提交代码前自动运行代码格式化、代码检查等工具。

推荐使用 pipx 安装 pre-commit：

pipx install pre-commit

使用 pre-commit 很简单，只需要在项目根目录下创建 .pre-commit-config.yaml 文件：

fail_fast: false

exclude: |
  (?x)^(
    .vscode/.*|
    uv.lock
  )$
repos:
  - repo: https://github.com/abravalheri/validate-pyproject
    rev: v0.22
    hooks:
      - id: validate-pyproject
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v5.0.0
    hooks:
      - id: check-added-large-files
      - id: check-builtin-literals
      - id: check-case-conflict
      - id: check-docstring-first
      - id: check-executables-have-shebangs
      - id: check-json
      - id: check-merge-conflict
      - id: check-toml
      - id: check-yaml
      - id: detect-private-key
      - id: end-of-file-fixer
      - id: mixed-line-ending
        args: [--fix=lf]
      - id: trailing-whitespace
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.7.1
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

在项目根目录下执行：

pre-commit install

现在，每次提交代码时，pre-commit 将会自动运行配置的钩子。

忽略文件

注意 exclude 字段中需要添加项目中所有需要忽略的文件，使用正则表达式匹配。

现在可以手动运行测试：

pre-commit run --all-files

自动更新规范版本：

pre-commit autoupdate