PlateShapez 测试与代码质量:pytest、ruff、mypy 完整开发工作流

原创2026-11-02 12:44:431,608 阅读

PlateShapez 测试与代码质量:pytest、ruff、mypy 完整开发工作流

PlateShapez 是一款用于生成对抗性车牌扰动叠加数据集的研究工具。项目内置了一套完整的代码质量工作流:用 pytest 做测试、ruff 做格式化与代码检查、mypy 做静态类型检查,再通过 dev 命令和 pre-commit 钩子一键串联,本地、钩子与 CI 三端保持一致。本文带你快速跑通这套 PlateShapez 开发工作流。

🧭 开发工作流速览

PlateShapez 的工具链围绕 uv(Python 包管理器)组织,核心命令一览:

工具 命令 作用
ruff format uv run dev format 统一代码格式
ruff check uv run dev lint 代码检查并自动修复
mypy uv run dev type 静态类型检查
全量检查 uv run dev check format → lint → type 顺序执行
pytest uv run pytest 运行测试套件
pre-commit uv run dev hooks install 安装提交前自动检查钩子

整体流程是:写代码 → 格式化与检查 → 类型检查 → 跑测试 → 提交(钩子拦截)→ CI 复核。每一步都有对应的文档支撑,例如 docs/project_spec.md 中记录了 CI 与编码规范要求。

📦 环境准备:安装 uv 与开发依赖

# 克隆仓库
git clone https://gitcode.com/gh_mirrors/pl/PlateShapez
cd plateshapez

# 安装开发依赖(ruff、mypy、pytest、pre-commit 都在 dev 组里)
uv sync --group dev

开发依赖统一声明在 pyproject.toml 的 dependency-groups 中,包括 ruff、mypy、pytest、pre-commit 等,版本由 uv 统一管理,避免"我的环境没问题"的漂移问题。项目要求 Python >=3.10,<3.14,仓库根目录的 .python-version 文件会提示 uv 使用正确的解释器版本。

🧪 pytest 测试套件:四层测试覆盖

PlateShapez 的测试位于 tests/ 目录,按职责分成四个文件:

测试文件 覆盖范围
tests/test_config.py 配置加载、YAML/JSON 解析、深度合并、CLI 参数优先级
tests/test_perturbations.py shapes、noise、warp、texture 四种扰动算法的正确性
tests/test_pipeline.py 数据集生成管线:输出数量、元数据键、种子可复现性
tests/test_integration.py advplate CLI 命令的端到端集成测试

常用运行方式:

# 运行全部测试
uv run pytest

# 带覆盖率统计
uv run pytest --cov=plateshapez

# 只跑某一个文件
uv run pytest tests/test_pipeline.py

测试设计上有两个亮点值得学习:

  • 确定性验证:test_pipeline.py 中用相同随机种子运行两次管线,逐像素比对输出图像,确保结果可复现;
  • 异常路径覆盖:目录缺失、未知扰动名、不支持的配置格式等场景都有对应的 pytest.raises 断言,保证错误信息友好且可预期。

🎨 代码格式与 Lint:ruff

格式化和 Lint 都由 ruff 承担,配置集中在 pyproject.toml:

[tool.ruff]
target-version = "py312"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "I"]  # pycodestyle、pyflakes、isort 规则

日常使用只需两条命令:

uv run dev format   # 等价于 ruff format .
uv run dev lint     # 等价于 ruff check . --fix

--fix 参数意味着大量问题(如导入排序)会被自动修复,剩下的才需要你手动处理。项目规范(见 docs/project_spec.md)要求导入统一放在文件顶部、变量命名避免单字母缩写,这些都与 ruff 规则互相配合。

🧬 静态类型检查:mypy

PlateShapez 对类型检查采取了比较严格的配置(pyproject.toml 的 [tool.mypy] 段):

  • check_untyped_defs = true:未标注类型的函数体也要检查
  • disallow_incomplete_defs = true:不允许只标注一半参数
  • warn_unused_ignores = true:过期的 # type: ignore 会告警
  • mypy_path = "src":配合 src/ 布局解析包

另外 src/plateshapez/py.typed 是 PEP 561 标记文件,声明该包对外提供类型信息。运行检查:

uv run dev type   # 等价于 mypy .

⚡ 一键全量检查:dev check

三个检查串成一条龙的命令是 dev,其实现见 src/plateshapez/dev.py:

uv run dev check

它会按 format → lint → type 的顺序执行,任何一步失败立即中断,与 scripts/check.sh 的行为完全一致。不想安装包时,也可以用 Bash 封装 scripts/dev:

./scripts/dev check

🪝 pre-commit 钩子:提交前自动拦截

钩子配置在 .pre-commit-config.yaml,采用 local 仓库方式,直接通过 uv 调用项目内安装的 ruff 与 mypy:

- id: ruff-format
  entry: uv run ruff format .
- id: ruff
  entry: uv run ruff check . --fix
- id: mypy
  entry: uv run mypy .

三个钩子都注册在 pre-commit 和 pre-push 两个阶段,意味着提交和推送前都会检查。安装方式:

uv run dev hooks install      # 安装钩子
uv run dev pre-commit         # 手动对全部文件跑一遍

关键设计:钩子与 CI 走的是同一套 uv 环境,从根源上避免了"本地工具版本和 CI 不一致"导致的假失败。

☁️ CI 与本地保持一致

CI 工作流 .github/workflows/ci.yml 的逻辑非常简洁:

  1. uv sync --group dev 同步开发依赖
  2. 执行 ./scripts/check.sh(即 format、lint、type 三连)

因为本地 dev check、pre-commit 钩子、CI 三者调用的是同一条 scripts/check.sh 路径,你在本地通过检查,CI 基本必过。若需要自托管 runner,仓库还提供了 scripts/setup_runner.sh 辅助脚本。

🧹 保持工作区干净:cleanup

测试与 demo 会生成临时图片、数据集等文件。测试前建议重置到干净状态:

uv run dev cleanup         # 清理 demo 文件与数据集
uv run dev cleanup all     # 彻底清理(含 .venv 与构建产物)

其背后是 scripts/cleanup.py,也支持 --dry-run 预览将删除哪些文件,操作前心里有数。

📌 小结:PlateShapez 质量工作流清单

  • ✅ uv 统一管理依赖与工具版本(uv sync --group dev)
  • ✅ ruff 负责格式化与 Lint,--fix 自动修掉大部分问题
  • ✅ mypy 严格模式静态类型检查,配合 py.typed 提供类型信息
  • ✅ pytest 四层测试:配置、算法、管线、CLI 集成
  • ✅ dev check 一条命令串联全部检查,失败即中断
  • ✅ pre-commit + CI 走同一脚本,本地通过即 CI 通过

照着这套流程走,代码在提交前就会被层层过滤,写起来顺手,review 起来轻松。

登录后查看全文
PlateShapez