Fix non-idempotent output with split_on_trailing_comma and a non-default wrap mode

[sarathfrancis90]

Summary

isort's output is not idempotent — isort(isort(x)) != isort(x) — when split_on_trailing_comma and include_trailing_comma are both enabled together with a non-default multi_line_output mode (e.g. GRID, VERTICAL, modes 0/1/4/5, or the Black profile with an explicit wrap-mode override). The first pass wraps the import using the requested mode and appends a trailing comma; only the second pass collapses it to VERTICAL_HANGING_INDENT. Running isort twice should always reach a fixpoint, so this is a stability bug.

Reproduction

import isort

src = "from a import b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w\n"
cfg = dict(multi_line_output=0, split_on_trailing_comma=True,
           include_trailing_comma=True, line_length=40)

first  = isort.code(src, **cfg)
second = isort.code(first, **cfg)
assert first == second   # fails on current main

The same instability reproduces for multi_line_output modes 0, 1, 4 and 5.

Root cause

In isort/output.py, the "explode onto individual lines" branch was only triggered when the input already carried a trailing comma (module in parsed.trailing_commas):

if (
    import_statement
    and config.split_on_trailing_comma
    and module in parsed.trailing_commas
    and not processed_as_imports_this_iteration
):

But when include_trailing_comma is set, isort itself adds a trailing comma to every import it wraps across multiple lines. So on the first pass the import is wrapped with the requested mode (no explode, because the source had no trailing comma yet) and gains a trailing comma; on the second pass that freshly-added comma now matches parsed.trailing_commas and the import is exploded — producing different output.

Fix

Treat an import as if it already carried a trailing comma when include_trailing_comma is enabled and the statement is going to be wrapped across multiple lines, so the explode happens on the first pass too and the output reaches a fixpoint regardless of the requested multi_line_output mode:

explode_on_trailing_comma = config.split_on_trailing_comma and (
    module in parsed.trailing_commas
    or (config.include_trailing_comma and do_multiline_reformat)
)

This is also consistent with the documented split_on_trailing_comma contract: an import that ends up with a trailing comma should be split onto separate lines.

Behavior impact

• No behavior change when split_on_trailing_comma is False.
• No behavior change for imports that fit on a single line (they are never wrapped, so do_multiline_reformat stays False).
• No imports are added or dropped.
• The output simply stabilizes on the first pass instead of the second.

Tests

• Added a regression test in tests/unit/test_regressions.py asserting idempotency for the affected configurations. It fails on main and passes with this change.
• Full unit suite: 572 passed, 1 skipped (the single unrelated test_importable failure reproduces identically on pristine main in this environment and is not touched by this change).
• ruff check, ruff format --check, and mypy are clean for the changed files.

Changelog

Added an entry under ### Unreleased in CHANGELOG.md.

[DanielNoord]

Could you remove this?

[DanielNoord]

Can you rebase your PR?

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.16%. Comparing base (87adfe4) to head (8dab19d).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2554   +/-   ##
=======================================
  Coverage   99.16%   99.16%           
=======================================
  Files          41       41           
  Lines        3097     3098    +1     
  Branches      670      670           
=======================================
+ Hits         3071     3072    +1     
  Misses         14       14           
  Partials       12       12           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sarathfrancis90]

Done — dropped the CHANGELOG entry and rebased onto main. The regression test now sits next to the new --sort-reexports one (that was the rebase conflict). Thanks for taking a look!

[DanielNoord]

Thanks!