aiohttp 贡献者质量门槛覆盖率统计口径与文档拼写检查的 CI 落地【免费下载链接】aiohttpAsynchronous HTTP client/server framework for asyncio and Python项目地址: https://gitcode.com/gh_mirrors/ai/aiohttpaiohttp 项目在 AGENTS.md 中为 AI 编码代理与人类贡献者明确了提交代码前的两条硬性质量门槛一是测试覆盖率报告codecov patch report同时覆盖tests/与aiohttp/两个目录二是文档拼写检查make doc-spelling作为 CI 硬门禁会读取每一个CHANGES/*.rst变更片段。本文以 aiohttp 仓库的源码、CI 配置与工具链为证据拆解这两条规则背后的工作原理、运行方式以及贡献者在本地复现检查的具体操作帮助你理解并遵守 aiohttp 的贡献门槛。背景这是一条 contrib 类变更说明本篇文章对应的原始记录来自变更片段 CHANGES/12580.contrib.rst属于 towncrier 分类中的contrib类型。根据 pyproject.toml 中[tool.towncrier]的类型定义contrib表示“影响贡献者体验的变更例如运行测试、构建文档、搭建开发环境”等内容与面向最终用户的功能变更feature和缺陷修复bugfix在性质上完全不同。该片段由bdraco提交它本身不改变任何运行时行为而是把既有的质量门槛显式写入 AGENTS.md让所有贡献者尤其是 AI 编码代理在开始编码前就能读到这些要求。变更片段记录了两项内容在 AGENTS.md 中说明coverage report 同时覆盖tests/与aiohttp/因此被 patch 的 stub 中不可达的防御性raise守卫以及测试中单向的 cleanup 分支都会在 codecov patch report 上显示为未覆盖。在 AGENTS.md 中说明文档拼写检查make doc-spelling是硬性 CI 门禁它会读取每一个CHANGES/*.rst片段提交前应在本地运行。规则一覆盖率报告覆盖tests/与aiohttp/两个目录覆盖率配置从何而来aiohttp 的测试体系默认就开启了覆盖率统计。查看 pytest.ini 中的addopts可以看到pytest 启动时预先加载pytest-cov插件并固定传入--cov --cov-config.coveragerc.toml --cov-contexttest --no-cov-on-fail也就是说只要在仓库根目录执行pytestpytest-cov就会按 .coveragerc.toml 的配置进行覆盖率采集。这份配置里有两处关键设置决定了“覆盖范围”[run] source [ ., ] source_pkgs [ aiohttp, ]source被设置为仓库根目录.意味着从仓库根目录能测量到的所有 Python 代码都在采集范围内其中既包括aiohttp/包本体也包括tests/目录下的测试代码本身。这正是片段中“coverage report coverstests/as well asaiohttp/”的配置层含义测试文件里的代码行同样会被覆盖率工具度量。此外.coveragerc.toml还设置了branch true分支覆盖率、core ctrace显式使用 C 追踪器避免 Python 3.14 默认sysmon追踪器拖慢测试速度、parallel默认开启配合 pytest-xdist 的--numprocessesauto并行测试以及show_missing true报告中列出未覆盖行。为什么测试代码的“未覆盖”会出现在 patch report 上这是本片段最有信息量的技术结论被 patch 的 stub 中不可达的防御性raise守卫以及测试中单向one-sided的 cleanup 分支都会在 codecov patch report 上显示为未覆盖uncovered。从源码结构看aiohttp 的测试与实现之间大量使用 monkeypatch / Mock 注入来模拟异常路径这会产生两类“有意写但不会真正执行”的代码防御性raise守卫例如在 aiohttp/client.py、aiohttp/cookiejar.py、aiohttp/helpers.py 等处源码中带有# type: ignore[unreachable]注释的raise/warn分支——它们是为了满足类型系统或防御未知路径而写的正常测试运行时不可达。当这些位置位于被 PR patch 触及的 stub 附近时codecov 的 patch 模式只统计本次 diff 涉及行的覆盖率就会把它们标记为未覆盖。测试中单向的 cleanup 分支测试代码里常见的try/finally清理逻辑、except兜底路径如果只覆盖了正常分支而异常分支从未被触发就会在 patch report 里以红色未覆盖行出现。这带来一个重要的贡献者心理预期管理在 aiohttp 中看到 codecov patch report 出现少量未覆盖行不一定是遗漏了测试可能是上述防御性代码被纳入统计的自然结果。片段将其写进 AGENTS.md正是为了减少贡献者在评审阶段对这类“假性未覆盖”的困惑。相关的覆盖率工具链aiohttp 还有一条完整的覆盖率上报链路常规 CI 测试任务在 .github/workflows/ci-cd.yml 中以pytest -m dev_mode --cov-append --cov-reportxml产出coverage.xml并通过codecov/codecov-actionv7上传附带CI-GHA、OS-*、Py-*等 flag。单独的cython-coverage任务使用另一份配置 .coveragerc-cython.toml相比默认配置额外加载了Cython.Coverage插件对 Cython 扩展代码单独统计并上传cython-coverage.xml。Autobahn WebSocket 协议测试任务.github/workflows/ci-cd.yml也独立上传覆盖率flag 为Autobahn。本地想快速查看 HTML 形式的覆盖率报告可以使用 Makefile 中的目标make cov-dev它会以--cov-reporthtml运行测试生成htmlcov/index.html并在终端输出打开路径见 Makefile。与“硬门槛”的关系覆盖率本身并不会因为某一行未覆盖就自动拦截 PR——aiohttp 并没有在.coveragerc.toml里设置fail_under该值被注释掉。真正的约束来自 codecov 的 patch 检查改动所涉及行的覆盖率如果显著下降CI 状态会变红。因此贡献者维护新代码时应当尽量让新增逻辑有对应测试覆盖同时理解防御性分支被计为未覆盖是正常现象。规则二make doc-spelling是硬性 CI 门禁读取每个 CHANGES 片段拼写检查命令的定义aiohttp 文档拼写检查的命令入口定义在根目录 Makefile.PHONY: doc-spelling doc-spelling: make -C docs spelling SPHINXOPTS-W --keep-going -n -E它进入docs/目录调用 Sphinx 的spellingbuilder并追加了一组严格的 Sphinx 选项-W把所有警告当作错误任何拼写错误都会导致命令失败--keep-going遇到错误后继续构建一次性报告所有问题-nnitpicky对文档中所有交叉引用做严格检查-E不缓存文档环境每次都全量重建确保结果可复现。docs/Makefiledocs/Makefile中的spelling目标则直接调用sphinx-build -b spelling生成拼写报告。拼写检查的实现sphinxcontrib-spelling拼写能力来自第三方 Sphinx 扩展sphinxcontrib-spelling其依赖声明在 requirements/doc-spelling.in-r doc.in sphinxcontrib-spelling; platform_system!Windows # We only use it in GitHub Actions CI/CD注意该依赖带环境标记platform_system!Windows——Windows 平台不会安装它因为 aiohttp 只在 GitHub Actions CI 的 Linux 环境使用拼写检查这与 docs/contributing.rst 中记录的“在 MacOS X 上运行拼写检查存在问题”互为印证。在 docs/conf.py 中扩展是按需加载的try: import sphinxcontrib.spelling # noqa extensions.append(sphinxcontrib.spelling) except ImportError: pass也就是说本地未安装该扩展时文档构建不受影响只有安装后才启用拼写 builder。同一文件还配置了spelling_exclude_patternsdocs/conf.py将 THREAT_MODEL.md 排除在拼写检查之外理由是它已由 pre-commit 中的 codespell 钩子覆盖见 .pre-commit-config.yaml避免双重检查同时注释说明该文件中的 STRIDE 列表会被拼写 builder 错误分词。为什么必须“读取每个 CHANGES/*.rst 片段”关键点在于make doc-spelling的检查范围是整个 Sphinx 文档工程而 towncrier 的变更片段同样参与文档构建。aiohttp 的 changelog 页面 CHANGES.rst 由 towncrier 在发版时根据CHANGES/目录下的片段文件自动拼接而成配置见 pyproject.tomldirectory CHANGES/、filename CHANGES.rst。因此任何新提交的CHANGES/*.rst片段都会成为文档树的一部分片段里的英文单词、专有名词、大小写变体都会被sphinxcontrib-spelling逐词校验。这就产生了一个对贡献者非常重要的推论一个拼写错误的 changelog 片段会直接导致 CI 的拼写检查任务失败。当拼写 builder 遇到它认为不认识的词时就会报错并导致-W下的构建失败。合法的技术词汇需要登记进白名单文件 docs/spelling_wordlist.txt这个文件目前收录了 426 行词条包括aiohttp、asyncio、multidict、brotli、awaitable、bodypartreader等库名、API 名和开发术语。在 CI 中的硬门禁形态拼写检查是 CI 中一个独立的 lint 任务。在 .github/workflows/ci-cd.yml 中可以看到完整流程以纯 Python 模式AIOHTTP_NO_EXTENSIONS: 1安装项目自身注释说明这一步“需要让 sphinxcontrib-spelling 能够识别allowlist一些依赖名称”按 requirements/doc-spelling.in 安装拼写检查依赖用-c锁定到 requirements/doc-spelling.txt 的固定版本执行make doc-spelling。该任务运行在lint-from-git作业中与黑格式化、mypy 等一起构成 lint 关卡失败即 CI 变红。这正是片段中“硬性 CI 门禁hard CI gate”的具体形态。本地运行方式在推送到远端之前本地应当执行make install-dev # 一次性的开发环境搭建安装依赖并 Cythonize见 Makefile make doc-spelling # 运行文档拼写检查其中make install-dev依赖 Makefile 中的.develop目标会完成依赖安装、llhttp 生成与pip install -e .。若只想最小化运行拼写检查也可以按 docs/contributing.rst 的指引在 Linux 上安装 enchant 后直接通过 pip 安装sphinxcontrib-spelling再执行sudo apt-get install enchant pip install sphinxcontrib-spelling make doc-spelling需要注意的是这条命令的检查范围包括全部CHANGES/*.rst片段因此新增或修改 changelog 片段后务必在本地跑一次避免把拼写错误带到 CI。与 codespell 的分工仓库里其实存在两套拼写检查职责不同make doc-spellingsphinxcontrib-spelling检查 Sphinx 文档树包括CHANGES/*.rst片段是 CI 硬门禁codespell挂在 .pre-commit-config.yaml 的 pre-commit 钩子里跳过*.pdf,*.svg,Makefile,CONTRIBUTORS.txt,venvs,_build等文件配置见 pyproject.toml 的[tool.codespell]。本地运行pre-commit run --all-files见 AGENTS.md即可覆盖 codespell 一类静态检查但codespell 无法替代make doc-spelling——后者检查的是构建后的文档产物两者互为补充。这两条规则的共同目标让 Agent 与人类贡献者行为对齐AGENTS.md 本身就是一份面向 AI 编码代理的操作手册其中 Build、Test、Lint Format、Documentation code style、Changelog、PRs 各节给出了可执行的操作规范。本次变更把覆盖率口径与拼写检查门槛显式写进这份文件本质上是把隐性知识codecov patch 的行为、拼写检查的覆盖范围变成贡献者开工前就能看到的显式规则从而减少两类最常见的返工贡献者看到 patch report 上的“未覆盖”行后误判为测试遗漏浪费时间补无意义的测试拼写错误的 changelog 片段导致 CI 变红不得不追加修复提交。结合 CHANGES/README.rst 中关于 changelog 片段的规范文件名遵循pr_number.category.rstcontrib类别用于“影响贡献者体验的变更”片段需用过去时并以-- by :user:github-username 署名可以看到 aiohttp 将元工作流变更也纳入版本记录——这正是contrib类别存在的意义。小结贡献 aiohttp 前值得记住的三件事覆盖率口径pytest默认开启pytest-covcoverage 同时测量tests/与aiohttp/被 patch 的 stub 中不可达的防御性raise、测试中的单向 cleanup 分支在 codecov patch report 上显示为未覆盖是预期行为不必强行“补”测试。拼写门禁make doc-spelling是 CI 硬性检查读取每一个CHANGES/*.rst片段本地推送前执行一次即可提前暴露问题合法技术词需加入 docs/spelling_wordlist.txt 白名单。行为对齐这些规则已固化在 AGENTS.md 中无论贡献者是 AI Agent 还是人类开发者都应先读文件、本地验证、再提交 PR让每一次改动都能顺利通过质量门槛。【免费下载链接】aiohttpAsynchronous HTTP client/server framework for asyncio and Python项目地址: https://gitcode.com/gh_mirrors/ai/aiohttp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考