Package: docstr-coverage
docstr-coverageis a simple tool that lets you measure your Python source code'sdocstringcoverage.
It shows which of your functions, classes, methods, and modules don't have docstrings.
It also provide statistics about overall docstring coverage for individual files, and for your entire project.SourceDocumentationExample>>>HunterMcGushion$docstr-coverage/docstr_coverage/

File:"docstr_coverage/setup.py"-Nomoduledocstring-Nodocstringfor`readme`Needed:2;Found:0;Missing:2;Coverage:0.0%

File:"docstr_coverage/docstr_coverage/__init__.py"-NomoduledocstringNeeded:1;Found:0;Missing:1;Coverage:0.0%

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


Overallstatisticsfor3files:
Docstringsneeded:14;Docstringsfound:10;Docstringsmissing:4Totaldocstringcoverage:71.4%;Grade:VerygoodHow Do I Use ItCommand-line ToolGeneral usage is:docstr-coverage <path to dir or module> [options]To test a single module, namedsome_module.py, run:docstr-coveragesome_module.pyTo test a directory (recursively), just supply the directorysome_project/srcinstead:docstr-coveragesome_project/srcOptions--skip-magic, -m- Ignore all magic methods (except__init__)--skip-init, -i- Ignore all__init__methods--skip-file-doc, -f- Ignore module docstrings (at the top of files)--skip-private, -P- Ignore private functions (starting with a single underscore)--skip-class-def, -c- Ignore docstrings of class definitions--skip-property, -sp- Ignore functions with@propertydecorator--include-setter, -is- Include functions with@setterdecorator (skipped by default)--include-deleter, -idel- Include functions with@deleterdecorator (skipped by default)--accept-empty, -a- Exit with code 0 if no Python files are found (default: exit code 1)--exclude=<regex>, -e <regex>- Filepath pattern to exclude from analysisTo exclude the contents of a virtual environmentenvand yourtestsdirectory, run:docstr-coverage some_project/ -e ".*/(env|tests)"--verbose=<level>, -v <level>- Set verbosity level (0-3, default: 3)0 - Silence1 - Print overall statistics2 - Also print individual statistics for each file3 - Also print missing docstrings (function names, class names, etc.)4 - Also print information about present docstrings--fail-under=<int|float>, -F <int|float>- Fail if under a certain percentage of coverage (default: 100.0)--badge=<filepath>, -b <filepath>- Generate a docstring coverage percent badge as an SVG saved to a given filepathInclude the badge in a repo's README using[![docstr_coverage](<filepath/of/your/saved/badge.svg>)](https://github.com/HunterMcGushion/docstr_coverage),
where<filepath/of/your/saved/badge.svg>is the path provided to the--badgeoption--follow-links, -l- Follow symlinks--percentage-only, -p- Output only the overall coverage percentage as a float, silencing all other logging--help, -h- Display CLI optionsConfig FileAll options can be saved in a config file. A file named.docstr.yamlin the folder in whichdocstr-coverageis executed is picked up automatically.
Other locations can be passed usingdocstr-coverage -C path/to/config.ymlor the long version--config.Example:paths:# list or string-docstr_coveragebadge:docs# Pathexclude:.*/test# regexverbose:3# int (0-4)skip_magic:True# Booleanskip_file_doc:True# Booleanskip_init:True# Booleanskip_class_def:True# Booleanskip_private:True# Booleanfollow_links:True# Booleanaccept_empty:True# Booleanignore_names_file:.*/test# regexfail_under:90# intpercentage_only:True# Booleanignore_patterns:# Dict with key/value pairs of file-pattern/node-pattern.*:method_to_ignore_in_all_filesFileWhereWeWantToIgnoreAllSpecialMethods:"__.+__"SomeFile:-method_to_ignore1-method_to_ignore2-method_to_ignore3a_very_important_view_file:-"^get$"-"^set$"-"^post$"detect_.*:-"get_val.*"equivalent todocstr-coverage docstr_coverage -e ".*/test" --skip-magic --skip-init --badge="docs" --skip-class-def etc...Note that options passed as command line arguments have precedence over options
configured in a config file.Ignoring by RegexIn your config files, usingignore_patterns, you can specify regex patterns for files names and nodes (methods, ...)
which should be ignored. See config file example above.Overriding by CommentsNote thatdocstr-coveragecan not parse
dynamically added documentation (e.g. through class extension).
Thus, some of your code which deliberately has no docstring might be counted as uncovered.You can override this by adding either# docstr-coverage:inherited(intended for use if a docstring is provided in the corresponding superclass method)
or a generic excuse with a reason, like# docstr-coverage:excused `My probably bad excuse`.
These have to be stated right above any class or function definition
(or above the functions annotations, if applicable).
Such class or function would then be counted as if they had a docstring.# docstr-coverage:excused `no one is reading this anyways`classFooBarChild(FooBar):# docstr-coverage:inheriteddeffunction(self):passPre-commit hookYou can usedocstr-coverageas a pre-commit hook by adding the following to your.pre-commit-config.yamlfile
and configuring thepathssection of the.docstr.yamlconfig.
This is preferrable overpre-commit args,
as it facilitates the use of the same config in CI, pre-commit and manual runs.repos:-repo:https://github.com/HunterMcGushion/docstr_coveragerev:v2.3.1# most recent docstr-coverage release or commit shahooks:-id:docstr-coverageargs:["--verbose","2"]# override the .docstr.yaml to see less outputPackage in Your ProjectYou can also usedocstr-coverageas a part of your project by importing it thusly.
It will supply you with overall and per-file coverages:fromdocstr_coverageimportget_docstring_coveragemy_coverage=get_docstring_coverage(['some_dir/file_0.py','some_dir/file_1.py'])If you want more fine grained information, try the experimentaldocstr_coverage.analyze()fromdocstr_coverageimportanalyzecoverage_report=analyze(['some_dir/file_0.py','some_dir/file_1.py'])coverage=coverage_report.count_aggregate().coverage()Why Should I Use ItThorough documentation is important to help others (and even yourself) understand your codeAs a developer, improve your code's maintainability for when you need to make updates and fix bugsAs a user, instantly know how easy it's going to be to understand a new library * If its documentation coverage is low, you may need to figure a lot out for yourselfInstallationpipinstalldocstr-coverageIf you like being on the cutting-edge, and you want all the latest developments, run:pipinstallgit+https://github.com/HunterMcGushion/docstr_coverage.gitSpecial ThanksThank you to Alexey "DataGreed" Strelkov, and James Harlow for doing all the hard work.docstr-coveragesimply revives and brings their efforts to Python 3. See 'THANKS.txt' for more information.