docstr-coverage 2.3.2

docstr-coverage是一个简单的工具，可以测量您的Python源代码的docstring覆盖率。它显示哪些函数、类、方法和模块没有docstrings。它还提供有关单个文件和整个项目的总体docstring覆盖率的统计信息。

• 源代码
• 文档

示例

>>> HunterMcGushion$ docstr-coverage /docstr_coverage/

File: "docstr_coverage/setup.py"
 - No module docstring
 - No docstring for `readme`
 Needed: 2; Found: 0; Missing: 2; Coverage: 0.0%

File: "docstr_coverage/docstr_coverage/__init__.py"
 - No module docstring
 Needed: 1; Found: 0; Missing: 1; Coverage: 0.0%

File: "docstr_coverage/docstr_coverage/coverage.py"
 - No docstring for `DocStringCoverageVisitor.__init__`
 Needed: 11; Found: 10; Missing: 1; Coverage: 90.9%


Overall statistics for 3 files:
Docstrings needed: 14; Docstrings found: 10; Docstrings missing: 4
Total docstring coverage: 71.4%;  Grade: Very good

如何使用它

命令行工具

通用用法是： docstr-coverage <路径到目录或模块> [选项]

要测试单个模块，名为some_module.py，请运行

docstr-coverage some_module.py

要测试一个目录（递归），只需提供目录 some_project/src 即可

docstr-coverage some_project/src

选项

• --skip-magic, -m - 忽略所有魔法方法（除 __init__ 外）
• --skip-init, -i - 忽略所有 __init__ 方法
• --skip-file-doc, -f - 忽略模块文档字符串（位于文件顶部）
• --skip-private, -P - 忽略私有函数（以单个下划线开头）
• --skip-class-def, -c - 忽略类定义的文档字符串
• --skip-property, -sp - 忽略带有 @property 装饰器的函数
• --include-setter, -is - 包括带有 @setter 装饰器的函数（默认跳过）
• --include-deleter, -idel - 包括带有 @deleter 装饰器的函数（默认跳过）
• --accept-empty, -a - 如果未找到 Python 文件，则退出代码为 0（默认：退出代码 1）
• --exclude=<regex>, -e <regex> - 排除分析中包含的文件路径模式
  • 要排除虚拟环境 env 和您的 tests 目录的内容，请运行： docstr-coverage some_project/ -e ".*/(env|tests)"
• --verbose=<level>, -v <level> - 设置详细程度级别（0-3，默认：3）
  • 0 - 无声
  • 1 - 打印总体统计信息
  • 2 - 还打印每个文件的详细统计信息
  • 3 - 还打印缺失的文档字符串（函数名称、类名称等）
  • 4 - 还打印现有文档字符串的信息
• --fail-under=<int|float>, -F <int|float> - 如果覆盖率低于一定百分比则失败（默认：100.0）
• --badge=<filepath>, -b <filepath> - 生成文档覆盖率百分比徽章作为 SVG 保存到指定的文件路径
  • 使用 [![docstr_coverage](<filepath/of/your/saved/badge.svg>)](https://github.com/HunterMcGushion/docstr_coverage) 将徽章包含在存储库的 README 中，其中 <filepath/of/your/saved/badge.svg> 是提供给 --badge 选项的路径
• --follow-links, -l - 跟踪符号链接
• --percentage-only, -p - 仅输出总体覆盖率百分比作为浮点数，静默所有其他日志
• --help, -h - 显示 CLI 选项

配置文件

所有选项都可以保存在配置文件中。自动选择执行 docstr-coverage 的文件夹中的 .docstr.yaml 文件。可以使用 docstr-coverage -C path/to/config.yml 或长版本 --config 来指定其他位置。

示例

paths: # list or string
  - docstr_coverage
badge: docs # Path
exclude: .*/test # regex
verbose: 3 # int (0-4)
skip_magic: True # Boolean
skip_file_doc: True # Boolean
skip_init: True # Boolean
skip_class_def: True # Boolean
skip_private: True # Boolean
follow_links: True # Boolean
accept_empty: True # Boolean
ignore_names_file: .*/test # regex
fail_under: 90 # int 
percentage_only: True # Boolean
ignore_patterns: # Dict with key/value pairs of file-pattern/node-pattern
  .*: method_to_ignore_in_all_files
  FileWhereWeWantToIgnoreAllSpecialMethods: "__.+__"
  SomeFile:
    - method_to_ignore1
    - method_to_ignore2
    - method_to_ignore3
  a_very_important_view_file:
    - "^get$"
    - "^set$"
    - "^post$"
  detect_.*:
    - "get_val.*"

相当于

docstr-coverage docstr_coverage -e ".*/test" --skip-magic --skip-init --badge="docs" --skip-class-def etc...

请注意，作为命令行参数传递的选项优先于配置文件中配置的选项。

正则表达式忽略

在您的配置文件中，使用 ignore_patterns，您可以指定要忽略的文件名和节点（方法、...）的 regex 模式。请参阅上面的配置文件示例。

通过注释覆盖

请注意，docstr-coverage 不能解析动态添加的文档（例如，通过类扩展）。因此，一些故意没有文档字符串的代码可能会被视为未覆盖。

您可以通过添加 # docstr-coverage:inherited（如果相应的超类方法提供了文档字符串，则用于该用途）或带有原因的通用借口，例如 # docstr-coverage:excused `My probably bad excuse` 来覆盖此情况。这些必须在任何类或函数定义（或函数注释，如果适用）的上方声明。这样的类或函数将按有文档字符串的方式计数。

# docstr-coverage:excused `no one is reading this anyways`
class FooBarChild(FooBar):

    # docstr-coverage:inherited
    def function(self):
        pass

预提交钩子

您可以使用 docstr-coverage 作为预提交钩子，通过在您的 .pre-commit-config.yaml 文件中添加以下内容，并配置 .docstr.yaml 配置的 paths 部分。这比 pre-commit args 更好，因为它便于在 CI、预提交和手动运行中使用相同的配置。

repos:
  - repo: https://github.com/HunterMcGushion/docstr_coverage
    rev: v2.3.2 # most recent docstr-coverage release or commit sha
    hooks:
      - id: docstr-coverage
        args: ["--verbose", "2"] # override the .docstr.yaml to see less output

将项目打包

您还可以将 docstr-coverage 作为项目的一部分使用，通过如下方式导入。它将为您提供总体和每个文件的覆盖率

from docstr_coverage import get_docstring_coverage
my_coverage = get_docstring_coverage(['some_dir/file_0.py', 'some_dir/file_1.py'])

如果您需要更细致的信息，请尝试使用实验性的 docstr_coverage.analyze()

from docstr_coverage import analyze
coverage_report = analyze(['some_dir/file_0.py', 'some_dir/file_1.py'])
coverage = coverage_report.count_aggregate().coverage()

为什么应该使用它

• 详尽的文档对于帮助他人（甚至你自己）理解您的代码非常重要
• 作为一名开发者，提高代码的可维护性，以便在需要更新和修复错误时
• 作为一名用户，立即了解理解一个新库的难度如何 * 如果其文档覆盖率低，您可能需要自己解决很多问题

安装

pip install docstr-coverage

如果您喜欢走在前沿，并希望获得所有最新进展，请运行

pip install git+https://github.com/HunterMcGushion/docstr_coverage.git

特别感谢

感谢Alexey "DataGreed" Strelkov和James Harlow完成了所有艰苦的工作。docstr-coverage仅仅是将他们的努力带到了Python 3。更多信息请参阅'THANKS.txt'。