interrogate

1.7.0 · active · verified Sat Apr 11

interrogate checks your Python codebase for missing docstrings. It aims to make documentation as important as code itself by highlighting methods, functions, classes, and modules that lack docstrings. This tool, currently at version 1.7.0, helps developers understand docstring coverage, enforce documentation in CI/CD pipelines, and assess code quality and maintainability. It supports Python 3.8 and above, with a moderate release cadence.

Warnings

gotcha By default, `interrogate` enforces an 80% documentation coverage threshold, meaning it will exit with a non-zero status code if your project falls below this. This might unexpectedly fail CI/CD pipelines if not anticipated.
Fix: Adjust the threshold using the `--fail-under` CLI option (e.g., `interrogate --fail-under 75 .`) or configure it in `pyproject.toml` or `setup.cfg`.
gotcha Many projects omit docstrings for `__init__` methods. By default, `interrogate` includes these in its coverage calculation. This can lead to lower reported coverage than expected.
Fix: Use the `--ignore-init-method` CLI option (e.g., `interrogate --ignore-init-method .`) or configure `ignore_init_method = true` in your `pyproject.toml` or `setup.cfg` to exclude them.
gotcha Generating PNG format badges requires installing `interrogate` with the `[png]` extra (`pip install interrogate[png]`), which in turn depends on `cairosvg`. `cairosvg` often has external system dependencies like `cairo` and `libffi` that must be installed manually (e.g., via Homebrew on macOS or package managers on Linux) and can be complex on Windows.
Fix: Ensure `cairosvg` and its required system libraries are installed. Refer to `cairosvg` documentation for platform-specific installation instructions. If PNG badges are not critical, stick to the default SVG format.
gotcha `interrogate` supports configuration via `pyproject.toml` (under `[tool.interrogate]`) or `setup.cfg` (under `[interrogate]`). Users sometimes only rely on command-line flags, missing the opportunity for project-wide, version-controlled settings.
Fix: For consistent project-wide settings, configure `interrogate` in `pyproject.toml` (recommended) or `setup.cfg`. Example: `[tool.interrogate] exclude = ["setup.py", "docs"] fail-under = 90 ignore-init-method = true`

Install

pip install interrogate Basic installation
pip install interrogate[png] With PNG badge generation support

Imports

interrogate
```
interrogate [OPTIONS] [PATHS]...
```
interrogate is primarily a command-line interface tool; there is no public Python API for programmatic checking of docstring coverage. It is typically run directly from the shell or configured via `pyproject.toml` or `setup.cfg`.

Quickstart

This quickstart demonstrates how to create a simple Python module and then run `interrogate` against it from the command line, showing basic usage, verbose output, and common options like ignoring `__init__` methods and setting a custom failure threshold.

mkdir my_project
cd my_project
cat <<EOF > my_module.py
"""A module-level docstring."""

def my_function(a, b):
    # Missing docstring
    return a + b

class MyClass:
    """A class with a docstring."""
    def __init__(self):
        # Missing __init__ docstring
        pass

    def my_method(self):
        """A method with a docstring."""
        pass
EOF

# Run interrogate with default settings (fail-under 80%)
interrogate my_module.py

# Run with verbose output to see details of missing docstrings
interrogate -vv my_module.py

# Run and ignore __init__ methods, and set a custom fail-under percentage
interrogate --ignore-init-method --fail-under 100 my_module.py

view raw JSON →