docstring-wrap
DocsProse wraps multi-line
docstring-expand
A single-line docstring (opener, body, and closer all on one line) reads as a kind of inline comment, and many downstream tools (Sphinx, IDE preview surfaces, doctest, PEP 257-aware linters) treat it inconsistently with its multi-line sibling.
expands every single-line triple-quoted docstring into the canonical multi-line shape, so a project's documentation surface presents one consistent structure across every documented unit.The rule fires on module, class, and function single-line docstrings. The body content is preserved verbatim across the expansion, and the resulting multi-line form passes immediately to
for the opener-and-closer placement and to for the line-budget wrap.The walker Docstring reads against the PEP 257 definition, so f-string forms (f"""...""") and concatenated string forms never qualify as docstrings and the rule skips them. Raw-prefixed (r""") and byte-prefixed (b""") single-line docstrings expand the same way as plain triple-quoted forms, with the prefix preserved verbatim on the opener. An empty single-line docstring ("""""") expands to a multi-line shape with a blank line between the opener and the closer. The PEP 257 summary-line convention is out of scope for this rule, leaving the body content's shape to authors and downstream conventions.
Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Toggle the rule on or off |
The Canonical Case
A
python
# This fixture pins module-level single-line docstring rewriting at
# column 0. The fixture's module docstring is itself the rewrite
# target, so the conventional triple-quoted claim-banner is replaced
# by these `#` comments.
"""
Module summary on a single line.
"""
x = 1More Examples
A class-level """A simple bag.""" splits across three lines with the body line landing at the class-body indent, sitting exactly where any other class-scope statement would. The rewrite tracks the enclosing
A method return not self.items, confirming the rewrite reads the actual enclosing indent rather than counting from column 0.
Outer and inner function defs each carry a single-line
A function's """Hello, world.""" becomes the canonical three-line shape with opener, body, and closer each on their own line. The body text passes through unchanged, trimmed of surrounding whitespace and re-laid at the def's body indent.
Related
docstring-frame
DocsProse drops a multi-line
For the docstring budgets that govern wrapping, the Configuration chapter covers the description and structured line lengths.