检查代码库的docstring覆盖率。
项目描述
interrogate: 解释你自己
检查代码库的docstring覆盖率。
为什么需要这个？
interrogate 会检查你的代码库中缺失的文档字符串。
文档应该和代码本身一样重要。它应该存在于代码中。Python 标准化 文档字符串，允许开发者像调用对象的 help() 一样轻松地导航库，并使用像 Sphinx、pydoc 和 Docutils 这样强大的工具自动生成HTML、LaTeX、PDF等。
输入： interrogate。
interrogate 将会告诉你哪些方法、函数、类和模块有文档字符串，哪些没有。使用 interrogate 来
了解你的代码文档的质量；
将其添加到CI/CD检查中，以强制对新增代码进行文档化；
评估新代码库的（一个方面）代码质量和可维护性。
让我们开始吧。
需求
interrogate 支持 Python 3.8 及以上版本。
安装
interrogate 可在 PyPI 和 GitHub 上找到。推荐的安装方法是使用 pip 在 virtualenv 中安装。
$ pip install interrogate附加功能
interrogate 提供了一种生成类似 shields.io 的覆盖率徽章（作为 SVG 文件）的方式。要生成 PNG 文件，请使用额外的 [png] 安装 interrogate。
$ pip install interrogate[png]注意：生成覆盖率徽章的 PNG 文件可能需要额外的系统库/工具。
在 Windows 上，安装 Visual C++ 编译器用于 Cairo；
在 macOS 上，安装 cairo 和 libffi（例如使用 Homebrew）；
在 Linux 上，安装 cairo、python3-dev 和 libffi-dev 软件包（名称可能因发行版而异）。
有关更多信息，请参阅 cairosvg 的 文档。
用法
在 Python 项目上试用
$ interrogate [PATH]
RESULT: PASSED (minimum: 80.0%, actual: 100.0%)添加详细程度以查看摘要
$ interrogate -v [PATH]
================== Coverage for /Users/lynn/dev/interrogate/ ====================
------------------------------------ Summary ------------------------------------
| Name | Total | Miss | Cover | Cover% |
|---------------------------------------|---------|--------|---------|----------|
| src/interrogate/__init__.py | 1 | 0 | 1 | 100% |
| src/interrogate/__main__.py | 1 | 0 | 1 | 100% |
| src/interrogate/badge_gen.py | 6 | 0 | 6 | 100% |
| src/interrogate/cli.py | 2 | 0 | 2 | 100% |
| src/interrogate/config.py | 8 | 0 | 8 | 100% |
| src/interrogate/coverage.py | 27 | 0 | 27 | 100% |
| src/interrogate/utils.py | 10 | 0 | 10 | 100% |
| src/interrogate/visit.py | 18 | 0 | 18 | 100% |
| tests/functional/__init__.py | 1 | 0 | 1 | 100% |
| tests/functional/test_cli.py | 8 | 0 | 8 | 100% |
| tests/functional/test_coverage.py | 10 | 0 | 10 | 100% |
| tests/unit/__init__.py | 1 | 0 | 1 | 100% |
| tests/unit/test_badge_gen.py | 8 | 0 | 8 | 100% |
| tests/unit/test_config.py | 10 | 0 | 10 | 100% |
| tests/unit/test_utils.py | 13 | 0 | 13 | 100% |
|---------------------------------------|---------|--------|---------|----------|
| TOTAL | 124 | 0 | 124 | 100.0% |
---------------- RESULT: PASSED (minimum: 80.0%, actual: 100.0%) ----------------添加更多详细程度
$ interrogate -vv [PATH]
================== Coverage for /Users/lynn/dev/interrogate/ ====================
------------------------------- Detailed Coverage -------------------------------
| Name | Status |
|---------------------------------------------------------------------|---------|
| src/interrogate/__init__.py (module) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/__main__.py (module) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/badge_gen.py (module) | COVERED |
| save_badge (L42) | COVERED |
| get_badge (L87) | COVERED |
| should_generate_badge (L103) | COVERED |
| get_color (L160) | COVERED |
| create (L173) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/cli.py (module) | COVERED |
| main (L258) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/config.py (module) | COVERED |
| InterrogateConfig (L19) | COVERED |
| find_project_root (L61) | COVERED |
| find_project_config (L89) | COVERED |
| parse_pyproject_toml (L100) | COVERED |
| sanitize_list_values (L116) | COVERED |
| parse_setup_cfg (L139) | COVERED |
| read_config_file (L173) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/coverage.py (module) | COVERED |
| BaseInterrogateResult (L23) | COVERED |
| BaseInterrogateResult.perc_covered (L37) | COVERED |
| InterrogateFileResult (L54) | COVERED |
| InterrogateFileResult.combine (L67) | COVERED |
| InterrogateResults (L81) | COVERED |
| InterrogateResults.combine (L93) | COVERED |
| InterrogateCoverage (L101) | COVERED |
| InterrogateCoverage._add_common_exclude (L121) | COVERED |
| InterrogateCoverage._filter_files (L128) | COVERED |
| InterrogateCoverage.get_filenames_from_paths (L141) | COVERED |
| InterrogateCoverage._filter_nodes (L168) | COVERED |
| InterrogateCoverage._filter_inner_nested (L194) | COVERED |
| InterrogateCoverage._get_file_coverage (L203) | COVERED |
| InterrogateCoverage._get_coverage (L231) | COVERED |
| InterrogateCoverage.get_coverage (L248) | COVERED |
| InterrogateCoverage._get_filename (L253) | COVERED |
| InterrogateCoverage._get_detailed_row (L264) | COVERED |
| InterrogateCoverage._create_detailed_table (L281) | COVERED |
| InterrogateCoverage._create_detailed_table._sort_nodes (L288) | COVERED |
| InterrogateCoverage._print_detailed_table (L315) | COVERED |
| InterrogateCoverage._create_summary_table (L338) | COVERED |
| InterrogateCoverage._print_summary_table (L381) | COVERED |
| InterrogateCoverage._sort_results (L399) | COVERED |
| InterrogateCoverage._get_header_base (L429) | COVERED |
| InterrogateCoverage._print_omitted_file_count (L438) | COVERED |
| InterrogateCoverage.print_results (L469) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/utils.py (module) | COVERED |
| parse_regex (L21) | COVERED |
| smart_open (L40) | COVERED |
| get_common_base (L60) | COVERED |
| OutputFormatter (L80) | COVERED |
| OutputFormatter.should_markup (L90) | COVERED |
| OutputFormatter.set_detailed_markup (L105) | COVERED |
| OutputFormatter.set_summary_markup (L129) | COVERED |
| OutputFormatter._interrogate_line_formatter (L158) | COVERED |
| OutputFormatter.get_table_formatter (L226) | COVERED |
|---------------------------------------------------------------------|---------|
| src/interrogate/visit.py (module) | COVERED |
| CovNode (L15) | COVERED |
| CoverageVisitor (L44) | COVERED |
| CoverageVisitor._has_doc (L58) | COVERED |
| CoverageVisitor._visit_helper (L65) | COVERED |
| CoverageVisitor._is_nested_func (L112) | COVERED |
| CoverageVisitor._is_nested_cls (L121) | COVERED |
| CoverageVisitor._is_private (L133) | COVERED |
| CoverageVisitor._is_semiprivate (L141) | COVERED |
| CoverageVisitor._is_ignored_common (L151) | COVERED |
| CoverageVisitor._has_property_decorators (L168) | COVERED |
| CoverageVisitor._has_setters (L182) | COVERED |
| CoverageVisitor._is_func_ignored (L193) | COVERED |
| CoverageVisitor._is_class_ignored (L217) | COVERED |
| CoverageVisitor.visit_Module (L221) | COVERED |
| CoverageVisitor.visit_ClassDef (L228) | COVERED |
| CoverageVisitor.visit_FunctionDef (L237) | COVERED |
| CoverageVisitor.visit_AsyncFunctionDef (L246) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/functional/__init__.py (module) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/functional/test_cli.py (module) | COVERED |
| runner (L22) | COVERED |
| test_run_no_paths (L30) | COVERED |
| test_run_shortflags (L77) | COVERED |
| test_run_longflags (L106) | COVERED |
| test_run_multiple_flags (L124) | COVERED |
| test_generate_badge (L135) | COVERED |
| test_incompatible_options (L170) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/functional/test_coverage.py (module) | COVERED |
| test_coverage_simple (L60) | COVERED |
| test_coverage_errors (L73) | COVERED |
| test_print_results (L101) | COVERED |
| test_print_results_omit_covered (L130) | COVERED |
| test_print_results_omit_none (L156) | COVERED |
| test_print_results_omit_all_summary (L174) | COVERED |
| test_print_results_omit_all_detailed (L198) | COVERED |
| test_print_results_ignore_module (L226) | COVERED |
| test_print_results_single_file (L253) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/unit/__init__.py (module) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/unit/test_badge_gen.py (module) | COVERED |
| test_save_badge (L26) | COVERED |
| test_save_badge_windows (L50) | COVERED |
| test_save_badge_no_cairo (L62) | COVERED |
| test_get_badge (L73) | COVERED |
| test_should_generate (L96) | COVERED |
| test_get_color (L115) | COVERED |
| test_create (L136) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/unit/test_config.py (module) | COVERED |
| test_find_project_root (L29) | COVERED |
| test_find_project_config (L48) | COVERED |
| test_parse_pyproject_toml (L57) | COVERED |
| test_sanitize_list_values (L93) | COVERED |
| test_parse_setup_cfg (L98) | COVERED |
| test_parse_setup_cfg_raises (L123) | COVERED |
| test_read_config_file_none (L134) | COVERED |
| test_read_config_file (L193) | COVERED |
| test_read_config_file_raises (L207) | COVERED |
|---------------------------------------------------------------------|---------|
| tests/unit/test_utils.py (module) | COVERED |
| test_parse_regex (L32) | COVERED |
| test_smart_open (L39) | COVERED |
| test_get_common_base (L69) | COVERED |
| test_get_common_base_windows (L100) | COVERED |
| test_output_formatter_should_markup (L132) | COVERED |
| test_output_formatter_set_detailed_markup (L163) | COVERED |
| test_output_formatter_set_summary_markup (L206) | COVERED |
| test_output_formatter_interrogate_line_formatter (L258) | COVERED |
| test_output_formatter_interrogate_line_formatter_windows (L319) | COVERED |
| test_output_formatter_get_table_formatter (L343) | COVERED |
| test_output_formatter_get_table_formatter_py38 (L381) | COVERED |
| test_output_formatter_get_table_formatter_raises (L395) | COVERED |
|---------------------------------------------------------------------|---------|
------------------------------------ Summary ------------------------------------
| Name | Total | Miss | Cover | Cover% |
|---------------------------------------|---------|--------|---------|----------|
| src/interrogate/__init__.py | 1 | 0 | 1 | 100% |
| src/interrogate/__main__.py | 1 | 0 | 1 | 100% |
| src/interrogate/badge_gen.py | 6 | 0 | 6 | 100% |
| src/interrogate/cli.py | 2 | 0 | 2 | 100% |
| src/interrogate/config.py | 8 | 0 | 8 | 100% |
| src/interrogate/coverage.py | 27 | 0 | 27 | 100% |
| src/interrogate/utils.py | 10 | 0 | 10 | 100% |
| src/interrogate/visit.py | 18 | 0 | 18 | 100% |
| tests/functional/__init__.py | 1 | 0 | 1 | 100% |
| tests/functional/test_cli.py | 8 | 0 | 8 | 100% |
| tests/functional/test_coverage.py | 10 | 0 | 10 | 100% |
| tests/unit/__init__.py | 1 | 0 | 1 | 100% |
| tests/unit/test_badge_gen.py | 8 | 0 | 8 | 100% |
| tests/unit/test_config.py | 10 | 0 | 10 | 100% |
| tests/unit/test_utils.py | 13 | 0 | 13 | 100% |
|---------------------------------------|---------|--------|---------|----------|
| TOTAL | 124 | 0 | 124 | 100.0% |
---------------- RESULT: PASSED (minimum: 80.0%, actual: 100.0%) ----------------其他用法
生成 shields.io 徽章（如这个！
$ interrogate --generate-badge PATH
RESULT: PASSED (minimum: 80.0%, actual: 100.0%)
Generated badge to /Users/lynn/dev/interrogate/docs/_static/interrogate_badge.svg有关更多徽章配置，请参见下面。
将其添加到您的 tox.ini 文件中，以强制执行覆盖率级别
[testenv:doc]
deps = interrogate
skip_install = true
commands =
interrogate --quiet --fail-under 95 src tests或与 pre-commit 一起使用
repos:
- repo: https://github.com/econchick/interrogate
rev: 1.7.0 # or master if you're bold
hooks:
- id: interrogate
args: [--quiet, --fail-under=95]
pass_filenames: false # needed if excluding files with pyproject.toml or setup.cfg直接在代码中使用它
>>> from interrogate import coverage
>>> cov = coverage.InterrogateCoverage(paths=["src"])
>>> results = cov.get_coverage()
>>> results
InterrogateResults(total=68, covered=65, missing=3)使用 GitHub Actions 与 interrogate 一起使用。查看由 Jack McKew 编写和维护的 action（感谢，Jack！）。
或者在 VSCode 中使用 interrogate 扩展，由 Kenneth Love 编写和维护（感谢，Kenneth！）。
配置
在您的 pyproject.toml 中进行配置（interrogate 将自动检测 pyproject.toml 文件，并为命令行选项选择默认值）
$ interrogate -c pyproject.toml [OPTIONS] [PATHS]...[tool.interrogate]
ignore-init-method = true
ignore-init-module = false
ignore-magic = false
ignore-semiprivate = false
ignore-private = false
ignore-property-decorators = false
ignore-module = false
ignore-nested-functions = false
ignore-nested-classes = true
ignore-setters = false
ignore-overloaded-functions = false
fail-under = 95
exclude = ["setup.py", "docs", "build"]
ignore-regex = ["^get$", "^mock_.*", ".*BaseClass.*"]
ext = []
# possible values: sphinx (default), google
style = sphinx
# possible values: 0 (minimal output), 1 (-v), 2 (-vv)
verbose = 0
quiet = false
whitelist-regex = []
color = true
omit-covered-files = false
generate-badge = "."
badge-format = "svg"或在 setup.cfg 中进行配置（interrogate 将自动检测 setup.cfg 文件，并为命令行选项选择默认值）
$ interrogate -c setup.cfg [OPTIONS] [PATHS]...[tool:interrogate]
ignore-init-method = true
ignore-init-module = false
ignore-magic = false
ignore-semiprivate = false
ignore-private = false
ignore-property-decorators = false
ignore-module = false
ignore-nested-functions = false
ignore-nested-classes = true
ignore-setters = false
ignore-overloaded-functions = false
fail-under = 95
exclude = setup.py,docs,build
ignore-regex = ^get$,^mock_.*,.*BaseClass.*
ext = []
; possible values: sphinx (default), google
style = sphinx
; possible values: 0 (minimal output), 1 (-v), 2 (-vv)
verbose = 0
quiet = false
whitelist-regex =
color = true
omit-covered-files = false
generate-badge = .
badge-format = svg徽章选项
徽章格式
默认文件格式为 svg。使用 --badge-format 标志可以创建 png 文件。 注意：要生成 png 文件，必须使用 interrogate[png] 安装 interrogate（见 上方）。
$ interrogate --generate-badge PATH --badge-format png
RESULT: PASSED (minimum: 80.0%, actual: 100.0%)
Generated badge to /Users/lynn/dev/interrogate/docs/_static/interrogate_badge.png徽章样式
以下徽章样式可通过 --badge-style 标志使用
选项 |
示例 |
|---|---|
平面 |
|
平面方形 |
|
平面方形修改版（默认） |
|
徽章样式 |
|
塑料 |
|
社交 |
命令行选项
要查看所有可用选项，请运行 interrogate --help
interrogate -h
Usage: interrogate [OPTIONS] [PATHS]...
Measure and report on documentation coverage in Python modules.
Options:
--version Show the version and exit.
-v, --verbose Level of verbosity.
NOTE: When configuring verbosity in
pyproject.toml or setup.cfg, `verbose=1`
maps to `-v`, and `verbose=2` maps to `-vv`.
`verbose=0` is the equivalent of no verbose
flags used, producing minimal output.
-q, --quiet Do not print output [default: False]
-f, --fail-under INT | FLOAT Fail when coverage % is less than a given
amount. [default: 80.0]
-e, --exclude PATH Exclude PATHs of files and/or directories.
Multiple `-e/--exclude` invocations
supported.
-i, --ignore-init-method Ignore `__init__` method of classes.
[default: False]
-I, --ignore-init-module Ignore `__init__.py` modules. [default:
False]
-m, --ignore-magic Ignore all magic methods of classes.
[default: False]
NOTE: This does not include the `__init__`
method. To ignore `__init__` methods, use
`--ignore-init-method`.
-M, --ignore-module Ignore module-level docstrings. [default:
False]
-n, --ignore-nested-functions Ignore nested functions and methods.
[default: False]
-C, --ignore-nested-classes Ignore nested classes. [default: False]
-O, --ignore-overloaded-functions
Ignore `@typing.overload`-decorated functions.
[default: False]
-p, --ignore-private Ignore private classes, methods, and
functions starting with two underscores.
[default: False]
NOTE: This does not include magic methods;
use `--ignore-magic` and/or `--ignore-init-
method` instead.
-P, --ignore-property-decorators
Ignore methods with property setter/getter/deleter
decorators. [default: False]
-S, --ignore-setters Ignore methods with property setter
decorators. [default: False]
-s, --ignore-semiprivate Ignore semiprivate classes, methods, and
functions starting with a single underscore.
[default: False]
-r, --ignore-regex STR Regex identifying class, method, and
function names to ignore. Multiple
`-r/--ignore-regex` invocations supported.
--ext Include Python-like files with the given
extension (supported: ``pyi``). Multiple
`--ext` invocations supported.
-w, --whitelist-regex STR Regex identifying class, method, and
function names to include. Multiple
`-w/--whitelist-regex` invocations
supported.
--style [sphinx|google] Style of docstrings to honor. Using `google`
will consider a class and its `__init__`
method both covered if there is either a
class-level docstring, or an `__init__`
method docstring, instead of enforcing both.
Mutually exclusive with `-i`/`--ignore-init`
flag. [default: sphinx]
-o, --output FILE Write output to a given FILE. [default:
stdout]
--color / --no-color Toggle color output on/off when printing to
stdout. [default: True]
--omit-covered-files Omit reporting files that have 100%
documentation coverage. This option is
ignored if verbosity is not set. [default:
False]
-g, --generate-badge PATH Generate a 'shields.io' status badge (an SVG
image) in at a given file or directory. Will
not generate a badge if results did not
change from an existing badge of the same
path.
--badge-format [svg|png] File format for the generated badge. Used
with the `-g/--generate-badge` flag.
[default: svg]
NOTE: To generate a PNG file, interrogate
must be installed with `interrogate[png]`,
i.e. `pip install interrogate[png]`.
--badge-style [flat|flat-square|flat-square-modified|for-the-badge|plastic|social]
Desired style of shields.io badge. Used with
the `-g/--generate-badge` flag. [default:
flat-square-modified]
-h, --help Show this message and exit.
-c, --config FILE Read configuration from `pyproject.toml` or
`setup.cfg`.Interrogate 用户
野外的 Interrogate
鸣谢
interrogate 受 docstr-coverage 的启发，该库是从 Alexey “DataGreed” Strelkov 的 docstring-coverage 分支出来的，后者受到 2004 年 James Harlow 的配方 的启发（海龟…）。
可爱的 
发布信息
1.7.0 (2024-04-07)
新增
修复
在忽略属性装饰器时包括对删除器的支持（#126 <https://github.com/econchick/interrogate/issues/126>）。
支持 –fail-under 值的浮点数（#114）。
移除
所有 Python 版本的 toml 依赖项（#150）。
下载文件
下载适用于您平台的文件。如果您不确定选择哪一个，请了解有关安装包的更多信息。
源分布
interrogate-1.7.0.tar.gz (159.6 kB 查看哈希值)
构建分布
interrogate-1.7.0-py3-none-any.whl (47.0 kB 查看哈希值)