stouputils.check.rules module#

The rules stouputils check knows, the settings a project tunes them with, and the violations they report.

RULES: dict[str, str] = {'banned-characters': 'Long dashes, ellipsis, multiplication sign, arrows, curly quotes and box-drawing comment banners', 'constant-comment': 'A module constant documented by a trailing comment instead of a docstring below it', 'examples-header': 'An ``Examples:`` header above doctests, which ``>>>`` already marks', 'final-newlines': 'A file not ending with the configured number of newline characters', 'long-comment': 'A block of consecutive comment lines over the limit', 'long-docstring': 'A function or class docstring over the line limit', 'module-docstring-position': 'A module docstring below line 1', 'space-alignment': 'Python code aligned with a tab after the first character instead of spaces', 'split-span': 'Inline code or a quote opened on one line of a comment or docstring and closed on another', 'stranded-fragment': 'A line break in a comment or docstring leaving a few words of a clause alone', 'syntax-error': 'A Python file the tokenizer or the parser rejects', 'tab-indentation': 'Python code indented with a space instead of tabs', 'typed-argument': 'An ``Args:`` entry repeating the type the signature carries'}[source]#: Every rule by the name ignore takes, with what it reports.

class Violation( line: int, rule: str, message: str, end_line: int | None = None, )[source]#

Bases: object

One rule broken at one line, or on every checked line of a range.

line: int[source]#

rule: str[source]#

message: str[source]#

property span: str[source]#

The line, or the range of lines, as written in a report.

>>> Violation(3, "long-comment", "").span, Violation(3, "tab-indentation", "", end_line=9).span
('3', '3-9')

class CheckConfig( ignore: Collection[str] = (), final_newlines: dict[str, int]=<factory>, docstring_max_lines: int = 15, comment_max_lines: int = 2, fragment_max_words: int = 3, )[source]#

Bases: object

Settings of the [tool.stouputils.check] table of a pyproject.toml, keys spelled with dashes.

>>> CheckConfig(ignore=["tab-indentation", "space-alignment"]).final_newlines
{'.py': 2, '.json': 1}
>>> CheckConfig(ignore=["tabs"])
Traceback (most recent call last):
        ...
ValueError: Unknown rules in ignore: ['tabs'], the known ones are banned-characters, ...

ignore: Collection[str] = ()[source]#: Rules left unchecked, by their name in RULES.

final_newlines: dict[str, int][source]#: Exact number of newline characters a file ends with, by suffix, replacing the defaults as a whole.

docstring_max_lines: int = 15[source]#: Longest docstring of a function or a class, doctests included.

comment_max_lines: int = 2[source]#: Longest block of consecutive comment lines.

fragment_max_words: int = 3[source]#: Most words a clause cut by a line break may leave alone on one side of it.

classmethod for_directory( directory: Path, ) → Self[source]#: Settings of the nearest pyproject.toml holding the table, looking upward like ruff, defaults without one.