Docstr-coverage

2.3.2 · active · verified Fri Apr 17

docstr-coverage is a Python utility that scans source files to ensure proper documentation. It identifies missing docstrings, provides a detailed report, and calculates an overall docstring coverage percentage. The current version is 2.3.2, and it follows an infrequent but active release cadence, typically releasing minor versions a few times a year.

Common errors

```
ModuleNotFoundError: No module named 'docstr_coverage'
```
cause The `docstr-coverage` package is not installed in the current Python environment.

fix Install the package using pip: `pip install docstr-coverage`
```
docstr-coverage: error: unrecognized arguments: --failUnder=90
```
cause Using `camelCase` configuration options or command-line arguments in `docstr-coverage` version 2.0.0 or later. Options now require `snake_case`.

fix Update your command-line arguments or configuration file (e.g., `pyproject.toml`) to use `snake_case`. Change `--failUnder` to `--fail-under`.
```
Command 'docstr-coverage' not found
```
cause The `docstr-coverage` executable is not in your system's PATH, usually because a virtual environment is not activated or pip's script directory is not included.

fix Ensure your virtual environment is activated. Alternatively, run it as a Python module: `python -m docstr_coverage your_project/`.

Warnings

breaking Configuration options (e.g., in `pyproject.toml` or `setup.cfg`) changed from `camelCase` to `snake_case`.
Fix: Update all configuration options in your project's configuration files (e.g., `pyproject.toml`) to use `snake_case`. For example, `failUnder` becomes `fail_under`.
gotcha The `docstr-coverage` CLI returns non-zero exit codes (e.g., 1 for failing `--fail-under`, 2 for argument errors). This can cause CI/CD pipelines to fail unexpectedly.
Fix: In CI/CD scripts, be aware of the exit codes. Configure your CI system to expect specific exit codes or wrap the command with `|| true` if you only want to log warnings without failing the build based on docstring coverage.
gotcha Incorrect usage of exclusion flags like `--skip` or `--exclude` can lead to either files being unexpectedly included or crucial files being ignored.
Fix: Carefully review the documentation for `--skip` (for individual docstring types) and `--exclude` (for file paths). Use glob patterns for `--exclude` paths, and test your configuration thoroughly to ensure the correct files and docstring types are being evaluated.

Install

pip install docstr-coverage Install latest version

Imports

get_docstr_coverage

from docstr_coverage import get_docstr_coverage

Quickstart

The primary usage of docstr-coverage is via the command line, but it also exposes a programmatic API. This example demonstrates how to use `get_docstr_coverage` to analyze a Python file and print the results. For CLI usage, simply run `docstr-coverage your_project/`.

import os
from docstr_coverage import get_docstr_coverage

# Create a dummy file for demonstration
with open('example_module.py', 'w') as f:
    f.write("""""""Module docstring."""\n
class MyClass:\n    """Class docstring."""\n    def __init__(self):\n        # No docstring here - this will be reported\n        pass\n\n    def my_method(self, arg):\n        """Method docstring."""\n        return arg * 2\n""")

# Run docstr-coverage programmatically
report = get_docstr_coverage(
    paths=['example_module.py'],
    skip_init=False,
    skip_magic=True,
    skip_private=False,
    skip_class_innards=False,
    verbose=2
)

print(f"\nOverall coverage: {report['overall_coverage']:.2f}%")

if report['missing_docstrings']:
    print("\nMissing docstrings found:")
    for item in report['missing_docstrings']:
        print(f"  - {item['file']}:{item['line']} ({item['name']}) -> {item['type']}")

# Clean up dummy file
os.remove('example_module.py')

view raw JSON →