krrood.development_tools.formatting

Formats Python files with ruff, then applies docformatter only where its output stays stable under a second ruff pass.

docformatter can miscount the blank lines it leaves after an attribute docstring that immediately precedes a decorated top-level class or function definition (it forgets to special-case the decorator), so it sometimes undoes exactly what ruff then re-adds. Re- running both tools forever would never converge for those files, so the plain ruff- formatted content is kept for a file whenever docformatter’s result does not survive a subsequent ruff pass unchanged.

Attributes

logger

Classes

Formatter	The formatting tools, by the module name they run under.
RuffArgument	The command line arguments ruff is run with.
DocformatterOption	The command line options docformatter is run with.
RuffExitCode	The exit code ruff reports when it formatted a file successfully.
DocformatterExitCode	The exit codes docformatter reports when it formatted a file successfully.
FileFormattingOutcome	The result of formatting a single file.
DocstringFormatter	Formats files with ruff, and their docstrings with docformatter where docformatter

Module Contents

krrood.development_tools.formatting.logger

class krrood.development_tools.formatting.Formatter

Bases: enum.StrEnum

The formatting tools, by the module name they run under.

RUFF = 'ruff'

DOCFORMATTER = 'docformatter'

run(arguments: Sequence[str], file_path: pathlib.Path) → int

Run this tool on file_path with the interpreter running this code.

Parameters:

• arguments – The command line arguments to pass before the file.

• file_path – The file to format, in place.

Returns:

The tool’s exit code.

Raises:

FormatterNotInstalled – If the tool is not installed for this interpreter.

class krrood.development_tools.formatting.RuffArgument

Bases: enum.StrEnum

The command line arguments ruff is run with.

FORMAT = 'format'

QUIET = '--quiet'

ISOLATED = '--isolated'

Ignore every configuration file, so each repository formats alike.

class krrood.development_tools.formatting.DocformatterOption

Bases: enum.StrEnum

The command line options docformatter is run with.

IN_PLACE = '--in-place'

MAKE_SUMMARY_MULTI_LINE = '--make-summary-multi-line'

PRE_SUMMARY_NEWLINE = '--pre-summary-newline'

CLOSE_QUOTES_ON_NEWLINE = '--close-quotes-on-newline'

BLACK_COMPATIBLE = '--black'

class krrood.development_tools.formatting.RuffExitCode

Bases: enum.IntEnum

The exit code ruff reports when it formatted a file successfully.

SUCCESS = 0

class krrood.development_tools.formatting.DocformatterExitCode

Bases: enum.IntEnum

The exit codes docformatter reports when it formatted a file successfully.

UNCHANGED = 0

CHANGED = 3

class krrood.development_tools.formatting.FileFormattingOutcome

The result of formatting a single file.

path: pathlib.Path

The file that was formatted.

original_content: str

The file’s content before formatting.

final_content: str

The file’s content to write back.

docstrings_reformatted: bool

Whether docformatter’s changes were kept.

False means they were discarded because they conflicted with ruff.

property changed: bool

Whether formatting changed the file’s content.

class krrood.development_tools.formatting.DocstringFormatter

Formats files with ruff, and their docstrings with docformatter where docformatter agrees with ruff.

format_file(path: pathlib.Path) → FileFormattingOutcome

Compute the formatted content of one file without writing it back.

Parameters:

path – The file to format.

Returns:

The formatting outcome for path.

format_files(paths: Sequence[pathlib.Path]) → bool

Format each file, writing back changes and reporting discarded docstring changes.

Parameters:

paths – The files to format.

Returns:

Whether any file was modified.