Docstring Lint Runner

A utility that runs docstring linting across Python files, exposing exit codes and structured messages for CI or tooling without reimplementing lint rules.

Capabilities

Runs lint and propagates exit codes

• Linting a directory of well-documented files returns exit code 0 with no messages. @test
• Linting a file missing a public function docstring returns exit code 1 and yields a message with the file path and line number of the violation. @test
• Passing an invalid option combination (such as an unknown convention) returns exit code 2 and reports the CLI error text. @test

Convention selection

• Selecting the Google docstring convention surfaces an error for a function missing argument documentation, while default settings do not flag the same code. @test

Inline ignore control

• When respect_inline_ignore is true, lines marked with # noqa: Dxxx are not reported; when false the same lines produce violations. @test

Message detail toggles

• When include_explanation is true, each message includes the rule explanation text from the linter. @test
• When include_source is true, each message includes the offending source snippet. @test

Implementation

@generates

API

from dataclasses import dataclass
from typing import Iterable, Optional

@dataclass
class LintMessage:
    code: str
    path: str
    line: int
    message: str
    explanation: Optional[str]
    source: Optional[str]

@dataclass
class LintResult:
    exit_code: int
    messages: list[LintMessage]

def lint_paths(
    targets: Iterable[str],
    *,
    convention: Optional[str] = None,
    respect_inline_ignore: bool = True,
    include_explanation: bool = False,
    include_source: bool = False,
) -> LintResult:
    """
    Run the docstring linter over provided files or directories, applying the requested
    convention and inline-ignore behavior via the linter dependency. Return structured
    messages and the exit code reported by that linter (0 clean, 1 violations, 2 invalid
    invocation).
    """

Dependencies { .dependencies }

pydocstyle { .dependency }

Docstring linter CLI used to produce errors, exit codes, explanations, and source snippets.