Python文档字符串覆盖率

注意：这完全是他人的工作。我做了些修改（徽章生成、pre-commit钩子等），并希望它可以通过pip安装。- @danielsuo。

如果你的文档健康状况危急，docstr-coverage将立刻帮助你。

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

• 来源： https://github.com/HunterMcGushion/docstr_coverage
• 文档： https://docstr-coverage.readthedocs.io

示例

>>> 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

选项

• --skipmagic, -m - 忽略所有魔术方法（如__init__和__str__）

• --skipfiledoc, -f - 忽略模块文档字符串（位于文件顶部）

• --exclude=<regex>, -e <regex> - 从分析中排除的文件路径模式

  • 要排除虚拟环境 env 和你的 tests 目录的内容，请运行
    $ docstr-coverage some_project/ -e "env/*|tests/*"

• --verbose=<level>, -v <level> - 设置详细级别（0-3）

  • 0 - 静音
  • 1 - 打印总体统计数据
  • 2 - 也打印每个文件的单独统计数据
  • 3 - 也打印缺失的文档字符串（函数名、类名等）

• --docstr-ignore-file=, -d - 包含要忽略的模式列表的文件路径。模式是（文件模式，名称模式）对

  • 文件内容示例

  SomeFile method_to_ignore1 method_to_ignore2 method_to_ignore3
  FileWhereWeWantToIgnoreAllSpecialMethods __.+__
  .* method_to_ignore_in_all_files
  a_very_important_view_file ^get$ ^set$ ^post$
  detect_.* get_val.*
  

项目中的包

您还可以通过以下方式将 docstr-coverage 作为项目的一部分使用

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

参数

• 必需参数：filenames <字符串文件名列表>
• 可选关键字参数：skip_magic <布尔值>，skip_file_docstring <布尔值>，verbose <整数（0-3）>
  • 有关 get_docstring_coverage 及其参数的更多信息，请参阅其 文档

结果

get_docstring_coverage 返回两个字典：1）每个文件的统计数据，2）总体统计数据。有关更多信息，请参阅 get_docstring_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'。