Docstring Gatekeeper

Create a lightweight docstring linting helper that focuses on selecting Python files by regex and enforcing missing-docstring rules based on public objects inferred from module names and __all__.

Capabilities

Filters files by regex

• Given a directory containing core_alpha.py and util_extra.py, running with file pattern ^core_.*\\.py$ reports issues only from core_alpha.py. @test

Respects __all__ for public API

• In a module that sets __all__ = ["public_fn"], a missing docstring on public_fn is reported while a missing docstring on hidden_fn is ignored. @test
• For a package whose __init__.py sets __all__ = ["exposed"], the module exposed.py is treated as public and must have a module docstring when linted. @test

Reports missing docstrings

• Running against a folder with a public class and its public method lacking docstrings emits missing-docstring issues that include the file path, line number, code, and message for each violation. @test

Implementation

@generates

API

from pathlib import Path
from typing import Iterable, List, Pattern, TypedDict, Union


class DocIssue(TypedDict):
    file: str
    line: int
    code: str
    message: str


def lint_docstrings(
    targets: Iterable[Union[str, Path]],
    file_regex: Union[str, Pattern[str]] = r".*\\.py",
    include_source: bool = False,
) -> List[DocIssue]:
    """Return missing-docstring issues for regex-matched files under the given targets."""

Dependencies { .dependencies }

pydocstyle { .dependency }

Docstring style checker with regex-based file selection and public/__all__-aware missing-docstring detection.