align-colons
AlignmentPads the space before : so consecutive dict entries, annotated assignments, signature annotations, and docstring entries share one column, with a docstring entry's parenthesized type in a column of its own.
reflow-signatures
reflow-signatures writes every function signature in one of two forms, a one-line declaration or one parameter per line, the choice set by code-line-length and max-params. A mixed form (part on the def line, the rest indented underneath) forces the reader to track two layouts at once, so it is rewritten to one or the other.
The rule expands a signature where any of the following is true:
- Its inline form overflows the configured
code-line-length. - Its parameter count exceeds
max-params. - A parameter's own annotation or default spans rows.
Otherwise the signature collapses to a single line. A comment inside the parameter list keeps the existing layout, because moving the parameters would separate the comment from the line it describes. The expanded form puts each parameter on its own line, indented one step past the def, with the closing ) flush with the def, the return annotation trailing on the same line as the ), and the final parameter ending without a comma, the form strip-trailing-commas accepts. A parameter the author wrote across rows moves whole into the expanded form the way reflow-collections moves a member it keeps as written, and a *args or **kwargs annotation moves the same way. A call inside a parameter's annotation or default is reshaped where that parameter ends up, so a nested call is measured against its expanded row rather than the one-line signature it started on.
Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Turns the rule on or off. |
max-params | positive int | false | 4 | Explodes a signature to one parameter per line once its parameter count exceeds the cap. false turns the count trigger off and leaves only the code-line-length budget. |
The line-length budget comes from the top-level code-line-length key (default 88), which the rule reads directly. Setting max-params to false makes the rule expand on line length alone, so a signature that fits the budget stays inline whatever its parameter count.
The Canonical Case
render takes five parameters, width, height, depth, scale, and fast, which fit within code-line-length on one line. The signature expands to one parameter per line, because five exceeds the max-params limit of 4, and the count triggers the expansion however well the inline form would have fit.
def render(
width: int,
height: int,
depth: int,
scale: int,
fast: bool
):
return (width, height, depth, scale, fast)More Examples
render carries a @cache decorator and five parameters, one over max-params. The parameter list expands and the @cache line above def render is left untouched, because the rewrite replaces only the text between ( and ).
Renderer.render takes self plus four typed parameters, five in all, over max-params. It expands one parameter per line at the class-body indent, because the rule reads into class bodies the same way it reads top-level definitions, and each parameter line takes its indent from the method's own def rather than from the module margin.
configure takes two parameters, under max-params, and its inline width fits the line budget, but the opts default is a dict spanning rows. The signature expands one parameter per line anyway, because a signature with a multi-line default takes the expanded form, so a def and a call with a multi-line argument end up in the same form rather than two.
render's note default is a triple-quoted string whose line break falls inside the literal's own text. The three parameters expand one per line, and the string's second line stays at its source column rather than moving under note, because shifting it would pad the literal's own contents.
assemble_result takes four parameters whose inline header overflows code-line-length, and its return annotation is the three-line union PrimaryEnvelope | SecondaryEnvelope | DeferredEnvelope inside parentheses. The parameters expand one per line and the parentheses pass through intact, because they are what lets the type span several lines, and dropping them would leave output that does not parse.
render's only parameter, target: int, is written in the expanded form though it fits inline, with a -> int return annotation. The signature collapses to render(target: int) -> int:, with the return annotation trailing the closing ) on the same line rather than sitting on its own.
render takes three parameters, under the count limit, but its inline form runs past the default code-line-length of 88 columns. left_descriptor, palette_descriptor, and right_descriptor each move onto their own line, because line length triggers the expansion on its own.
_parse_file's inline row overflows the budget, and the only literal on it is the subscript in the Generator[ParsedLine, None, None] return annotation, which carries no bracket pair reflow-collections explodes. The signature expands its parameters one per line, because nothing else on the row can end the opening row early, so waiting on an expansion that never arrives would leave the row over the budget.
outer, an async def at module level, and inner, a plain def nested in its body, each take five parameters, over max-params. Both expand one parameter per line at their own indent, outer's parameters four spaces in and inner's eight, because the walker reads into outer's body to reach inner.
render's two parameters, palette and target, are written one per line even though their count is under max-params and the inline form fits code-line-length. The signature collapses back onto a single line, the same rewrite as expansion run in the other direction.
No Change
own_line_pin carries # comment between parameters on a line of its own, and trailing_line_pin carries # trailing on a parameter line after one parameter, both between ( and ), and both signatures take five parameters, over max-params. Both signatures are left exactly as written, because a comment in either placement keeps the existing layout, since moving the parameters would separate the comment from the line it describes.
No Change
already_inline takes two parameters, palette and target, which fit within both max-params and code-line-length, and already_expanded takes five, over max-params, written one per line. Neither signature is edited, because the inline form is the one the rule would write for the first and the one-per-line form is the one it would write for the second.
No Change
resolve's two parameters, payload and fallback, fit on one line, and its return annotation PrimaryEnvelope | SecondaryEnvelope | DeferredEnvelope spans three parenthesized lines. The parameters stay inline and the signature is left as written, because the rule measures the line budget up to the return annotation rather than across its full wrapped width.
function_nmtakes a single parameter whose default is a nestedouter_call_name(...)call, and the signature crosses the 66-column budget. reflow-signatures puts the parameter on its own line at an indent of four, and the call in its default explodes from that column rather than from the column it occupied in the source.reflow-calls leaves the parameters of a signature that is about to explode alone, so nothing measures them twice, and the inner
inner_call_nmcall is measured against the exploded row with the buffer align-equals writes aroundkeyword_name =counted in.composearrives exploded, one parameter per line, with a trailing,afterverbose: bool. strip-trailing-commas removes that comma and neither rule changes anything else, because the stripped form is the layout reflow-signatures writes itself.handler_map's return annotation crosses the 50-column budget, and the only collection literal on that row is the[Values, list[str]]list insideCallable. reflow-collections explodes that literal, and reflow-signatures keepsselfinline, because it reads the opening row as ending at the literal's bracket rather than exploding a lone parameter to recover width the explode is about to give back.storewritesttl : intwith a space before the:, and its one-line signature crosses the 40-column budget by exactly that space. strip-stranded-padding removes it, and reflow-signatures measures the signature at the width that removal leaves, so it stays on one line rather than exploding and joining back on a later pass.configuretakes five typed parameters on one line, two with defaults. reflow-signatures explodes the signature to one parameter per line, align-colons pads each name to one:column, and align-equals pads the=ofmangoanddeltainto one column, while the parameters keep their source order even with alphabetize-siblings in the run, because reordering parameters would change every positional call.