wrap-docstrings
DocsWraps a docstring's description prose to docstring-line-length and its Title-case-headed sections to the budget docstring-structured-policy selects.
expand-docstrings
expand-docstrings rewrites every single-line triple-quoted docstring (opener, body, and closer all on one line) into the multi-line form, putting the opener, the body, and the closer each on a line of its own, so every documented unit in a project shows one structure. A single-line docstring reads as a kind of inline comment, and downstream tools (Sphinx, IDE hover previews, doctest, PEP 257-aware linters) treat it differently from its multi-line sibling.
The rule fires on module, class, and function single-line docstrings. The body text moves onto its own line at the docstring's indent with its leading and trailing whitespace trimmed and nothing else changed. frame-docstrings runs ahead of this rule and settles the quotes, so a requoted one-liner expands in the same pass, and wrap-docstrings then wraps the description prose against its budget.
The Docstring walker reads against the PEP 257 definition, so an f-string (f"""..."""), a bytes literal (b"""..."""), and a concatenated string never count as docstrings and the rule skips them. A raw-prefixed (r""") single-line docstring expands the same way as a plain one, with the prefix kept on the opener. A docstring whose body is empty or whitespace alone ("""""") stays as written, as does a non-triple-quoted one-liner and a docstring sharing the def line with its definition. The PEP 257 summary-line convention is out of scope for this rule, leaving the body's wording to authors and downstream conventions.
Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Turns the rule on or off. |
The Canonical Case
The module docstring """Module summary on a single line.""" keeps its opener, body, and closer on one physical line. It expands to three lines, with Module summary on a single line. on its own line at column zero, the indent a module-level statement takes.
# A single-line module docstring at column 0. The docstring is the
# rewrite target itself, so these comments stand above it in its place.
"""
Module summary on a single line.
"""
x = 1More Examples
Bag's docstring """A simple bag.""" sits on one line directly under the class line. It expands to three lines, with A simple bag. at the class-body indent, the column def __init__ starts at, because the rule reads the enclosing scope's indent rather than adding a fixed offset.
empty's docstring """Return whether the bag is empty.""" sits on one line inside a def nested in class Bag. It expands with its body line at the method-body indent, two steps in from column zero, the same column return not self.items starts at, because the rule reads the enclosing indent rather than counting from column zero.
greet's docstring """Hello, world.""" sits on one line. It expands to three lines, opener, body, and closer each on its own line, with Hello, world. written between them unchanged apart from the surrounding whitespace the rule trims, at the body indent of the def.
outer and the inner function nested inside it each carry a one-line docstring. Both expand, each body line at the indent of its own def, so Inner docstring. sits one indent step deeper than Outer docstring., because the rule fires once per docstring at every nesting level.
zeta,alpha, andbetaarrive out of order,alphawith a two-line docstring and the other two with one-line docstrings. alphabetize-siblings sorts the methods, expand-docstrings rewrites the one-line docstrings ofbetaandzetato multi-line form, and frame-docstrings puts every"""on its own line, with space-statements writing one blank line between the methods.
Related
frame-docstrings
DocsRewrites a docstring's quotes to the triple-double-quote form and puts a multi-line docstring's opener and closer on their own lines.
For the docstring budgets that govern wrapping, the Configuration chapter covers the description and structured line lengths.