PlateShapez 测试与代码质量:pytest、ruff、mypy 完整开发工作流
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 的逻辑非常简洁:
uv sync --group dev同步开发依赖- 执行
./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 起来轻松。