Config-Aware Docstring Lint Runner

Build a helper that runs a docstring linter over given files or directories while relying on its configuration discovery, inheritance, and CLI overrides.

Capabilities

Discovers nearest config automatically

• When invoked without an explicit config path, it uses the linter's built-in discovery to honor pyproject.toml, setup.cfg, tox.ini, or .pydocstyle files in parent directories for the selected targets. @test

Merges parent and child settings when allowed

• When both a parent and nested directory supply lint config with inheritance enabled, the runner merges them so child-specific selectors augment (not replace) parent options for files in that nested directory. @test

Explicit config disables discovery

• Providing a config_path argument causes discovery to be skipped and only the supplied config to be used for all targets. @test

CLI options override config rules

• Passing CLI overrides such as selected or ignored error codes applies on top of the chosen configuration so overrides take precedence for the current run. @test

Implementation

@generates

API

from pathlib import Path
from dataclasses import dataclass
from typing import Iterable, Sequence

@dataclass
class LintMessage:
    code: str
    message: str
    location: str  # "<path>:<line>"

class ConfigAwareLintRunner:
    def __init__(self, root: Path):
        """Prepare the runner scoped to a project root for config discovery."""

    def run(
        self,
        targets: Iterable[Path],
        config_path: Path | None = None,
        select: Sequence[str] | None = None,
        ignore: Sequence[str] | None = None,
    ) -> list[LintMessage]:
        """
        Run the docstring linter on provided targets.

        - Uses discovery across supported config files when config_path is None.
        - Skips discovery and uses only config_path when provided.
        - Applies select/ignore overrides on top of the configuration for this run.
        """

Dependencies { .dependencies }

pydocstyle { .dependency }

Docstring style checker with configuration discovery, inheritance, and CLI overrides.