interrogate 命令行完全指南19 个参数精准控制 docstring 覆盖率检查【免费下载链接】interrogateExplain yourself! Interrogate a codebase for docstring coverage.项目地址: https://gitcode.com/gh_mirrors/in/interrogateinterrogate 是一款开源的 Pythondocstring 覆盖率检查命令行工具它逐个扫描代码中的模块、类、方法与函数精确统计哪些写了文档字符串、哪些没有并输出覆盖率百分比。对于想把代码文档质量管起来的团队和个人开发者interrogate 是把 docstring 覆盖率变成可量化指标的终极利器。本文将带你从零上手一次性掌握它的19 个核心参数并学会用pyproject.toml、CI/CD 把覆盖率检查固化到日常流程中。interrogate 是什么为什么需要 docstring 覆盖率检查Python 的 docstring 是写在模块、类、函数开头的一段字符串文档。它是help()、Sphinx、pydoc 等工具的数据源但很多项目写代码时常常忘了补文档。interrogate 正是为了解决文档到底写了多少这个问题而生量化文档健康度用百分比告诉你项目文档覆盖了多少告别凭感觉守住底线接入 CI/CD 后覆盖率不达标就构建失败强制新代码补文档精准定位-vv详细模式直接列出每一个漏网之鱼所在文件与行号。interrogate 支持 Python 3.8 及以上版本安装只需一条命令pip install interrogate快速上手第一条 interrogate 命令在项目根目录直接运行不传路径则默认扫描当前目录$ interrogate RESULT: PASSED (minimum: 80.0%, actual: 100.0%)默认要求覆盖率不低于 80%达标显示PASSED否则返回FAILED并让进程以退出码 1 结束——这正是它能在 CI 里当门卫的关键。加上-v查看每个文件的摘要统计$ interrogate -v src Coverage for /path/to/project/src/ ------------------------------------ Summary ------------------------------------ | Name | Total | Miss | Cover | Cover% | |--------------------------------|---------|--------|---------|----------| | interrogate/__init__.py | 1 | 0 | 1 | 100% | | interrogate/cli.py | 2 | 0 | 2 | 100% | | interrogate/partial.py | 29 | 19 | 10 | 34% | |--------------------------------|---------|--------|---------|----------| | TOTAL | 32 | 19 | 13 | 40.6% | ---------------- RESULT: FAILED (minimum: 80.0%, actual: 40.6%) ----------------再加上一档-vv还会多出详细覆盖率表逐个列出每个类、方法、函数的COVERED/MISSED状态和行号方便直接去补文档。这些输出逻辑都实现在 coverage.py 中。19 个核心参数速查表interrogate 的命令行参数都定义在 cli.py 中除去辅助项核心可配置参数正好 19 个先收藏这张速查表参数作用默认值-v, --verbose输出详细程度可叠加-v/-vv0-q, --quiet不打印任何输出关闭-f, --fail-under低于该覆盖率则失败80.0-e, --exclude排除文件/目录可多次指定空-i, --ignore-init-method忽略类的__init__方法关闭-I, --ignore-init-module忽略__init__.py模块关闭-m, --ignore-magic忽略魔法方法不含__init__关闭-M, --ignore-module忽略模块级 docstring关闭-C, --ignore-nested-classes忽略嵌套类关闭-n, --ignore-nested-functions忽略嵌套函数与内部方法关闭-O, --ignore-overloaded-functions忽略typing.overload装饰函数关闭-p, --ignore-private忽略双下划线开头的私有成员关闭-P, --ignore-property-decorators忽略 property getter/setter/deleter关闭-S, --ignore-setters忽略 property setter 方法关闭-s, --ignore-semiprivate忽略单下划线开头的半私有成员关闭-r, --ignore-regex按正则忽略指定名称可多次指定空--ext额外扫描.pyi等 Python 类文件空-w, --whitelist-regex按正则白名单只统计指定名称空--styledocstring 风格sphinx/googlesphinx下面按类别逐一详解。控制输出与检查结果-v、-q、--fail-under三档输出详细程度-v 与 -vv 不加参数只打印一行RESULT: PASSED/FAILED-v额外输出每个文件的摘要表-vv在摘要表基础上追加逐成员的详细覆盖表。注意在pyproject.toml里配置时verbose1对应-vverbose2对应-vv。静默模式-q 只关心退出码、不关心输出时使用非常适合接入 CI 任务interrogate --quiet --fail-under 95 src tests覆盖率门槛--fail-under 类型可以是整数或浮点数如--fail-under 95.5。计算规则为已覆盖数 / 总数 × 100%当结果低于门槛时退出码为 1。控制扫描范围-e、--ext排除指定路径--exclude 自动生成文档、迁移脚本这类文件往往不需要 docstring用-e排除可多次指定interrogate -v -e docs -e setup.py -e tests/fixtures srcinterrogate 默认还会自动排除.tox、.venv、venv、.git、.hg等常见目录。扫描 .pyi 等类型文件--ext 默认只扫描.py文件想顺带检查类型存根.pyi文件时interrogate --ext pyi src13 个 ignore 参数按需豁免检查对象忽略参数是 interrogate 的精华它们的作用从代码注释到魔法方法全覆盖逻辑实现在 visit.py 的 AST 遍历器中。模块与类级别-M / -I / -i / -m / -C / -n-M/--ignore-module不要求模块顶部有 docstring-I/--ignore-init-module跳过所有__init__.py-i/--ignore-init-method不要求类的__init__写 docstring很多项目遵循类 docstring 已说明一切-m/--ignore-magic跳过__str__、__repr__等魔法方法不含__init__两者要分开配置-C/--ignore-nested-classes与-n/--ignore-nested-functions忽略定义在函数/类内部的嵌套结构。类成员级别-p / -s / -P / -S / -O-p/--ignore-private忽略__xxx开头的私有类、方法、函数不含魔法方法-s/--ignore-semiprivate忽略_xxx开头的半私有成员-P/--ignore-property-decorators忽略带propertygetter/setter/deleter 的方法-S/--ignore-setters只忽略 setter-O/--ignore-overloaded-functions忽略typing.overload装饰的重载函数这些只是类型声明无需 docstring。一次叠加多个豁免参数非常常见例如interrogate -v -i -m -M -p -s -O src正则与文档风格-r、-w、--style用正则精准忽略--ignore-regex 当命名规则无法用前缀概括时正则就是终极方案支持多次指定interrogate -v -r ^get -r .*BaseClass$ -r mock_.* src白名单模式--whitelist-regex ⭐与忽略相反-w只统计匹配正则的名称其余一律不算入分母。开启后模块级 docstring 也会被自动忽略适合只想考核某个核心子集的场景。sphinx 与 google 文档风格--style sphinx默认类与__init__各自都算作独立对象都要有 docstring 才算覆盖google类 docstring 或__init__docstring任有其一两者均视为已覆盖更贴近 Google 风格文档的惯例。注意--style google与-i/--ignore-init-method互斥同时使用会直接报错。进阶玩法徽章、配置文件与 CI 集成一键生成 docstring 覆盖率徽章 interrogate 可以生成 shields.io 风格的覆盖率徽章SVG/PNG实现在 badge_gen.pyinterrogate --generate-badge . --badge-format svg --badge-style flat src--badge-formatsvg默认或png生成 PNG 需安装pip install interrogate[png]--badge-styleflat、flat-square、flat-square-modified默认、for-the-badge、plastic、social六种风格任选徽章颜色随覆盖率变化≥95 亮绿、≥90 绿、≥75 黄绿、≥60 黄、≥40 橙、40 红只有结果发生变化时才重写徽章避免 CI 产生无谓的文件改动。用 pyproject.toml 固化参数 ⚙️与其把一长串参数写进每条命令不如沉淀到配置里interrogate 会自动发现pyproject.toml解析逻辑见 config.py[tool.interrogate] fail-under 90 exclude [setup.py, docs, build] ignore-init-method true ignore-magic true ignore-private true ignore-semiprivate true ignore-regex [^get$, ^mock_.*] style sphinx命令行参数优先级更高两者可以互相覆盖灵活组合。接入 CI/CD让文档覆盖率硬起来 写入tox.ini让文档检查成为独立测试环境[testenv:doc] deps interrogate skip_install true commands interrogate --quiet --fail-under 95 src tests也可以作为 pre-commit 钩子每次提交自动把关repos: - repo: https://gitcode.com/gh_mirrors/in/interrogate rev: 1.7.0 hooks: - id: interrogate args: [--quiet, --fail-under95] pass_filenames: false常见问题速答 Q怎么快速找出哪些函数没写 docstringA用interrogate -vv详细表中标记为MISSED的条目就是行号都给你标好了。Q如何只检查单个文件A直接传入文件路径如interrogate -v my_module.py。Q空文件也算覆盖吗A空文件算作已覆盖覆盖率为 100%配合--omit-covered-files可让 100% 覆盖的文件不再出现在报告中。Q想把报告保存下来A用-o report.txt把结果写入文件--no-color可关闭颜色方便日志与 CI 存档。总结interrogate 用 19 个精悍的参数把写没写文档这件看似主观的事变成了可量化、可强制执行的质量指标。无论是个人项目自我约束还是团队在 CI 里设置覆盖率红线它都能在几分钟内配置完毕、长期生效。现在就跑一条interrogate -v看看你的代码自证清白了没有吧【免费下载链接】interrogateExplain yourself! Interrogate a codebase for docstring coverage.项目地址: https://gitcode.com/gh_mirrors/in/interrogate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
