reflow-calls
LayoutExplodes a call to one keyword argument per line once its argument count passes max-args, its width passes code-line-length, or an argument spans rows, and rejoins a list broken anywhere else onto one row.
line-overflow
line-overflow reports each line still over its *-line-length cap once no layout rule can shorten it, so an unsatisfiable cap shows up as a finding in prose check and as a flagged line in the sandbox rather than as a setting that did nothing. The caps are hard limits that every layout rule fits within, so a call, collection, signature, or import that crosses its cap explodes to one entry per line, and an alignment run lays out an over-budget member first and aligns it within the cap after. When no legal layout meets the cap (a deep indent, a long identifier, a single-name import already at its narrowest, a cap set below what the statement needs), the narrowest layout stays and this rule names the line.
A line inside an import statement is measured against import-line-length and every other line against code-line-length. A line a layout rule could still split is left to that rule, so line-overflow reports only what no layout rule can shorten. The lines a layout rule can split include an inline call carrying arguments, a multi-element collection, a comma-joined import of either form, a signature carrying parameters, a single-statement match arm, an implicitly concatenated string run outside a docstring slot, and a line of docstring prose. No rule reaches a construct inside an f-string or t-string replacement field, so a line whose only splittable construct sits there is reported here as well. The lint never rewrites, so the diagnostic is reported and the source stays as written.
An overflow that sits inside one string literal with interior whitespace has a reshape even though no rule performs it, because the whitespace gives a legal place to break and adjacent literals inside parentheses join at compile time into the identical value. line-overflow carries that parenthesized form as a display-only suggestion, so prose check renders the layout and prose format never writes it. It stays a suggestion because the break points would become source, where a word inserted near the front reflows every line beneath it and the diff then claims the whole literal changed.
Two cases draw no suggestion, and their findings differ. A literal with no interior whitespace has nowhere legal to break, so a URL, a hash, or a dense regex keeps the report ending "with no legal reshape". A literal that would fit whole one indent below its line needs no break either, because the overflow came from the width ahead of it, so its report stays bare rather than claiming nothing could be done.
Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Turns the rule on or off. |
suggest-string-splits | bool | true | Suggests the parenthesized adjacent-literal form for an over-budget line whose overflow sits inside one string literal containing whitespace, as a display-only fix prose format never writes. false reports the overflow alone. |
suggest-string-splits gates the suggested form alone, not the report. With it off, an over-budget line whose literal could take a break is still reported, and the report omits the "with no legal reshape" ending, because a reshape exists there whether or not the finding spells it out.
The Canonical Case
BANNER's 54-column line overflows the 40-column budget inside one string literal whose interior spaces give a break somewhere legal to fall. The finding carries the parenthesized adjacent-literal form as a suggestion, and prose format never writes it, because Python joins the parts back into the identical value at compile time, whereas the chosen break points would become source a later edit has to reflow by hand.
BANNER = "the quick brown fox jumps over the lazy dog"More Examples
metrics.rolling.window.average.trailing and its = cross the 40-column budget on their own, so "a short tail" opens past the budget rather than straddling it. The finding is a bare report ending with no legal reshape, because no split of that literal can bring the line within the budget.
ENDPOINT's URL carries no interior whitespace, and its 52-column line overflows the 40-column budget. The finding is a bare report ending with no legal reshape, because no pair of adjacent literals can reproduce the value with a break between them, and the same is true of a hash or a dense regex, where the message means exactly what it says.
BANNER's string carries a \t and the escaped quotes around \"lazy\", and its 77-column line overflows the 40-column budget. The suggested split cuts the string only after a run of literal whitespace, between over and the, so each escape travels whole inside one part, because a backslash sits flush against the character it escapes with no whitespace between them for a cut to fall on.
metrics.rolling.window.average = previous_value is 47 columns, over the 40-column code-line-length, and carries no call, collection, import, or signature a layout rule could split. The line is reported with with no legal reshape, because no legal form brings it within the budget, so an unsatisfiable budget becomes a finding rather than a setting that silently did nothing.
PATTERN's literal carries an r prefix and single quotes, and its 56-column line overflows the 40-column budget. Each part of the suggested split opens with r' and closes with ', because the split copies each part's opener and closer from the source rather than rebuilding them from the quote style, which would drop the r and change what the pattern's backslashes mean.
BANNER's 54-column line overflows the 40-column budget, with suggest-string-splits = false set for the rule. The finding carries no suggested split, only the report naming the line and its budget, and the message still omits with no legal reshape, because the split of this string exists whether or not the finding spells it out.
Related
For per-line opt-outs, the Suppression chapter covers the # prose: ignore[line-overflow] directive. The Lengths section of the configuration reference states the hard-limit contract on the caps that this rule completes.