Skip to content
Ordering№ 13reflow-importsspace-statements

group-imports ​

group-imports moves each import in a contiguous into its canonical section, a from __future__ import ahead of everything, then the bare import statements, the external from … import … statements, and the local-package imports last:

SectionMembers
__future__from __future__ import annotations
Bareimport os, import numpy as np
External fromfrom collections import Counter
Local-packagerelative imports and any package on the first-party list

The rule moves imports into their sections and leaves the order within each to alphabetize-siblings, so the two agree on the grouping through one shared classifier. A run already in section order passes through with no edit. Under a class header carrying # prose: keep, the imports in the class body stay as written along with its other statements, whereas the imports inside one of its methods still , since a method body is a of its own.

An absolute from __future__ import … takes the leading section on its own, because Python rejects a module that places the statement below any other code, so the section is a compiler requirement rather than a legibility preference. A relative from .__future__ import … and a bare import __future__ name ordinary modules and classify as any other import does.

A from import is local when it is relative (from . import x,from ..pkg import y) or its module's root package appears on the first-party list under [imports]. A bare import is local when the root package of any name it binds is first-party. Every other bare import stays bare, every other from import is external, and a statement that is no import at all stays where it sits and ends the run.

A section marker divides a run into sections, so an author who grouped imports under a divider keeps that grouping and no import crosses the marker into the section above it. space-statements writes the single between one canonical section and the next, reflow-imports runs afterward and splits a comma-joined statement so each module sits on its own line in its section, and align-imports reads the grouped result and aligns the import keyword within each section.

Configuration ​

KeyTypeDefaultMeaning
enabledbooltrueTurns the rule on or off.

Turned off, the rule leaves the imports as one flat block, which alphabetize-siblings sorts together rather than within sections.

The Canonical Case ​

A scrambled mixes bare, external from, and local imports, with myapp named in first-party. group-imports partitions the run into bare, external from, and local sections in that order, so import sys and import os lead, from typing import Any and from collections import Counter follow, and from myapp import app and from . import shared close the run.

Within a section the statements keep their source order, so sys stays ahead of os, because sorting belongs to alphabetize-siblings and the between sections to space-statements.

prose.toml
toml
[imports]
first-party = [ "myapp" ]
import sys
import os
from typing import Any
from collections import Counter
from myapp import app
from . import shared
python

More Examples ​

Kept and Grouped each import from collections import abc above import sys, and only Kept carries # prose: keep on its header. group-imports moves import sys above the from import in Grouped and leaves Kept as written, because the marker holds every statement of the class body against each rule that reorders one. The imports inside the if TYPE_CHECKING: arm of Kept keep their order too, since an if opens no , whereas the imports inside load still , because a method body is a scope of its own.

The # --- Local --- comment sits between import sys and from . import shared. Each side of the partitions on its own and no import crosses it, so import sys moves above from collections import Counter in the upper section, and import os moves above from . import shared in the lower one rather than joining import sys.

import sys closes its line with # prose: skip inside a of five imports. import sys stays put and the imports below it on their own, import re moving above from pkg import alpha, whereas from pkg import beta above it stays first, because a skipped import holds its line and the regrouping of the imports on either side leaves it untouched.

Under if TYPE_CHECKING:, from collections import abc sits above import sys. group-imports moves the bare import sys above the from import in place, both lines keeping the arm's indent, because the rule reads the body of a compound statement the same way it reads the module.

The body of load opens with from collections import Counter above import sys. group-imports moves the bare import sys above the from import in place, both lines keeping the function-body indent, because the rule reads every nested body the same way it reads the module.

With myapp named in first-party, the already reads bare imports, then the external from collections import Counter, then the first-party from myapp import app. group-imports emits no edit, because every statement already sits in its section and the rule rewrites only when a statement has to move.

prose.toml
toml
[imports]
first-party = [ "myapp" ]
  1. import sys, os and import myapp.core, abc each name two modules in one statement, with myapp in first-party. reflow-imports splits each into one module per line ahead of group-imports and alphabetize-siblings, so every split-off module reaches its own and its sorted position, and myapp.core ends up in the local section rather than beside the stdlib abc it was joined to.

  2. Bare, external from, and local imports sit scrambled together, with myapp named in first-party. group-imports partitions them into bare, external, and local sections, alphabetize-siblings sorts the names within each section, space-statements writes one between sections, and align-imports pads the import keyword into a within each section.

Ordering

alphabetize-siblings

Sorts sibling entries whose order carries no meaning, covering import names, dict keys, class-body members, keyword arguments, and docstring entries.

Alignment

align-imports

Pads the space before the import keyword across consecutive from imports, or before as across consecutive aliased imports, so the keywords share one column.

Layout

reflow-imports

Splits a from … import … that overflows import-line-length into repeated-prefix statements, breaks a comma-joined import a, b into one statement per module, and merges repeated from statements of one module into one line.

Formatting

space-statements

Sets the blank-line count between module-level definitions, class members, import groups, and the __main__ guard to PEP 8's canonical values.

Lint

bare-imports

Reports an unaliased bare import reached through at most max-attributes distinct attributes, which a from x import … would replace.

0.11.0Versione83e7e6Commit43Rules1830Fixtures2026-11-19Updated