align-equals
AlignmentAligns the = separator across consecutive single-target assignments, annotated function-parameter defaults, and an exploded call's keyword arguments.
align-colons
The : separator appears across the contexts below, wherein columns of values sit beside columns of names and the reader's eye wants a tidy table rather than a ragged margin.
name: description entries of every Google-style docstring section (Args:, Returns:, Raises:, and the rest) all read as parallel two-column entries. Each aligned row keeps one space on each side of its :, and each docstring section resolves its own column so a wide Args: entry never shifts the Returns: table. Single-expression match arms live in a separate dispatch table owned by .The rule walks each context independently, treating a group as the consecutive members sharing the same indentation level and parent shape. A blank line, an own-line comment, or a non-member statement resets the group. Alignment honors the
so that one-member contexts skip padding altogether, leaving a one-key dict reading as plain code instead of a one-row table.Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Toggles the rule on or off. |
max-shift | positive int | 0 | false | 16 | The width-spread budget a contiguous run may shift to reach the shared column. A positive N caps the spread, 0 forbids any shift so every row sits flush, and false lifts the cap so a contiguous run folds into one column. To hold one row out of an otherwise-aligned group, mark it with # prose: skip. |
max-shift bounds how far a key may shift to align. The rule walks each group of : entries in source order and grows a column while its width spread stays within the cap, breaking a fresh column at the first key that would exceed it. A max-shift of false lifts the cap so a contiguous group folds into one column, and 0 forbids any shift so every : sits flush. The per-rule facets reference covers the full semantics.
The Canonical Case
A dictionary literal whose entries have differing key lengths aligns on the : separator, and the reader reads keys and values as separate columns.
capitals = {
"USA" : "Washington",
"France" : "Paris",
"Japan" : "Tokyo",
"Spain" : "Madrid",
}More Examples
Setting max-shift to false lifts the cap, so a contiguous run always aligns to its widest key. A spread the default would break folds into one column.
Setting max-shift to 0 forbids any shift, so every row stands alone and its : collapses flush against the key. Even equal-width neighbors stay flush rather than sharing a column.
The first three keys sit within max-shift of each other and align as one column. The trailing key overshoots the cap against them, so it breaks off with its : flush against the name.
A narrow field reading mid-run sits more than max-shift from the wide fields above it, so it breaks the run in reading order. The fields before it share one column and the fields from it onward share another.
Field widths climb in source order. The walk grows one column through the narrow rows that read first, then breaks when the next field clears max-shift of the group, gathering the wide tail into its own column.
Aligning the : column across a dict's entries also settles the run after each colon to one space, so a padded "a": 1 reads as "a" : 1 under the shared column. The value side no longer carries the stray padding a hand-aligned literal left behind.
An own-line comment between two entries closes the run and starts a fresh one, so the entries above and below the comment align on their own columns rather than one shared column. A trailing comment rides with its entry, whereas a standalone comment line breaks the run.
A run mixing commented and bare entries aligns to a single : column across the whole dict rather than splitting at the commented rows, because each comment attaches to its entry rather than to the alignment.
A dict whose entries each carry a trailing comment aligns its : separators on the shared column, with each comment left riding after its value. The comment is an annotation on the entry, so it never blocks the alignment.
The phrase Args: appears both in the docstring's body prose and as the real section header. Only the header triggers alignment, leaving the inline mention as-is while the named entries beneath the header align on one : column.
settles the
: across Args:, Returns:, and every other Google-style section, each section resolving its own column so a wide Args: entry never shifts the Returns: table beside it.Every annotated parameter on a multi-line signature settles its : onto a shared column at the widest name's width. The return-type : closing the signature line sits outside the parameter group and stays untouched.
A dict mixes string literals, an integer literal, and a bare name reference as keys. The math runs on each key's display width, so the : lines up identically regardless of the key expression's kind.
A run of line-adjacent annotated assignments settles its : onto a shared column at the widest name's width, the same way class fields and dict entries do. Each aligned row keeps one space before the colon and one after it, so a padded x: int reads as a row in the same table as yyyy : str.
A dict whose values are themselves dicts has each nested dict aligning its own : column at its own indent. The inner alignment is unaffected by the outer dict's key widths.
A dict mixes key: value entries with a **defaults unpacking. The unpacking carries no key expression, so it drops out of the alignment group while the keyed entries around it align on a shared : column.
No Change
A dict hand-aligned at its widest key, its key widths spanning exactly max-shift. The reading-order walk gathers the whole run into one group, so the hand-alignment round-trips unchanged and every : holds its column.