align-equals
AlignmentAligns the = separator across consecutive single-target assignments, annotated function-parameter defaults, and an exploded call's keyword arguments.
chain-layout
A dotted method chain packed onto one line reads as a single run of punctuation, and the eye has to parse the dots to find where one stage ends and the next begins. The same chain broken one link per line reads as a pipeline, each stage a row the reader takes in at a glance.
breaks a chain inside a parenthesis pair and hangs every link beneath the head's own dot, giving the chain one aligned column to scan down. The column is the alignment family's existing primitive reaching a new token, wherein builds from the operator and this builds from the..Two triggers open the break, the count trigger firing on a chain carrying more links than max-links, so a chain that fits the width still breaks once it carries enough stages to read as a pipeline. The length trigger fires on a chain whose joined single-line form crosses code-line-length from the column it lands at, which reaches a two-link chain the count cap leaves alone. A link is a .name(...) call, so a long dotted prefix ahead of a single call carries one link and stays where it sits, and a .name access that is not itself called shares the row of the link below it.
The head holds the receiver together with its first call, because a bare receiver alone on a line carries no information, and each link below it hangs at the receiver's own width past the head's indent. Where that width would shift the dot column further than max-shift allows, the chain falls back to the full split instead, standing the receiver alone on its line and running every link flush beneath it. The cap is the same max-shift the alignment rules read, so one knob governs how far any column may travel.
The break only ever opens a chain, never rejoining one, so a chain already hung across lines holds that shape even where its joined form would fit the budget. A count trigger opposed by a fit test would alternate forever, wherein the count breaks the chain and the fit test rejoins it on the pass after.
A chain sits inside a parenthesis pair rather than behind backslash continuations, reusing a pair the source already carries so a parenthesized chain gains no second one. The whole chain settles in the run that first opens it, every link placed against the indentation and width that run emits, leaving each link's own argument list to
and the collection inside it to , both of which read the columns this break produces. A chain spanning a comment holds its source shape, since relocating the links would carry the comment away from the row it annotates, and one whose links already span lines is left where it sits. A chain inside an f-string or t-string replacement field is opaque to layout whatever its width, because a line break spliced into a single-quoted field is PEP 701 syntax that parses on Python 3.12 and later and fails everywhere earlier, leaving an over-wide interpolation for to report.Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Toggles the rule on or off. |
max-links | positive int | false | 2 | Breaks a method chain to one link per line once its link count exceeds the cap. false disables the count trigger and leaves only the code-line-length budget. |
max-shift | positive int | 0 | false | 16 | The width a hung link's dot column may sit past the indent the broken chain opens at. A wider receiver takes the full split instead, standing alone with every link flush beneath it. 0 always takes that split, and false lifts the cap so every chain hangs. |
A three-link chain breaks at the default cap of 2 even where it fits the line. Setting max-links = false leaves code-line-length as the only trigger, and setting max-shift = 0 takes the full split for every chain.
The Canonical Case
A chain carrying more links than max-links breaks even where its single-line form fits the budget, because enough stages to read as a pipeline read better stacked. The head holds the receiver with its first call, and every link below it hangs beneath that head's own dot, giving the chain one aligned column to scan down.
result = (
query.filter(a)
.order(b)
.limit(c)
)More Examples
A chain naming where a value is written breaks the same way a chain a reader scans does, wrapping the whole target in the pair. Python accepts a parenthesized target and the output compiles, so the shape is pinned here rather than guarded, since suppressing it needs the walk to carry a target flag down through every nested shape.
The head sits one indent step past the row carrying the chain and the closing paren drops back to that row, measured from the row's own indent rather than from the column the chain happens to open at, so a chain bound to a keyword argument stacks against the statement instead of against the argument list.
The break replaces the chain rather than whatever the chain feeds, so a subscript applied to its result sits past the closing paren and reads as the one operation that happens after the pipeline settles.
A subscript ahead of the first call belongs to the receiver rather than to a link, so it sits on the head row and the links hang beneath the dot that follows it.
Hanging each dot beneath a receiver this wide would shift the column further than max-shift allows, so the chain takes the full split instead, standing the receiver alone on its line and running every link flush beneath it.
The length trigger is independent of the count, so a chain holding only two links still breaks once its single-line form crosses code-line-length from the column it lands at.
No Change
The rule only ever breaks, so a chain already hung across lines holds that shape even where its joined form would fit, because a count trigger opposed by a fit test would alternate forever.
No Change
Breaking a chain relocates every link, which would carry a comment away from the row it annotates, so a chain spanning one holds the shape the source gave it.
No Change
A chain at or under max-links whose single-line form fits the budget is left exactly as written, so the rule reaches a pipeline rather than every attribute call.