docstring-frame
DocsCanonicalizes a docstring's quotes and frames the opener and closer.
docstring-wrap
A docstring carries two readings inside one triple-quoted region. The description prose between the opening """ and the first section heading reads as paragraphs, where 76 characters is the comfortable line for sustained reading. Every Title-case-headed section that follows reads as a code-shaped table, where the line budget matches the surrounding code's code-line-length (88 by default) so that argument annotations sit at the same column as the function body's expressions.
The rule reads docstring-line-length for the description budget, code-line-length for the structured budget, and docstring-structured-policy to override the structured budget when a project prefers a single narrower line across the whole docstring. Code blocks inside the description (fenced or indented) are preserved verbatim, since their layout is load-bearing. reStructuredText field lists, doctest blocks, section underlines, and Sphinx directives pass through unwrapped for the same reason, so structured markup keeps the shape a renderer reads rather than collapsing into a paragraph. A token that reads as a URL or carries an embedded path / or - wraps as one atomic word, so an over-budget link overflows the measure intact rather than splitting between its segments. The two sibling docstring rules sit upstream of this one:
Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Toggles the rule on or off. |
Description and structured budgets come from the top-level Configuration keys: docstring-line-length (default 76), code-line-length (default 88), and docstring-structured-policy (defaulting to "code-line-length") drive the column targets.
The Canonical Case
Description prose wraps to docstring-line-length, with the existing paragraph structure preserved across the rewrap.
def greet():
"""
The function-level description carries the same wrap shape as the module
docstring, with each wrapped line indented to match the docstring body.
"""
return 1More Examples
A token that reads as a URL or carries an embedded path / or - wraps as a single atomic word, so an over-budget link lands on its own line and overflows the budget intact rather than splitting between its segments, keeping the value copy-pasteable.
An Attributes: section in a class docstring wraps its entries with the same hanging-column shape a function Args: entry uses. The walker visits every body whose first statement is a string literal, so class and function docstrings reshape identically.
A docstring carrying both a description paragraph and a structured Args: section wraps each region to its own shape. The paragraph wraps at the docstring budget against the body indent, and the Args: entry wraps at the same budget with a hanging indent at the description column.
A long Args: entry that overruns its line re-wraps to the section budget with a hanging indent at the description's start column, so continuation lines sit under the description rather than at the parameter-list indent. A short sibling entry below it is left alone.
A Returns: section body wraps to the section budget, so the return-value description tracks the same horizontal room the Args: table uses rather than the narrower description budget.
A .config.toml sidecar flips docstring-structured-policy so non-entry section bodies wrap at the narrower docstring budget instead of the default structured budget. A long Note: paragraph wraps at the docstring width once the policy selects it.
No Change
A docstring whose description and section bodies already fit their budgets passes through unchanged. The rule fires only when wrapping actually shortens a line, so short Args: and Returns: entries produce no edit.
No Change
List items pass through verbatim and are never re-flowed onto multiple lines, even when an item runs long. The recognized markers cover -, *, +, and numeric ordered items, matching the CommonMark set. Body text after the list resumes the description budget.
No Change
A doctest block passes through verbatim. A >>> prompt opens an interactive region that runs to the next blank line, so an example and its expected output never join under a reflow.
No Change
A triple-backtick fenced code block passes through verbatim no matter how wide its lines run. The fence marks the region as code rather than prose, so the wrap math leaves it untouched.
No Change
A four-space-indented block under a description paragraph passes through verbatim because indented blocks read as code samples. Re-flowing them would damage their semantics, so the rule leaves the over-budget lines in place.
No Change
A NumPy-style section underline passes through verbatim. A line that is a run of one repeated adornment character such as -, =, or ~ flushes the open paragraph and keeps the heading's landmark instead of gluing onto the line above.
No Change
A reStructuredText field list passes through unwrapped, one field per line. Each :name: value line opens a field-list region the wrap math skips, so a run of module metadata survives instead of gluing onto its neighbor.
No Change
A Sphinx directive passes through verbatim. A .. name:: line opens a directive block, so consecutive directives stay one per line instead of merging into a paragraph a renderer would read as a single directive.
Related
For the budget semantics, the Docstring Budgets section of the Configuration chapter covers how the description and structured budgets interact.