epythet.validation.lint

Level 0: static docstring linters, normalised into the finding model.

Two tools are shelled out to. ruff check --select D covers pydocstyle (presence, summary lines, section formatting for the configured convention). pydoclint covers signature consistency (DOC1xx/DOC2xx/DOC4xx/ DOC5xx: undocumented or misnamed parameters, missing returns), which ruff only previews a handful of; it is optional and skipped with a note when it is not installed.

Findings keep the tool’s own code as rule (D102, DOC101) and name the tool in tool, so they never collide with ledger ids.

Module Attributes

STYLES	Docstring styles ruff's pydocstyle convention and pydoclint's --style both accept.
RUFF_D_IGNORE	D107 (__init__ must have its own docstring) contradicts pydoclint's DOC301 (__init__ must NOT have one; its Args merge into the class docstring) -- the house convention this repo's docstring-style skill already documents.
PYDOCLINT_OPTIONS	types live in annotations, never in the docstring.

Functions

pydoclint_severity(code)	DOC1xx (arguments disagree with the signature) are warnings; the rest info.
ruff_severity(code)	D1xx (missing docstrings) are warnings; other D rules are style, so info.
run_lint_level(package_dir, *, project_dir)	Level 0: ruff D plus pydoclint, with notes for anything skipped.
run_pydoclint(package_dir, *, project_dir[, ...])	Run pydoclint if installed; otherwise return a note and no findings.
run_ruff(package_dir, *, project_dir[, style])	Run ruff check --select D and translate its JSON output.

epythet.validation.lint.PYDOCLINT_OPTIONS = ('--quiet', '--skip-checking-short-docstrings', 'true', '--arg-type-hints-in-docstring', 'false', '--arg-type-hints-in-signature', 'true', '--check-return-types', 'false', '--check-yield-types', 'false')

types live in annotations, never in the docstring. --arg-type-hints-in-signature true tells pydoclint that is how a documented signature looks (DOC108 fires on the opposite reading: false means “expect no type hints in the signature”, which trips on every annotated function). --arg-type-hints-in-docstring false keeps it from asking for types in the docstring text. --allow-init-docstring defaults to False, which enforces DOC301 (__init__ undocumented, its Args merged into the class docstring) – the convention this house already writes to, so it is left at its default rather than passed explicitly.

Type:

pydoclint options for the house convention

epythet.validation.lint.RUFF_D_IGNORE = ('D107',)

D107 (__init__ must have its own docstring) contradicts pydoclint’s DOC301 (__init__ must NOT have one; its Args merge into the class docstring) – the house convention this repo’s docstring-style skill already documents. Only one side can pass, so the ruff side is dropped.

epythet.validation.lint.STYLES = ('google', 'numpy', 'sphinx')

Docstring styles ruff’s pydocstyle convention and pydoclint’s --style both accept.

epythet.validation.lint.pydoclint_severity(code)

DOC1xx (arguments disagree with the signature) are warnings; the rest info.

Return type:

str

>>> pydoclint_severity("DOC101"), pydoclint_severity("DOC201")
('warning', 'info')

epythet.validation.lint.ruff_severity(code)

D1xx (missing docstrings) are warnings; other D rules are style, so info.

Return type:

str

>>> ruff_severity("D102"), ruff_severity("D205")
('warning', 'info')

epythet.validation.lint.run_lint_level(package_dir, *, project_dir, style='google', ignore=())

Level 0: ruff D plus pydoclint, with notes for anything skipped.

ignore is the --ignore list every other level applies at file discovery; the linters walk the package themselves, so their findings are filtered by the same predicate (is_ignored()) on the file’s full path.

Return type:

tuple[list[Finding], list[str]]

epythet.validation.lint.run_pydoclint(package_dir, *, project_dir, style='google')

Run pydoclint if installed; otherwise return a note and no findings.

pydoclint writes its report to stderr, so both streams are parsed.

Return type:

tuple[list[Finding], list[str]]

epythet.validation.lint.run_ruff(package_dir, *, project_dir, style='google')

Run ruff check --select D and translate its JSON output.

Returns (findings, notes); notes explains a skipped run.

Return type:

tuple[list[Finding], list[str]]