tessl/pypi-interrogate

Interrogate a codebase for docstring coverage.

—

Pending

Overview

Eval results

Files

CLI Interface

Name: tessl/pypi-interrogate
Author: tessl

Full-featured command-line interface built with Click framework supporting extensive configuration options, multiple output formats, and integration with CI/CD pipelines. The CLI provides the primary way to use interrogate for analyzing docstring coverage.

Capabilities

Main CLI Function

Primary command-line entry point that handles argument parsing and execution.

def main(
    ctx: click.Context,
    paths: Tuple[str, ...],
    color: bool = True,
    exclude: Tuple[str, ...] = (),
    ignore_init_method: bool = False,
    ignore_init_module: bool = False,
    ignore_magic: bool = False,
    ignore_module: bool = False,
    ignore_nested_classes: bool = False,
    ignore_nested_functions: bool = False,
    ignore_private: bool = False,
    ignore_property_decorators: bool = False,
    ignore_regex: Tuple[str, ...] = (),
    ignore_semiprivate: bool = False,
    fail_under: Optional[float] = None,
    docstring_style: str = "sphinx",
    output: Optional[str] = None,
    quiet: int = 0,
    verbose: int = 0,
    omit_covered_files: bool = False,
    generate_badge: Optional[str] = None,
    badge_format: str = "svg",
    badge_style: str = "flat",
    config: Optional[str] = None
) -> None:
    """
    Main CLI command for interrogate.
    
    Args:
        ctx: Click context object
        paths: Paths to analyze for docstring coverage
        color: Use color output
        exclude: Patterns of paths to exclude
        ignore_init_method: Ignore __init__ method docstrings
        ignore_init_module: Ignore __init__.py module docstrings  
        ignore_magic: Ignore magic method docstrings
        ignore_module: Ignore module-level docstrings
        ignore_nested_classes: Ignore nested class docstrings
        ignore_nested_functions: Ignore nested function docstrings
        ignore_private: Ignore private method docstrings
        ignore_property_decorators: Ignore property decorator docstrings
        ignore_regex: Regular expressions for names to ignore
        ignore_semiprivate: Ignore semiprivate method docstrings
        fail_under: Fail if coverage percentage is below this threshold
        docstring_style: Docstring style to check
        output: Output file path
        quiet: Quiet level (0-2)
        verbose: Verbose level (0-2)
        omit_covered_files: Don't show files with 100% coverage
        generate_badge: Path to generate coverage badge
        badge_format: Badge format (svg/png)
        badge_style: Badge style
        config: Configuration file path
    """

Command Line Options

Analysis Options

Options controlling what code elements to analyze and ignore.

# Ignore specific types of code elements
interrogate --ignore-init-method src/           # Ignore __init__ methods
interrogate --ignore-init-module src/           # Ignore __init__.py modules
interrogate --ignore-magic src/                 # Ignore magic methods (__str__, etc.)
interrogate --ignore-module src/                # Ignore module-level docstrings
interrogate --ignore-nested-classes src/        # Ignore nested classes
interrogate --ignore-nested-functions src/      # Ignore nested functions
interrogate --ignore-private src/               # Ignore private methods (_method)
interrogate --ignore-semiprivate src/           # Ignore semiprivate methods (_method)
interrogate --ignore-property-decorators src/   # Ignore @property decorators
interrogate --ignore-setters src/               # Ignore @property.setter methods
interrogate --ignore-overloaded-functions src/  # Ignore @typing.overload functions

Pattern-Based Filtering

Options for filtering files and code elements using patterns.

# Exclude files/directories by pattern
interrogate --exclude tests --exclude docs src/

# Ignore code elements by regex pattern
interrogate --ignore-regex "test_.*" --ignore-regex ".*_test$" src/

# Include only specific patterns (whitelist)
interrogate --whitelist-regex "^public_.*" --whitelist-regex "^api_.*" src/

# Include .pyi stub files
interrogate --ext pyi src/

# Combine multiple patterns
interrogate --ignore-regex "^get_.*" --ignore-regex "^set_.*" --ignore-regex "test_.*" src/

Output Control

Options controlling output format and verbosity.

# Verbose output with detailed information
interrogate --verbose src/                      # Show detailed results
interrogate -vv src/                           # Very verbose output

# Quiet output
interrogate --quiet src/                       # Suppress detailed output  
interrogate -qq src/                          # Very quiet (minimal output)

# Disable colored output
interrogate --no-color src/

# Omit files with 100% coverage from detailed output
interrogate --omit-covered-files src/

# Save output to file
interrogate --output results.txt src/

Quality Control

Options for enforcing coverage standards and failing builds.

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

# Different docstring styles (affects validation)
interrogate --docstring-style sphinx src/      # Sphinx style (default)
interrogate --docstring-style google src/      # Google style
interrogate --docstring-style numpy src/       # NumPy style

Badge Generation

Options for generating coverage badges.

# Generate SVG badge in current directory
interrogate --generate-badge . src/

# Generate badge with specific filename
interrogate --generate-badge docs/coverage.svg src/

# Generate PNG badge (requires cairosvg)
interrogate --generate-badge docs/coverage.png --badge-format png src/

# Different badge styles
interrogate --generate-badge . --badge-style flat src/           # Default flat style
interrogate --generate-badge . --badge-style flat-square src/    # Flat square style
interrogate --generate-badge . --badge-style for-the-badge src/  # For-the-badge style
interrogate --generate-badge . --badge-style plastic src/        # Plastic style

Configuration Files

Options for using configuration files.

# Use specific configuration file
interrogate --config pyproject.toml src/
interrogate --config setup.cfg src/

# Configuration file auto-discovery (default behavior)
# Searches for pyproject.toml or setup.cfg in project root
interrogate src/

Usage Examples

Basic Usage

# Analyze current directory
interrogate .

# Analyze specific directories
interrogate src/ tests/

# Analyze specific files
interrogate src/main.py src/utils.py

Common CI/CD Patterns

# Strict coverage check for CI
interrogate --fail-under 85 --ignore-init-method --ignore-private src/

# Generate badge and check coverage
interrogate --generate-badge docs/coverage.svg --fail-under 80 src/

# Quiet mode for CI with specific threshold
interrogate --quiet --fail-under 90 --omit-covered-files src/

Development Workflow

# Detailed analysis during development
interrogate --verbose --color src/

# Focus on missing docstrings only
interrogate --verbose --omit-covered-files src/

# Check specific patterns
interrogate --ignore-regex "test_.*" --ignore-private --verbose src/

Complex Configuration

# Comprehensive configuration
interrogate \
  --fail-under 85 \
  --ignore-init-method \
  --ignore-private \
  --ignore-magic \
  --ignore-regex "test_.*" \
  --ignore-regex ".*_callback$" \
  --exclude tests \
  --exclude docs \
  --exclude migrations \
  --generate-badge docs/coverage.svg \
  --badge-style flat-square \
  --verbose \
  --color \
  src/

Integration Examples

GitHub Actions

# .github/workflows/docs.yml
- name: Check docstring coverage
  run: |
    interrogate --fail-under 80 --generate-badge docs/coverage.svg src/
    
- name: Commit badge
  run: |
    git add docs/coverage.svg
    git commit -m "Update coverage badge" || exit 0
    git push

Pre-commit Hook

# .pre-commit-config.yaml
- repo: https://github.com/econchick/interrogate
  rev: 1.7.0
  hooks:
    - id: interrogate
      args: [--fail-under=80, --ignore-init-method, --ignore-private]

Makefile Integration

# Makefile
.PHONY: docs-coverage
docs-coverage:
	interrogate --generate-badge docs/coverage.svg --fail-under 85 src/

.PHONY: check-docs
check-docs:
	interrogate --fail-under 85 --quiet --omit-covered-files src/

Exit Codes

The CLI returns different exit codes based on analysis results:

0: Success (coverage meets threshold or no threshold set)
1: Coverage below threshold (when --fail-under is used)
2: Command-line argument error
3: Configuration file error

# Example usage with exit code handling
if interrogate --fail-under 80 src/; then
    echo "Coverage check passed"
else
    echo "Coverage check failed"
    exit 1
fi

Module Execution

Interrogate can also be run as a Python module:

# Equivalent to 'interrogate' command
python -m interrogate src/

# With arguments
python -m interrogate --fail-under 80 --verbose src/

Help and Version

# Show help
interrogate --help

# Show version
interrogate --version

Install with Tessl CLI

npx tessl i tessl/pypi-interrogate

docs