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.
wrap-docstrings
wrap-docstrings wraps the prose inside a docstring to its budget, reading two kinds of text inside one triple-quoted region. The description prose between the opening """ and the first section heading wraps as paragraphs at docstring-line-length. Every Title-case-headed section below it reads as a code-shaped table, its running text taking the budget docstring-structured-policy selects (code-line-length, 88 by default) so it measures with the code around it, whereas its name: description entries wrap to docstring-line-length with a hanging indent at the column the description starts on.
The rule reads docstring-line-length for the description budget, code-line-length for the structured budget, and docstring-structured-policy where a project prefers one narrower line across the whole docstring.
A structured block (a fenced or indented code block, a table, a doctest, a field header) passes through unwrapped, because its layout carries meaning. An interpreted-text role closes its name on a backtick rather than on whitespace, so a line opening with :class: or :math: reads as prose and wraps with its paragraph.
Rewrapped prose collapses every interior whitespace run to one space, so the word sequence is identical on every run, whereas a section entry's aligned head stays as written. Its description wraps at the width strip-stranded-padding settles that head to, where the strip removes the padding before a lone entry's :. Section prose wraps one line at a time, first-fit, so a row the rule writes re-wraps to itself. A break that would put a comment marker, an entry head, or a list marker at the start of the next row folds back into the word before it, because the bare #, name:, or + a wrap would leave at the head of the next row reads as the marker it is. A token that reads as a URL or carries an embedded / or - wraps as one whole word, so an over-budget link overflows the budget intact rather than splitting between its segments.
A backslash ending a line of a non-raw docstring continues it into the next, so the rule resolves that continuation into the join it performs anyway rather than carrying the backslash mid-line as the invalid escape \ . A join with no whitespace on either side splices first, so a URL broken across two source lines stays one token. A continuation inside a passthrough block moves with it as written, and a raw docstring has none at all, its backslash being a literal character.
An entry's head line and every line below it that opens no entry of its own read as one paragraph, rewrapped from the description column the settled head leaves, so padding that moves the : reflows the whole description rather than stranding the continuation lines. A line whose own form marks it as structure is exempt, so a doctest, a list item, or a bracketed literal under an entry keeps its layout.
The sibling rules frame-docstrings and expand-docstrings settle the quoting and the framing before this rule measures anything, and the wrap runs after align-colons so an entry's budget reflects the column its key was padded to. The Pipeline Order reference lists where each sits.
Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Turns the rule on or off. |
The description and structured budgets come from the top-level Configuration keys, where docstring-line-length (default 76), code-line-length (default 88), and docstring-structured-policy (defaulting to "code-line-length") set the column targets.
The Canonical Case
The one paragraph in greet's docstring runs past docstring-line-length. It wraps to that budget with every wrapped line written at the docstring body indent, and the rewrap moves words across the line break without splitting or merging the paragraph.
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
The resolve docstring ends its first line with a backslash, which in a non-raw string suppresses the newline after it, so the two source lines already form one logical line of the docstring's value. The wrap joins and reflows that logical line and drops the backslash, because carrying it into the reflowed text would put it mid-line as the invalid escape \ and change the string's value.
This docstring's body opens with the :class: role naming ~ensemble.VotingClassifier, a position where a field list could begin. The line reads as prose and the paragraph wraps to the budget, because the field-list test runs at that block boundary and fails on the role's closing backtick.
Posting's class docstring carries an Attributes: section whose title entry runs past the budget. The entry wraps with the same hanging indent a function's Args: entry takes, its continuation line sitting under A descriptive title, because the rule visits every body whose first statement is a string literal, so class and function docstrings wrap identically.
The URL in reference's docstring is split with a trailing \ and resumed flush at column zero, so no whitespace separates the two halves across the join. The wrap splices the halves back into one token before measuring and writes the URL alone on its own line, because joining the two as ordinary prose lines would insert a space the value never had and break the link in two.
render's docstring carries a description paragraph and a structured Args: section, both over budget. The paragraph wraps at the docstring budget from the body indent, and the label entry wraps at that same budget with a hanging indent at its description column, while the short count entry is left as written.
The pattern docstring carries an r prefix, so its trailing backslash continues nothing and is a literal character of the docstring's value. The wrap reflows the \ as an ordinary word, which puts it mid-line in the output, whereas the same backslash in a non-raw docstring would be a line continuation to resolve away.
The name entry under Args: runs past its budget, whereas the short retries entry below it fits. name re-wraps to the docstring budget with a hanging indent, its continuation lines sitting under A descriptive name at the column the description starts on rather than back at the parameter-list indent, and retries is left as written.
The description under Returns: in total's docstring names no entry and runs past the budget. It wraps to the structured budget rather than the narrower description budget, reflowing onto two lines at the section body indent, because a structured section body without a name: head takes the wider budget.
The module docstring separates its two sentences with a double space after disk.. The double space collapses to one as the paragraph reflows, because every whitespace run between reflowed words collapses to a single space, and left alone the run would survive mid-line and vanish only at a wrap point, leaving the measured length to depend on where the wrap fell.
The parse_link_headers description ends in a URL that alone exceeds the budget. The wrap breaks after see: and writes the URL whole on its own line, overflowing the budget, because a token carrying a path / or - wraps as one atomic word, which keeps the value copy-pasteable.
The wrap puts the :class: role of ~ensemble.VotingClassifier at the start of a line, the position where a field list would normally open. The role stays inside the reflowed paragraph rather than opening a field list, because a field list opens only at a block boundary, so a marker arriving at the start of a continuation line still reads as ordinary prose.
The line under Notes: carries a bare #, a threshold: head, and a +, and a first-fit wrap at the code-line-length = 40 the case sets would open a row on threshold:. Each marker moves down with the word before it, so the wrap writes writes threshold: together rather than opening a row that would read as a new entry, and the same guard keeps the bare # and + markers glued to the words ahead of them.
The case sets docstring-structured-policy = "docstring-line-length", and the paragraph under Note: runs past that width. The section body reflows across three lines at the docstring budget rather than the default structured budget, because the policy selects which budget a structured section's prose wraps to.
No Change
The docstring carries list items under -, +, and 1. markers, the first - item running far past the budget, followed by a Continuation prose paragraph. Every list item passes through verbatim, the over-budget - item included, and the Continuation prose paragraph below the list, which already fits the budget, is written unchanged, because the markers are drawn from the CommonMark set and a line opening on one reads as a list item rather than prose.
No Change
The example under Summary line. opens with a # comment and continues into total = sum(values) and print(total). All three lines pass through verbatim, one statement per line, because the comment opens a passthrough block that runs to the next blank line, so the statements never merge into one paragraph.
No Change
Every line of the configure docstring, the short Args: entries and the one-line Returns: body included, already fits its budget. The whole docstring passes through unchanged, because the rule writes an edit only where wrapping would shorten a line.
No Change
add's docstring carries a doctest block, >>> add(2, 3) with its expected 5 and >>> add(10, 20) with its 30. The block passes through verbatim, because a >>> prompt opens an interactive region that runs to the next blank line, so a prompt and its output never join under a reflow.
No Change
The fenced python block in example's docstring carries an x = some_long_identifier + ... line wider than the budget. The block passes through verbatim however wide its lines run, because the fence marks the region as code rather than prose, so the wrap never measures it.
No Change
The handlers line sits under no section heading, and its parenthesized Callable type runs the line past the budget. The line stays whole, because the parenthesized type marks it as a field header rather than prose, and a wrap would split the type at one of its interior commas and put the remainder at the column a new field name would occupy.
No Change
The Encoder docstring carries a reStructuredText grid table mapping Python types to their JSON equivalents. The table keeps its rows and column widths untouched, because a line opening with a + border or a | cell delimiter passes through verbatim, so the grid is never reflowed into a paragraph no renderer would display as a table.
No Change
Example:: closes on the second colon reStructuredText opens a literal block with, and the indented sample beneath it runs past the code-line-length = 40 the case sets. The sample passes through verbatim, because a heading closing on :: opens no section, whereas one closing on a single : would, and wrapping the sample as section prose would have rewritten it into broken Python.
No Change
The ---------- underline beneath Parameters is a run of one repeated adornment character. It passes through verbatim and keeps its place under the heading, because a line made of one repeated character ends the open paragraph and is written as it stands, so the NumPy heading is never reflowed into the prose around it.
No Change
The module docstring is a reStructuredText field list running from :codeauthor: to :platform:. It passes through unwrapped, one field per line, because each :name: value line opens a field-list region the wrap math skips, so the metadata lines never merge into one paragraph.
No Change
The reStructuredText simple table under Summary line. has dict and list rows that open with no leading punctuation at all. The table keeps its columns, because the spaced ===== adornment above the rows opens a passthrough block that runs to the next blank line, so the rows stay under the Name and Meaning headings.
No Change
.. versionadded:: 0.10 and .. deprecated:: 1.0 sit on consecutive lines. Both pass through verbatim, one per line, because a line opening with .. starts a directive block, and reflowed into one paragraph they would render as a single directive.
No Change
Under Summary line., two assignments sit indented four extra spaces, the first running past the budget. The block passes through verbatim, over-budget line included, because an indented block reads as a code sample and reflowing code would break it.
render's docstring starts its summary on the"""line and carries anArgs:section. frame-docstrings moves the summary off the opener line, align-colons pads the:aftertemplate,context_map, andescape_htmlinto one column, and wrap-docstrings wraps the summary to the docstring budget across two lines.Both
Attributes:entries ofProcessrun past the docstring budget before anything wraps them. align-colons pads both:to one column pastcommand_messagewith no line cap of its own, and wrap-docstrings then reflows each description withindocstring-line-lengthand hangs the wrapped lines from that padded column, so both entries reach their final layout in one pass rather than drifting across several.The one
Args:entry offetchis writtentimeout : Maximum seconds to wait before giving up., with a space before its:, and its description runs past the 40-column docstring budget. strip-stranded-padding removes the space, because a lone entry has no sibling column to share, and wrap-docstrings breaks the description at the budget and hangs the continuation under the start of the text as the strip leaves it, one column narrower than the source, so both rules agree on where the continuation sits.
Related
For the budget semantics, the Docstring Budgets section of the Configuration chapter covers how the description and structured budgets interact.