docstr-coverage

What it is and what it does

docstr-coverage is a command-line tool and Python library that scans your source code to identify which functions, classes, methods, and modules lack docstrings. It walks your project recursively, counts what's documented and what's missing, and reports both per-file and aggregate coverage percentages with a letter grade. You run it as a CLI tool pointing at a file or directory, configure it via YAML, or import its API into your own code to get structured coverage data.

The tool is designed to help enforce documentation standards in teams and projects. It supports fine-grained filtering—you can skip magic methods, private functions, properties, or entire file patterns via regex—and lets you override its analysis with inline comments for inherited or deliberately undocumented code. It integrates into pre-commit hooks, can generate SVG badges for README files, and supports both strict pass/fail thresholds and silent percentage-only output for CI pipelines.

Use it for:

• Audit a new library or codebase to understand how well-documented it is before deciding to use or maintain it.
• Enforce minimum documentation standards in CI/CD by failing builds when docstring coverage drops below a threshold.
• Generate a coverage badge to display in a project's README as a visual indicator of documentation quality.
• Integrate into pre-commit hooks to catch undocumented functions and classes before they reach version control.
• Measure documentation debt over time by running the tool on releases and tracking coverage trends.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Measures docstring coverage in Python source code by scanning for missing docstrings in functions, classes, methods, and modules, then reports statistics and identifies gaps.

Yes, if you need to audit or enforce docstring coverage in Python projects. The tool is straightforward, has no security vulnerabilities, and low install friction. However, maintenance is dormant (last release May 2024, no commits for 829 days), so verify compatibility with your Python version before relying on it for critical CI workflows. For one-off audits or pre-commit integration in stable codebases, it's a solid choice.

Install

docstr-coverage on PyPI

pip install docstr-coverage

uv add docstr-coverage

poetry add docstr-coverage

Installing docstr-coverage

Before you install

Low install friction with four lightweight runtime dependencies (click, PyYAML, tqdm, importlib-resources). Maintenance is dormant—last release was 2024-05-07 and no commits for 829 days—but the repository remains active and unarchived.

License in practice

MIT license permits commercial and private use with minimal restrictions; you must include a copy of the license and retain copyright notices.

Quickstart

pip install docstr-coverage

# Command-line usage:
docstr-coverage /path/to/project

# Or as a library:
from docstr_coverage import get_docstring_coverage
coverage = get_docstring_coverage(['file.py'])

Verify before relying

• Whether dormant maintenance (829 days since last release) affects compatibility with recent Python versions beyond 3.12
• Performance characteristics on large codebases or deeply nested directory structures

Package facts

Evidence: docstr_coverage-2.3.2-py3-none-any.whl

Keywords: docstring, coverage, documentation, audit, source, code, statistics, report

Tags

More Software Development packages