interrogate

library1.7.0pypypi✓ verified 23d ago

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.

testing

pip install interrogate

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · INTERROGATE

interrogate

testingpythonv1.7.0

Install

2.6s avg

Import

—

Disk

42MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.7.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.910 runs

installs and imports cleanly · install 0.0s · import 0.000s · 43.7MB

glibc

py 3.10–3.910 runs

installs and imports cleanly · install 2.6s · import 0.000s · 45MB

42MB installed

● package 42MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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`.

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

interrogate --version

Debug

Known issues

gotchaBy 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`.

affects: All versions

gotchaMany 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.

affects: All versions

gotchaGenerating 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.

affects: All versions

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`

affects: All versions

Upgrade

Version history

1.7.0latest on PyPI · released Apr 7, 2024

Audit

Dependencies

cairosvgoptionalRequired for generating PNG badges (when `interrogate[png]` is installed).

cairooptionalSystem library often required by cairosvg for PNG generation.

libffioptionalSystem library often required by cairosvg for PNG generation, especially on macOS.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/econchick/interrogate ↗

packagehttps://pypi.org/project/interrogate/ ↗

homepagehttps://interrogate.readthedocs.io ↗

docshttps://interrogate.readthedocs.io ↗