MLflow 仓库拼写检查实战:使用 typos 查找、修复与忽略拼写错误
MLflow 仓库拼写检查实战:使用 typos 查找、修复与忽略拼写错误
本指南面向 MLflow 项目贡献者与希望在自己仓库中落地拼写检查的开发者,系统讲解如何借助 typos 工具完成拼写错误的查找、批量修复与误报忽略。文章以 dev/typos.md 为骨架,结合 MLflow 仓库中真实的 pyproject.toml 配置与 .pre-commit-config.yaml 钩子定义,帮助你理解这套检查机制在 MLflow 中的完整落地方式,并掌握可直接复用的配置写法。
typos 在 MLflow 仓库中的角色
typos 是一个基于预置词典的拼写检查工具,它只报告词典中已知的拼写错误,不依赖语法分析,因此误报率低、执行速度快,非常适合作为 CI / pre-commit 检查的一部分。
在 MLflow 仓库中,typos 被注册为 pre-commit 钩子,定义于 .pre-commit-config.yaml:
- id: typos
name: typos
entry: bin/typos --format brief --color never
files: '\.(py$|mdx?$)'
language: system
stages: [pre-commit]
require_serial: true
pass_filenames: false
这段配置揭示了两个关键事实:
- 检查范围:
files: '\.(py$|mdx?$)'意味着typos只扫描 Python(.py)、Markdown(.md)与 MDX(.mdx)文件,其他类型的文件不参与检查。 - 执行方式:
entry: bin/typos --format brief --color never使用--format brief输出简洁的检查结果,并关闭颜色输出以便日志归档;pass_filenames: false表示整个仓库作为一个整体被扫描,而非逐文件传入。
安装 typos
在本地开发环境中,MLflow 推荐通过 Homebrew 安装与 CI 一致的版本:
# 将 <version> 替换为 dev/install-typos.sh 中安装的版本
brew install typos-cli@<version>
使用带版本号的安装方式,可以保证本地检查结果与 CI 完全一致,避免因工具版本差异导致"本地通过、CI 失败"的困扰。除 Homebrew 外,typos 官方还提供了 cargo install typos-cli、预编译二进制等安装途径,可按需选用。
查找拼写错误
查找仓库中的拼写错误只需一行命令:
pre-commit run --all-files typos
这条命令通过 pre-commit 框架调用上一节定义的 typos 钩子,对全仓库范围内符合 \.(py$|mdx?$) 规则的文件执行检查,并以 brief 格式输出命中项及对应文件位置。由于钩子配置了 require_serial: true,检查会在单个进程中串行执行,避免并发扫描带来的资源竞争。
若你尚未配置 pre-commit 环境,也可以直接调用 typos 二进制:
typos [PATH]
不带路径时默认扫描当前目录,并自动遵守 pyproject.toml 中的 [tool.typos.*] 配置段。
修复拼写错误
找到错误后,可以手动逐一修改,也可以借助 typos 的自动写入能力:
typos --write-changes [PATH]
--write-changes 会把检查到的拼写错误按词典中的正确拼写直接改写回文件中。[PATH] 是可选参数,用于把修改限定在指定路径范围内——例如只想修正 mlflow/store/ 目录下的文件时,传入该目录即可。
需要留意的是,自动改写适用于词典中明确给出的修正项;对于人工扩展词表或正则忽略的误报(见下文),--write-changes 不会触碰。批量改写前建议先跑一次不带 --write-changes 的检查,人工确认命中清单,再执行写入。
忽略误报
typos 依赖内置词典,难免会把代码中合法的变量名、缩写、专有名词判定为错误。MLflow 提供了两种处理误报的方式,分别对应"一次性"与"全局性"两种场景。
方式一:行内 / 块级忽略注释
当误报只是个别文件中的偶发情况时,推荐直接在源码中注释标记,让检查器跳过该行或该代码块:
# 忽略包含拼写"错误"的单行:
"<false_positive>" # spellchecker: disable-line
# 忽略一整块包含拼写"错误"的代码:
# spellchecker: off
"<false_positive>"
"<another_false_positive>"
# spellchecker: on
这两种注释指令之所以生效,是因为 MLflow 在 pyproject.toml 的 [tool.typos.default] 段用正则将其显式纳入忽略范围:
[tool.typos.default]
extend-ignore-re = [
# 行级忽略:以 `# spellchecker: disable-line` 结尾的行
"(?Rm)^.*#\\s*spellchecker: disable-line$",
# 块级忽略:`# spellchecker: off` 与 `# spellchecker: on` 之间的内容
"(?s)(#|//)\\s*spellchecker: off.*?\\n\\s*(#|//)\\s*spellchecker: on",
...
]
其中 (?Rm) 表示多行 + 无换行匹配的修正标志,(?s) 表示 . 可跨行匹配,从而让 off 与 on 之间的任意文本(含换行)整体被跳过。这意味着这两条注释约定是 MLflow 自定义并全局生效的规则,你在仓库中看到这类注释时,应理解为"这里经过人工确认、属于合法内容"。
方式二:扩展全局忽略列表
当同一个误报反复出现在多个文件、多行代码中时,逐行加注释显然不经济。此时应在 pyproject.toml 的 [tool.typos.default] 段扩展 extend-ignore-re 正则列表:
# pyproject.toml
[tool.typos.default]
extend-ignore-re = [
...,
"false_positive",
]
MLflow 仓库中实际维护的忽略正则极具代表性,涵盖了大量领域术语与测试文本,例如:
[tool.typos.default]
extend-ignore-re = [
# numpy.arange(`typos` 曾误报 arange)
"(?i)(numpy|np)\\.arange",
# nd array 相关写法
"(?i)nd( |_|\\.)?array",
# 用于测试的德语 / 法语句子
"MLflow ist",
"Ich habe eine schöne Haufe von Kokos",
"Apple Inc. ist ein",
"Apple Inc. est une entreprise technologique",
# pytorch-lightning
"lightning",
# `typos` 会把 'lok' 误判为 'look' 的拼写错误
"(?i)daniel lok",
# GitHub 用户名提及
"@[a-z0-9-]+",
# Azure 容器实例 / Kubernetes 服务缩写
"\\(ACI\\)", "\\(AKS\\)", "AKS",
# Journey 乐队歌词 "Don't Stop Believin'"
"livin'",
]
上述完整列表见 pyproject.toml#L516-L547。可以看出,这类忽略条目往往带有明确注释说明"为何它是合法的",便于后续维护者理解取舍依据。新增忽略项时,建议遵循同样的注释习惯。
发现拼写错误但 typos 不识别?
typos 的词典覆盖范围有限,某些仓库特有拼写(如缩写、内部术语)即使拼写正确也会被误报,而某些真实拼写错误也可能因不在词典中而被漏报。此时可以扩展 extend-words 词表,把词汇加入 [tool.typos.default.extend-words] 段:
# pyproject.toml
[tool.typos.default.extend-words]
...
mflow = "mlflow"
extend-words 的键值语义为"如果文本中出现键(mflow),则视为 mlflow 的拼写错误并按其修正"。MLflow 仓库自身的词表定义于 pyproject.toml#L483-L497,充分体现了"领域术语 + 内部缩写"的典型用法:
[tool.typos.default.extend-words]
aimd = "aimd" # additive increase multiplicative decrease(AIMD 拥塞控制)
als = "als" # alternating least squares(交替最小二乘)
mape = "mape" # mean absolute percentage error(平均绝对百分比误差)
fpr = "fpr" # false positive rate(假阳性率)
gam = "gam" # generalized additive models(广义加性模型)
ser = "ser" # serialization
yhat = "yhat" # ŷ(预测值符号)
iternal = "internal" # "internal" 的拼写错误
instumentation = "instrumentation" # "instrumentation" 的拼写错误
selectin = "selectin" # SQLAlchemy 懒加载策略
tpe = "tpe" # Tree-structured Parzen Estimator(hyperopt/optuna)
TPE = "TPE" # Tree-structured Parzen Estimator
indx = "indx" # 索引的有意简写
Tru = "Tru" # TruLens 库名前缀
这里存在两类语义截然不同的条目,值得区分:
- 修正真实错误:如
iternal = "internal"、instumentation = "instrumentation",作用是让typos --write-changes能自动修正仓库中残留的真实拼写错误; - 宣告合法词汇:如
tpe、ser、indx等,作用是向词典"登记"这些在 MLflow 上下文中合法(且意图明确)的写法,避免它们被误报或误改。
两种用法共用同一配置段,新增条目时应根据意图附上注释,方便后续维护。
控制扫描的文件范围
typos 默认会扫描仓库中几乎所有文本文件,但 MLflow 通过 pyproject.toml#L499-L514 的 [tool.typos.files] 段做了精细的"白名单 + 例外"管理:
[tool.typos.files]
extend-exclude = [
# 白名单:只检查下列扩展名
"*",
"!*/",
"!*.py",
"!*.md",
"!*.mdx",
# proto 文件虽然匹配 *.py,但这里再次排除
"mlflow/protos/**/*",
# 第三方 vendor 代码,不改动
"mlflow/utils/gorilla.py",
# 子模块内容,应在上游修复而非在此修改
"mlflow/assistant/skills/**/*",
]
配置逻辑为:先用 "*" 排除一切文件,再用 "!*.py"、"!*.md"、"!*.mdx" 反向加入允许检查的类型;随后进一步排除三组例外——自动生成的 proto 代码、vendored 的 gorilla.py、以及作为子模块引入的 mlflow/assistant/skills 目录。这与你此前看到的 pre-commit 钩子 files 规则(\.(py$|mdx?$))相互印证,构成"钩子入口 + 工具内层"的双重范围控制。
延伸:MLflow 品牌拼写的专项检查
除了通用拼写检查,MLflow 还维护了一个针对品牌名拼写的专项脚本 dev/mlflow-typo.sh。它用正则 ' \bM(lf|LF|lF)low\b' 扫描代码,揪出把 MLflow 误写成 Mlflow 的拼写错误:
- 允许的例外模式为
Mlflow\(|"Mlflow"|import Mlflow$(例如字符串常量或 import 语句中的大小写); - 通过
EXCLUDED_FILES数组跳过不受控制的 i18n JSON 文件、StringUtils.ts及对应测试文件; - 命中时输出提示并返回退出码 1,在 CI 中使检查失败。
它适用于 typos 词典未必覆盖的大小写语义问题,是通用拼写检查之外的有效补充。
总结:MLflow 拼写检查的完整工作流
结合上述内容,MLflow 仓库的拼写检查体系可以归纳为一条完整链路:
- 安装:
brew install typos-cli@<version>,与 CI 版本保持一致; - 触发:通过
.pre-commit-config.yaml中的typos钩子执行bin/typos --format brief --color never,仅扫描.py/.md/.mdx文件; - 范围控制:
[tool.typos.files]段通过白名单 + 例外排除 proto、vendored 与子模块代码; - 误报处理:偶发误报用
# spellchecker: disable-line/off/on注释就地跳过;全局误报在extend-ignore-re中添加正则; - 词表扩展:真实错误在
extend-words中登记以启用自动修正,合法术语同样在此登记以防误报; - 批量修复:确认命中清单后执行
typos --write-changes [PATH]自动改写; - 品牌专项:用 dev/mlflow-typo.sh 额外拦截
Mlflow大小写误写。
对于任何希望把拼写检查集成进日常开发流程的团队,这套"通用工具 + 精细配置 + 专项脚本"的组合方式都值得直接借鉴:它既保证了检查的自动化与一致性,又通过词典扩展、正则忽略和范围白名单,把误报干扰降到最低,让拼写检查真正成为提升代码库质量与可检索性的可靠一环。
如果你想进一步了解各配置项的完整语义,可直接阅读仓库根目录的 pyproject.toml([tool.typos.*] 三段配置)以及 .pre-commit-config.yaml 中的钩子定义。