or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

ast-visitor.mdbadge-generation.mdcli-interface.mdconfiguration.mdcoverage-analysis.mdindex.mdutilities.md
tile.json

tessl/pypi-interrogate

Interrogate a codebase for docstring coverage.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/interrogate@1.7.x

To install, run

npx @tessl/cli install tessl/pypi-interrogate@1.7.0

index.mddocs/

Interrogate

A Python command-line tool and library for analyzing docstring coverage in Python codebases. Interrogate examines Python modules, classes, functions, and methods to identify missing docstrings and generate detailed coverage reports, helping developers maintain code documentation standards.

Package Information

  • Package Name: interrogate
  • Language: Python
  • Installation: pip install interrogate

Optional PNG badge support:

pip install interrogate[png]

Core Imports

import interrogate

For programmatic usage:

from interrogate.coverage import InterrogateCoverage
from interrogate.config import InterrogateConfig

For CLI usage:

from interrogate.cli import main

Basic Usage

Command Line Usage

# Analyze current directory
interrogate .

# Analyze specific files/directories
interrogate src/ tests/

# Generate coverage report with badge
interrogate --generate-badge badge.svg src/

# Fail if coverage below threshold
interrogate --fail-under 80 src/

Programmatic Usage

from interrogate.coverage import InterrogateCoverage
from interrogate.config import InterrogateConfig

# Create configuration
config = InterrogateConfig(
    ignore_module=True,
    fail_under=80,
)

# Run coverage analysis
coverage = InterrogateCoverage(["src/"], config)
results = coverage.get_coverage()

# Print results
coverage.print_results(results)

Architecture

Interrogate is built around several key components:

  • Coverage Analysis: Core engine that traverses Python AST to identify docstring coverage
  • Configuration Management: Handles CLI options, config files (pyproject.toml, setup.cfg)
  • Results Processing: Aggregates and formats coverage statistics
  • Badge Generation: Creates SVG/PNG badges for documentation coverage visualization
  • CLI Interface: Command-line interface built with Click framework

The analysis process uses Python's AST (Abstract Syntax Tree) to examine code structure and identify missing docstrings across modules, classes, functions, and methods.

Capabilities

Coverage Analysis

Core functionality for analyzing docstring coverage in Python codebases. Examines AST to identify missing docstrings and generate comprehensive coverage statistics.

class InterrogateCoverage:
    def __init__(self, paths, conf=None, excluded=None, extensions=None): ...
    def get_coverage(self): ...
    def print_results(self, results, output, verbosity): ...

class InterrogateResults:
    total: int
    covered: int 
    missing: int
    perc_covered: float
    ret_code: int
    file_results: Dict[str, InterrogateFileResult]

Coverage Analysis

Configuration Management

Handles configuration from multiple sources including CLI arguments, pyproject.toml, and setup.cfg files. Provides unified configuration interface with validation and defaults.

class InterrogateConfig:
    def __init__(self, **kwargs): ...

def find_project_config(path_search_start): ...
def parse_pyproject_toml(path_config): ...
def parse_setup_cfg(path_config): ...

Configuration

Badge Generation

Creates SVG and PNG badges displaying docstring coverage percentages. Supports multiple badge styles and automatic color coding based on coverage thresholds.

def create(
    output,
    result,
    output_format=None,
    output_style=None
): ...

def get_badge(
    result,
    color,
    style=None
): ...

Badge Generation

Command Line Interface

Full-featured CLI built with Click framework supporting extensive configuration options, multiple output formats, and integration with CI/CD pipelines.

def main(ctx, paths, **kwargs): ...

CLI Interface

Utilities

Helper functions and formatting utilities for file handling, path manipulation, and terminal output formatting.

def parse_regex(ctx, param, values): ...
def smart_open(filename=None, fmode=None): ...
def get_common_base(files): ...

class OutputFormatter:
    def __init__(self, config, file=None): ...
    def should_markup(self): ...
    def set_detailed_markup(self, padded_cells): ...
    def set_summary_markup(self, padded_cells): ...
    def get_table_formatter(self, table_type): ...

Utilities

AST Visitor

AST traversal and node analysis for collecting docstring coverage information from Python source code.

class CovNode:
    name: str
    path: str
    level: int
    lineno: int
    covered: bool
    node_type: str
    is_nested_func: bool
    is_nested_cls: bool
    parent: object

class CoverageVisitor:
    def __init__(self, filename, config): ...
    def visit_Module(self, node): ...
    def visit_ClassDef(self, node): ...
    def visit_FunctionDef(self, node): ...
    def visit_AsyncFunctionDef(self, node): ...

AST Visitor

Package Constants

__author__ = "Lynn Root"
__version__ = "1.7.0"
__email__ = "lynn@lynnroot.com"
__description__ = "Interrogate a codebase for docstring coverage."
__uri__ = "https://interrogate.readthedocs.io"

Types

class BaseInterrogateResult:
    total: int
    covered: int
    missing: int
    perc_covered: float

class InterrogateFileResult(BaseInterrogateResult):
    filename: str
    ignore_module: bool
    nodes: list
    
    def combine(self): ...

class InterrogateResults(BaseInterrogateResult):
    ret_code: int
    file_results: dict
    
    def combine(self): ...

class CovNode:
    name: str
    path: str
    level: int
    lineno: int
    covered: bool
    node_type: str
    is_nested_func: bool
    is_nested_cls: bool
    parent: object

class InterrogateConfig:
    color: bool = False
    docstring_style: str = "sphinx"
    fail_under: float = 80.0
    ignore_regex: bool = False
    ignore_magic: bool = False
    ignore_module: bool = False
    ignore_private: bool = False
    ignore_semiprivate: bool = False
    ignore_init_method: bool = False
    ignore_init_module: bool = False
    ignore_nested_classes: bool = False
    ignore_nested_functions: bool = False
    ignore_property_setters: bool = False
    ignore_property_decorators: bool = False
    ignore_overloaded_functions: bool = False
    include_regex: bool = False
    omit_covered_files: bool = False