align-imports
AlignmentAligns the import and as keywords across consecutive import statements.
import-layout
Prose holds code to a line-length budget but leaves imports exempt by default, so a from a.deeply.nested.module import x, y, z, ... runs past the margin however wide its roster grows.
from ... import ... statements. Each statement repeats the module prefix and greedily packs as many alphabetized names as fit before the next line opens, so the imported names begin at the column the eye reaches after import on every line and a deep module path never drives them rightward.Further shape questions sit below that width split, each a facet rather than a rule of its own, because they all answer the same question about what one import line holds. split-multi-module breaks a comma-joined import a, b into one import statement per module, the form pycodestyle flags as E401, since those commas separate distinct modules and nothing binds them to one line. merge-members runs the other direction on from-imports, gathering every from pkg import ... statement of one module in an import run onto a single line carrying each member once, so the module appears once with its roster behind it. A from pkg import a, b line is never broken at its commas, because those separate members of one module rather than modules.
The rule runs ahead of
and , so each module it puts on its own line reaches its canonical group and slot in the same pass, and the gathered roster lands in the order would leave it. Settingalphabetize = false holds the authored member order across both moves.The rule acts on single-line imports that open their own line. A from ... import *, a from-import already within budget, a ;-joined statement, and a parenthesized multi-line import stay untouched, and a lone name whose own line still overflows keeps its place rather than splitting further. A backslash-continued import arrives here already rejoined, since
import keyword across the resulting run, which already carries one identical prefix per line.Configuration
| Key | Type | Default | Meaning |
|---|---|---|---|
enabled | bool | true | Toggles the rule on or off. |
merge-members | bool | true | Folds repeated from <module> import … statements into one statement carrying each member once, ordered as would leave it. false leaves each statement on its own line. |
split-multi-module | bool | true | Breaks a comma-joined import a, b into one import statement per module. false keeps the comma-joined form. |
Each shape move sits behind its own facet, so a project can switch one off without disturbing the others. split-multi-module governs the comma-joined break and merge-members the same-module gather, both defaulting on, and the width split runs regardless of either.
The wrap budget comes from the top-level import-line-length key (default 120), governing the import wrap independently of code-line-length. An import is a roster
import-line-length to false drops the dedicated budget, so the import wrap falls back to code-line-length.The Canonical Case
A from ... import ... whose names overrun import-line-length splits into a run of repeated-prefix statements, each greedily packing the alphabetized names up to the budget before the next line opens.
from pkg.sub import alpha, beta, delta
from pkg.sub import epsilon, gammaMore Examples
split-multi-module breaks import a, b into one import statement per module, the shape
The merge and the width split settle together, so three statements gather into one roster that then repacks to the budget rather than emerging as a single over-long line.
A relative import folds its leading dots into the repeated prefix, so every split line opens with the same from ..pkg import anchor.
An as-aliased name keeps its alias when the line splits, so each packed statement repeats the module prefix and holds every name as alias pair intact.
A from-import nested in a block splits with every continuation line carrying the block indent, and the budget counts the indent column so each packed line still fits.
A comma-joined import whose modules carry aliases splits with each as clause on its own module's statement, leaving
The merge reaches every statement of one module across the whole import run, so a sibling module standing between two from pkg import ... lines does not keep them apart.
Clearing one facet leaves the others running, so the two from pkg statements stay apart while split-multi-module still breaks import os, sys into one statement per module.
merge-members folds two from pkg import ... statements into one line carrying both members, so the module appears once with its roster behind it, ordered as
Clearing one facet leaves the others running, so import os, sys stays exactly as written while merge-members still gathers the two from pkg statements onto one line.
No Change
A comment describes the statement it sits beside, and folding two statements into one leaves it describing nothing, so a commented member keeps every statement of its module in place.
No Change
The gather clears each folded member's whole line, so a comment trailing the last of them keeps every statement of its module in place rather than going down with the line it sits on.
No Change
A single name whose own from ... import ... line still overruns the budget stays in place rather than splitting further, since one name has nowhere left to break.
No Change
A from ... import * carries one name and passes through unchanged, even past the budget, because a star import has nothing to pack.
No Change
A from ... import ... that already fits the import budget keeps its single line, leaving the split for the genuinely long rosters.