{"id":4056,"library":"interrogate","title":"interrogate","description":"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.","status":"active","version":"1.7.0","language":"en","source_language":"en","source_url":"https://github.com/econchick/interrogate","tags":["docstring","coverage","linting","quality","documentation","ci-cd"],"install":[{"cmd":"pip install interrogate","lang":"bash","label":"Basic installation"},{"cmd":"pip install interrogate[png]","lang":"bash","label":"With PNG badge generation support"}],"dependencies":[{"reason":"Required for generating PNG badges (when `interrogate[png]` is installed).","package":"cairosvg","optional":true},{"reason":"System library often required by cairosvg for PNG generation.","package":"cairo","optional":true},{"reason":"System library often required by cairosvg for PNG generation, especially on macOS.","package":"libffi","optional":true}],"imports":[{"note":"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`.","symbol":"interrogate","correct":"interrogate [OPTIONS] [PATHS]..."}],"quickstart":{"code":"mkdir my_project\ncd my_project\ncat <<EOF > my_module.py\n\"\"\"A module-level docstring.\"\"\"\n\ndef my_function(a, b):\n    # Missing docstring\n    return a + b\n\nclass MyClass:\n    \"\"\"A class with a docstring.\"\"\"\n    def __init__(self):\n        # Missing __init__ docstring\n        pass\n\n    def my_method(self):\n        \"\"\"A method with a docstring.\"\"\"\n        pass\nEOF\n\n# Run interrogate with default settings (fail-under 80%)\ninterrogate my_module.py\n\n# Run with verbose output to see details of missing docstrings\ninterrogate -vv my_module.py\n\n# Run and ignore __init__ methods, and set a custom fail-under percentage\ninterrogate --ignore-init-method --fail-under 100 my_module.py\n","lang":"bash","description":"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."},"warnings":[{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For consistent project-wide settings, configure `interrogate` in `pyproject.toml` (recommended) or `setup.cfg`. Example: `[tool.interrogate]\nexclude = [\"setup.py\", \"docs\"]\nfail-under = 90\nignore-init-method = true`","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}