[`isort`] support for configurable import section heading comments by Alex-ley-scrub · Pull Request #23151 · astral-sh/ruff

Alex-ley-scrub · 2026-02-09T01:42:25Z

Summary

settings.rs - Added import_headings: FxHashMap<ImportSection, String> field to Settings struct with default and display support
options.rs - Added import_heading configuration option with #[option] metadata, documentation, and TOML table syntax. Added validation for unknown sections and mapping to Settings
mod.rs - Core logic in format_import_block:
- Collects all configured heading values as "# {heading}" strings
- Strips matching heading comments from ALL imports in each section (handles reordering)
- Inserts heading comments above each section after blank line logic
organize_imports.rs - Extended fix range backward to include heading comment lines above the first import, preventing duplication on fix application

Test Plan

Test Coverage (9 new tests, 156 total passing)

cargo test -p ruff_linter -- isort::tests
cargo test -p ruff_linter -- isort::tests::import_heading

Test	Scenario
import_heading.py	Basic unsorted imports get headings added
import_heading_already_present.py	Existing headings stripped and re-added correctly
import_heading_already_correct.py	Properly sorted+headed imports produce NO diagnostic
import_heading_unsorted.py	Completely unsorted imports get sorted with headings
import_heading_with_no_lines_before.py	Interaction with no_lines_before setting
import_heading_partial.py	Headings configured for only some sections
import_heading_wrong_heading.py	Non-matching comments preserved as regular comments
import_heading_single_section.py	Only one section present gets its heading
import_heading_force_sort_within_sections.py	Works with force_sort_within_sections

fixes astral-sh#6371

astral-sh-bot · 2026-02-09T15:06:10Z

`ruff-ecosystem` results

Linter (stable)

✅ ecosystem check detected no linter changes.

Linter (preview)

✅ ecosystem check detected no linter changes.

Alex-ley-scrub · 2026-02-09T19:45:23Z

thanks @ntBre for approving the tests to run. I've pushed an update now to fix the clippy warnings etc.
will have a look at the other failing tests as well

cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
cargo insta test --all-features --unreferenced reject --test-runner nextest
cargo nextest run --cargo-profile profiling --all-features
cargo nextest run --all-features --profile ci

ntBre · 2026-02-09T19:50:27Z

No problem! It looks like you just need to accept a few configuration snapshot changes and regenerate the JSON schema. I'll try to give this a review soon.

(I think the python_package check that just failed is probably unrelated)

...__rules__isort__tests__import_heading_already_present_import_heading_already_present.py.snap

crates/ruff_linter/src/rules/isort/mod.rs

…shot

amyreese

Why are the ty snapshots changing?

crates/ruff_linter/src/rules/isort/rules/organize_imports.rs

crates/ruff_linter/src/rules/isort/mod.rs

ntBre

Thank you! This looks good to me overall, I mostly had very minor comments. I think trying to use the Tokens and double-checking the duplicate heading handling are the most significant.

crates/ruff_linter/src/rules/isort/rules/organize_imports.rs

crates/ruff_linter/src/rules/isort/mod.rs

crates/ruff_workspace/src/options.rs

crates/ruff_linter/src/rules/isort/rules/organize_imports.rs

astral-sh#23151 (comment) Co-authored-by: Brent Westbrook <36778786+ntBre@users.noreply.github.com>

astral-sh#23151 (comment) Co-authored-by: Amethyst Reese <amethyst@n7.gg>

astral-sh#23151 (comment) Co-authored-by: Brent Westbrook <36778786+ntBre@users.noreply.github.com>

astral-sh#23151 (comment) (might need to add a & ref to make this compile, will check locally) Co-authored-by: Amethyst Reese <amethyst@n7.gg>

…ies field when running locally with `cargo dev generate-all`

…rties are not missing when we run `cargo dev generate-all`

crates/ruff_workspace/src/options.rs

…icate header comments see: astral-sh#23151 (comment)

…re properties are not missing when we run `cargo dev generate-all`" This reverts commit e3794e7.

crates/ruff_linter/src/rules/isort/mod.rs

ntBre

Thank you!

* main: (209 commits) [ty] Defer base inference for functional `type(...)` classes (#22792) flake8-executable: allow global flags in uv shebangs (EXE003) (#22582) [ty] Add `replace-imports-with-any` option (#23122) Update html comments in mdtests (#23269) Apply ruff formatting to mdtests (#22935) [ty] Exclude test-related symbols from non-first-party packages in auto-import completions [ty] Refactor `CursorTest` helper to support site-packages [ty] Qualify inlay hint edit symbol when possibly referencing another variable (#23265) [ty] Avoid `UnionBuilder` overhead when creating a new union from the filtered elements of an existing union (#22352) [ty] Refactor TypedDict key assignment validation (#23262) [ty] Improve Python environment path documentation (#23256) [ty] loop control flow analysis using loop header definitions Prepare for 0.15.1 (#23253) Remove docker-run-action (#23254) [ty] Allow discovering dependencies in system Python environments (#22994) Ensure pending suppression diagnostics are reported (#23242) [`isort`] support for configurable import section heading comments (#23151) [ty] Fix method calls on subclasses of `Any` (#23248) [ty] Fix bound method access on `None` (#23246) Make range suppression test snapshot actually useful (#23251) ...

Alex-ley-scrub added 2 commits February 9, 2026 00:28

test: add test cases for astral-sh#6371

0b1741d

fixes astral-sh#6371

feat(isort): implement import_heading option

9c642c3

fixes astral-sh#6371

Alex-ley-scrub mentioned this pull request Feb 9, 2026

Support heading setting for isort #6371

Closed

ntBre added isort Related to import sorting configuration Related to settings and configuration labels Feb 9, 2026

fix: clippy warnings

cb982e4

ntBre self-requested a review February 9, 2026 19:50

amyreese reviewed Feb 9, 2026

View reviewed changes

...__rules__isort__tests__import_heading_already_present_import_heading_already_present.py.snap Outdated Show resolved Hide resolved

crates/ruff_linter/src/rules/isort/mod.rs Outdated Show resolved Hide resolved

Alex-ley-scrub added 2 commits February 9, 2026 20:12

fix: run cargo dev generate-all

e9c5c31

fix: update snapshots

6ffebbf

Alex-ley-scrub requested review from BurntSushi, Gankra, MichaReiser, carljm, dcreager and sharkdp as code owners February 9, 2026 20:13

fix: address PR comment astral-sh#23151 (comment)

9b0167c

ntBre removed request for BurntSushi, Gankra, MichaReiser, carljm, dcreager and sharkdp February 9, 2026 20:25

Alex-ley-scrub added 2 commits February 9, 2026 20:35

fix: address PR comment astral-sh#23151 (comment)

fe12aa3

fix: update test to better match the name of the test and update snap…

e05212c

…shot

amyreese reviewed Feb 10, 2026

View reviewed changes

fix: address PR review comments astral-sh#23151 (review)

e433060

ntBre reviewed Feb 10, 2026

View reviewed changes

Alex-ley-scrub and others added 7 commits February 11, 2026 00:00

fix: adopt PR suggestion

b5140c9

astral-sh#23151 (comment) Co-authored-by: Brent Westbrook <36778786+ntBre@users.noreply.github.com>

fix: adopt PR suggestion

1e89052

astral-sh#23151 (comment) Co-authored-by: Amethyst Reese <amethyst@n7.gg>

fix: adopt PR suggestion

e18a752

astral-sh#23151 (comment) Co-authored-by: Brent Westbrook <36778786+ntBre@users.noreply.github.com>

fix: adopt PR suggestion

83400cc

astral-sh#23151 (comment) Co-authored-by: Brent Westbrook <36778786+ntBre@users.noreply.github.com>

fix: adopt PR suggestion

ca0f608

astral-sh#23151 (comment) Co-authored-by: Brent Westbrook <36778786+ntBre@users.noreply.github.com>

fix: adopt PR suggestion

9f79fb7

astral-sh#23151 (comment) (might need to add a & ref to make this compile, will check locally) Co-authored-by: Amethyst Reese <amethyst@n7.gg>

fix: clippy/compiler warnings/errors

ab3d745

lamkina mentioned this pull request Feb 11, 2026

Migrating Azure pipelines to GHA workflows scritical/.github#30

Merged

8 tasks

Alex-ley-scrub added 4 commits February 11, 2026 01:21

fix: rename snapshots

c35e536

fix: address some more PR feedback

9e52b33

fix: address some more PR feedback, and use better variable names again

1fb2633

fix: minor comment formatting

90e2229

Alex-ley-scrub requested review from amyreese and ntBre February 11, 2026 01:38

Alex-ley-scrub added 2 commits February 11, 2026 07:50

fix: manually update ruff.schema.json because was missing the propert…

5d4a504

…ies field when running locally with `cargo dev generate-all`

fix: add missing schemars(extend("properties" ...)) to ensure prope…

e3794e7

…rties are not missing when we run `cargo dev generate-all`

Alex-ley-scrub commented Feb 11, 2026

View reviewed changes

crates/ruff_workspace/src/options.rs Outdated Show resolved Hide resolved

Alex-ley-scrub and others added 4 commits February 11, 2026 16:44

fix: add test case to clarify isort vs ruff.isort behaviour with dupl…

3c1fbf0

…icate header comments see: astral-sh#23151 (comment)

Merge branch 'astral-sh:main' into feat/6371-isort-headings

4fc57e1

Revert "fix: add missing schemars(extend("properties" ...)) to ensu…

a3037c2

…re properties are not missing when we run `cargo dev generate-all`" This reverts commit e3794e7.

fix: update settings snapshot after updating branch with upstream

41dfd96

amyreese approved these changes Feb 12, 2026

View reviewed changes

crates/ruff_linter/src/rules/isort/mod.rs Show resolved Hide resolved

ntBre approved these changes Feb 12, 2026

View reviewed changes

amyreese changed the title ~~feat: #6371 isort headings~~ [isort] support for configurable import section heading comments Feb 12, 2026

amyreese merged commit d056a9f into astral-sh:main Feb 12, 2026
42 checks passed

BrewTestBot mentioned this pull request Feb 13, 2026

ruff 0.15.1 Homebrew/homebrew-core#267345

Merged

lamkina mentioned this pull request Feb 19, 2026

Add Ruff's new Isort section headers scritical/.github#34

Open

ntBre mentioned this pull request Feb 19, 2026

Ruff docs example's for [lint.isort] import-heading wrong. #23420

Open

Conversation

Alex-ley-scrub commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test Plan

Uh oh!

astral-sh-bot bot commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ruff-ecosystem results

Linter (stable)

Linter (preview)

Uh oh!

Alex-ley-scrub commented Feb 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ntBre commented Feb 9, 2026

Uh oh!

Uh oh!

Uh oh!

amyreese left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ntBre left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ntBre left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Alex-ley-scrub commented Feb 9, 2026 •

edited

Loading

astral-sh-bot bot commented Feb 9, 2026 •

edited

Loading

`ruff-ecosystem` results

Alex-ley-scrub commented Feb 9, 2026 •

edited

Loading