Docstring Coverage

What is it?

Docstring Coverage is a simple audit tool that lets you test your python source code for coverage by docstrings. It can show you which functions, classes, methods and modules has no docstrings and also provides you statistics about overall docstring coverage for each file and your project.

Here's the sample output:

DataGreed$ docstring-coverage docstring-coverage/

File docstring-coverage/setup.py
 - No module dostring!
 Needed: 1; Exist: 0; Missing: 1; Coverage: 0.0%

File docstring-coverage/docstringcoverage/__init__.py
 - No module dostring!
 Needed: 1; Exist: 0; Missing: 1; Coverage: 0.0%

File docstring-coverage/docstringcoverage/cover.py
 - No docstring for DocStringCoverageVisitor!
 - No docstring for DocStringCoverageVisitor.__init__!
 - No docstring for DocStringCoverageVisitor.visitModule!
 - No docstring for DocStringCoverageVisitor.visitClass!
 - No docstring for DocStringCoverageVisitor.visitFunction!
 - No docstring for DocStringCoverageVisitor.getResult!
 - No docstring for get_docstring_coverage.printDocstring!
 Needed: 11; Exist: 4; Missing: 7; Coverage: 36.4%


Overall statistics for 3 files:
Docstrings needed: 13; Docstrings exist: 4; Docstrings missing: 9
Total docstring coverage: 30.8%;  Grade: not so good

How do I use it?

You can use Django Coverage as a commandline tool or you can import it in your project to use data it collects.

As a commandline tool

The general usage goes like this: docstring-coverage [options] <path to dir or module>

To test one module, named somemodule.py, run:

$ docstring-coverage somemodule.py

To test a directory some_project/src (recursively), just supply a directory:

$ docstring-coverage some_project/src

Options

--version - shows program's version number and exits
-h, --help - shows a help message and exits
-m, --nomagic - if this option is provided, skips all magic methods (like __init__ or __str__)
-v LEVEL, --verbose=LEVEL - sets verbosity level (0-3).
- 0 - does not print anything at all
- 1 - prints overall statistics
- 2 - print individual statistics for each file
- 3 - prints all missing docstrings (function names, class names, etc.)

As package in your project

You can use Docstring Coverage as a part of your project by importing the module:

import docstringcoverage
cover_results = docstringcoverage.get_docstring_coverage(['somefolder/somefile.py','somefolder/otherfile.py' ])

Arguments

get_docstring_coverage(filenames, count_magic=True, skip_empty_files = True, verbose_level=0)

Here is the breakdown of arguments that get_docstring_coverage accepts:

filenames - a list of string containing filenames with absolute or relative paths
count_magic - a boolean. If False, skips all magic methods and does not include them in the report
skip_empty_files - a bool, if True, skips all empty files, still includes them in the report, but doesn't require a module docstring for them
verbose_level - an int, possible vallues 0..3

Results

get_docstring_coverage return a list, consisting of two dicst, containing data about checked files in the following format:

[
    {'<filename>': 
        {
            'missing': ["<method_or_class_name","..."],                                    
            'module_doc': <True or False>,  #has module docstring 
            'missing_count': <missing_count>,
            'needed_count': <needed_docstrings_count>,
            'coverage': <percent_of_coverage>,     
            'empty': <True or False> #True if file is empty (no vars, funcs or classes)
        },
        ...
    },
                  
    #totals
    {
        'missing_count': <total_missing_count>,
        'needed_count': <total_needed_docstrings_count>,
        'coverage': <total_percent_of_coverage>,                                
    }               
]

Why would I use it?

Well, documenting your code is a very good habit, that will help you or someone else to maintain it easily. As a developer, you can use this tool to see which methods/classes you missed when you wrote docstrings, so you can cover them. As an auditor, you can tell exactly how much of the code is documented, which is good for obvious reasons.

Anyway, I hope you will find this project useful.

Download & installation

From sources

See downloads page for downloads (I don't usually maintain separate archives for downloads, so look for the "tags" section for stable releases).

After extracting just run setup.py install (you may need to have root privileges):

$ python setup.py install

Via Pip

You can also download & install automatically via pip like that:

$ pip install docstring-coverage

Or like that to pull the version straight from this repository:

$ pip install -e git+https://bitbucket.org/DataGreed/docstring-coverage.git#egg=docstring-coverage

Special thanks

Thanks to James Harlow for writing the original script that serves as a base for this project. I owe you a beer.

Wiki

docstring-coverage / Home