[RFC][formatter] Prefer vertical alignment of arguments

[XuehaiPan]

Summary

As per #24572 (comment), propose removing the compact multi-line layout (Layout 2) where the formatter packs all arguments on a single indented line. Expressions would go directly from single-line (Layout 1) to one-per-line with trailing comma (Layout 3).

If adopted as the default, this also resolves the long-standing COM812 formatter incompatibility (#9216).

• How to use COM812 in linter but avoid conflict with formatter? #9216

Current formatter behavior

The formatter produces three layouts for comma-separated content:

# Layout 1: single line (fits within line width)
result = func(a, b, c)

# Layout 2: compact multi-line (all args on one indented line, no trailing comma)
result = func(
    a, b, c, d, e, f, g, h
)

# Layout 3: one-per-line (with trailing comma)
result = func(
    a,
    b,
    c,
    d,
    e,
    f,
    g,
    h,
)

This proposal removes Layout 2. Expressions that don't fit on a single line would always use Layout 3.

---

Motivation

1. Readability

Layout 2 can be misleading at a glance — it's ambiguous whether the expression takes one argument or many:

# Layout 2 — at a glance, this looks like a single argument
result = func(
    this_function_actually(takes, two), parameters
)

# Layout 3 — structure is immediately clear
result = func(
    this_function_actually(takes, two),
    parameters,
)

This was raised independently by multiple users:

• How to use COM812 in linter but avoid conflict with formatter? #9216 (comment)
• How to use COM812 in linter but avoid conflict with formatter? #9216 (comment)
• How to use COM812 in linter but avoid conflict with formatter? #9216 (comment)
• [formatter] Add magic-trailing-comma option with normalize mode to make formatter COM-safe #24572 (comment)

2. COM812 compatibility

The formatter and COM812 currently conflict because Layout 2 has no trailing comma:

# Formatter produces Layout 2
def args(
    aaaaaaaa, bbbbbbbbb, cccccccccc, ddddddddd, eeeeeeee, ffffff, gggggggggggg, hhhh
):
    pass

COM812 flags this (newline before ) without trailing comma), adds a comma, and the formatter re-expands to Layout 3 — requiring multiple ruff format → ruff check --fix → ruff format passes to converge. Users must disable COM812 entirely to avoid this.

Without Layout 2, the formatter would always produce Layout 3 (with trailing comma) for expressions that don't fit on a single line. COM812 and the formatter would converge in a single ruff format pass.

3. Diff-friendliness

Layout 2 lacks a trailing comma, which means adding or removing an argument always touches the existing last line:

 # Layout 2 — no trailing comma, 2 lines changed to add an argument
 result = some_function(
-    first_argument, second_argument, third_argument, fourth_argument
+    first_argument, second_argument, third_argument, fourth_argument, fifth_argument
 )

Layout 3 with trailing comma keeps diffs minimal — only the new line is added:

 # Layout 3 with trailing comma — 1 line added
 result = some_function(
     first_argument,
     second_argument,
     third_argument,
     fourth_argument,
+    fifth_argument,
 )

This is the core purpose of COM812 — reducing diff noise when parameters change. Layout 2 directly undermines this goal.

4. pre-commit and CI usability

pre-commit expects each hook to be idempotent in a single pass. The current ruff format + COM812 combination fundamentally requires multiple passes:

1. ruff format produces Layout 2 (no trailing comma)
2. ruff check --fix adds trailing comma (COM812)
3. ruff format re-expands to Layout 3 (trailing comma forces one-per-line)

This means pre-commit hooks always report changes on the first run, even when the final state is identical to the original. Users resort to multi-pass workarounds:

# Workaround: run format → check → format in a loop
- repo: local
  hooks:
    - id: ruff
      entry: bash -c '
        ruff format "$@";
        for i in 1 2 3; do
          ruff check --fix "$@";
          ruff format "$@";
        done;
        ruff check "$@" && ruff format --check "$@"
        ' --
      types: [python]

The multi-pass workaround also introduces potential bugs: each intermediate write to disk can trigger file watchers, invalidate caches, and cause stale reads in AI coding agents and IDE language servers that monitor file changes. When running pre-commit run --all-files, the loop touches every Python file in the repo multiple times even when the final state is identical to the original.

Without Layout 2, ruff format alone produces COM-compliant output. A single ruff format pass is sufficient — no ruff check --fix needed, no loops, no workarounds:

# Clean: single-pass hooks
- repo: https://github.com/astral-sh/ruff-pre-commit
  hooks:
    - id: ruff-check
      args: [--fix, --exit-non-zero-on-fix]
    - id: ruff-format
      args: [--exit-non-zero-on-format]

5. AI-generated code

AI coding agents frequently produce over-wrapped expressions. With Layout 2, the formatter can't normalize these to a consistent style in one pass — the trailing comma presence or absence changes the output:

# AI-generated (trailing comma prevents collapsing in "respect" mode)
result = func(
    arg1,
    arg2,
)

# Formatter can't collapse this to `func(arg1, arg2)` because the
# trailing comma signals "keep expanded"

Without Layout 2, the formatter's behavior becomes more deterministic — expressions either fit on one line (Layout 1) or expand to one-per-line (Layout 3).

6. Consistency with other constructs

Lists, dicts, sets, and imports already go directly from Layout 1 to Layout 3 — they don't have a Layout 2 intermediate form. Only function calls, function definitions, pattern arguments, and subscript tuples use the compact layout (via an inner group() wrapper). Removing it would make all comma-separated constructs behave consistently.

---

Affected constructs

Layout 2 currently applies to:

• Function call arguments
• Function definition parameters
• Match pattern arguments
• Subscript tuples (e.g., matrix[a, b, c])

Lists, dicts, sets, imports, type parameters, with statements, and other comma-separated constructs already go directly from Layout 1 to Layout 3.

---

Possible solutions

Four magic-trailing-comma modes and their behavior:

Behavior	"respect"	"ignore"	"force"	"normalize"
Trailing comma as expansion signal	Yes	No	Yes	No
Add comma to hanging multi-line	If formats to one-per-line	If formats to one-per-line	Always	If doesn't fit in single-line
Add comma to one-per-line	If formats to one-per-line	If formats to one-per-line	Always	If doesn't fit in single-line
Remove comma from single-line	No (expands to one-per-line)	If fits in single-line	No (expands to one-per-line)	If fits in single-line
Remove comma from one-per-line	No	If formats to single-line or hanging multi-line	No	If fits in single-line
Remove Layout 2	No	No	Yes (consequence of adding comma)	Yes (explicit style spec)
COM812 safe	No	No	Yes	Yes
Status	Current default	skip-magic-trailing-comma = true	New (#24609)	New (#24572)

All four modes on the compact multi-line case:

# Input — Layout 2
result = some_function(
    first_argument_name, second_argument_name, third_argument_name, fourth_argument_name
)

# respect — stays Layout 2 (no trailing comma signal)
result = some_function(
    first_argument_name, second_argument_name, third_argument_name, fourth_argument_name
)

# ignore — stays Layout 2
result = some_function(
    first_argument_name, second_argument_name, third_argument_name, fourth_argument_name
)

# force — Layout 3 (trailing comma added → one-per-line)
result = some_function(
    first_argument_name,
    second_argument_name,
    third_argument_name,
    fourth_argument_name,
)

# normalize — Layout 3 (same result for this case)
result = some_function(
    first_argument_name,
    second_argument_name,
    third_argument_name,
    fourth_argument_name,
)

All four modes on over-wrapped short expressions with trailing comma:

# Input — AI-generated, fits on one line
result = func(
    arg1,
    arg2,
)

# respect — stays expanded (trailing comma is "magic")
result = func(
    arg1,
    arg2,
)

# ignore — collapses (trailing comma ignored)
result = func(arg1, arg2)

# force — stays expanded (trailing comma is still "magic")
result = func(
    arg1,
    arg2,
)

# normalize — collapses (trailing comma ignored + comma removed)
result = func(arg1, arg2)

"force" and "normalize" both resolve the COM812 conflict but differ on trailing comma semantics:

• "force" respects existing trailing commas — the user's intent to keep expressions expanded is preserved
• "normalize" ignores existing trailing commas — the formatter fully owns layout decisions based on line width

Either could be gated behind preview, edition = "next", or made the default. They are also compatible with removing Layout 2 globally — if Layout 2 is removed for everyone, "force" becomes equivalent to "respect" and "normalize" becomes equivalent to "ignore" for the layout, with trailing comma addition as the only remaining difference.

---

Open questions

Per #24572 (comment):

1. Style: Is removing Layout 2 (always using Layout 3 for multi-line) a formatting style we want to support?
2. Default: Should this become the default, and if so, how do we get there?
   • Direct change (breaking — reformats all existing code)
   • preview flag (opt-in, may stabilize later)
   • edition = "next" (opt-in, stable within the edition, requires designing the edition mechanism)
3. Configurability: If it shouldn't become the default, how should it be configurable? And should the config live in [format] or [lint.flake8-commas]?
   • format.magic-trailing-comma = "force" ([formatter] Add magic-trailing-comma option with force mode to make formatter COM-safe #24609) — formatter owns trailing comma behavior, single-pass convergence
   • A lint.flake8-commas option — linter-side, but requires ruff check --fix after ruff format (two passes)
   • A separate layout option decoupled from trailing comma handling
   • No option — wait for edition = "next"
4. Black compatibility: Layout 2 matches Black's line-wrapping behavior. Removing it is a deliberate deviation. Is this acceptable?
5. Ecosystem impact: How much code would be reformatted? [WIP] Prefer vertical alignment of arguments #23083 may have ecosystem data from its exploration.
6. Scope: Should this apply to all four affected constructs (calls, defs, patterns, subscripts) equally, or should some keep Layout 2?
7. Relationship to COM812: If Layout 2 is removed globally, should the COM812 incompatibility warning be removed? Should COM812 itself be reconsidered (since the formatter would handle trailing commas)?

Prior work

• [WIP] Prefer vertical alignment of arguments #23083 — previous exploration of removing the compact layout
• How to use COM812 in linter but avoid conflict with formatter? #9216 — COM812 formatter incompatibility
  • How to use COM812 in linter but avoid conflict with formatter? #9216 (comment) — original "force" suggestion
  • How to use COM812 in linter but avoid conflict with formatter? #9216 (comment) — approved approach: config option or new rule
  • How to use COM812 in linter but avoid conflict with formatter? #9216 (comment) — implement the config option or split the rule
  • How to use COM812 in linter but avoid conflict with formatter? #9216 (comment) — AI agents + pre-commit convergence motivation
• [formatter] Add magic-trailing-comma option with normalize mode to make formatter COM-safe #24572 — "normalize" mode (postponed)
  • [formatter] Add magic-trailing-comma option with normalize mode to make formatter COM-safe #24572 (comment) — layout changes should not be coupled with trailing comma behavior
  • [formatter] Add magic-trailing-comma option with normalize mode to make formatter COM-safe #24572 (comment) — consider removing compact layout globally or via edition = "next"
  • [formatter] Add magic-trailing-comma option with normalize mode to make formatter COM-safe #24572 (comment) — open a new issue to discuss the style change
• [formatter] Add magic-trailing-comma option with force mode to make formatter COM-safe #24609 — "force" mode (preview feature)

cc @MichaReiser @dylwil3 @charliermarsh

[ashrub-holvi]

That's what I always had in mind, thank you for creating detailed issue! Of course one may say that even layout 1 shouldn't exists for always have same style and never see reformatting diffs, but I can understand that same people may disagree.

[MichaReiser]

Can you say more why we can't always add the trailing comma if a single argument call is too long and expands too:

result = func(
    this_function_actually(takes, two),
)

This seems to be the main difference between the new proposed options.

I also think this line is incorrect for ignore:

Remove comma from one-per-line

When using ignore, Ruff ignores the trailing comma and removes it if the call expression now fits on a single line.

[XuehaiPan]

Can you say more why we can't always add the trailing comma if a single argument call is too long and expands too:

result = func(
    this_function_actually(takes, two),
)

This seems to be the main difference between the new proposed options.

@MichaReiser We can — and in fact the formatter already does this for Layout 3.

So the issue reduces to a single change: remove Layout 2. Once every multi-line expression uses Layout 3, trailing commas are added automatically, and the formatter becomes COM812-safe. No new option needed — the existing format.skip-magic-trailing-comma boolean already covers both behaviors.

The current behavior of `respect`/`ignore`

respect and ignore produce identical one-per-line output (both with trailing comma). The only difference is whether existing trailing commas prevent collapsing:

# Input
result1 = func1(
    short_arg1,
    short_arg2,
)
result2 = func2(
    very_long_argument_name_one,
    very_long_argument_name_two,
    very_long_argument_name_three,
)

# respect — result1 stays expanded (trailing comma is "magic"); result2 unchanged
result1 = func1(
    short_arg1,
    short_arg2,
)
result2 = func2(
    very_long_argument_name_one,
    very_long_argument_name_two,
    very_long_argument_name_three,
)

# ignore — result1 collapses (trailing comma not a signal); result2 identical
result1 = func1(short_arg1, short_arg2)
result2 = func2(
    very_long_argument_name_one,
    very_long_argument_name_two,
    very_long_argument_name_three,
)

If we remove Layout 2 and always add trailing commas to hanging multi-line, the existing format.skip-magic-trailing-comma boolean already covers both behaviors:

• skip-magic-trailing-comma = false → respect (trailing comma prevents collapsing)
• skip-magic-trailing-comma = true → ignore (trailing comma doesn't prevent collapsing)

No new option is needed — the force / normalize distinction only matters if Layout 2 is kept as the default and offered as an opt-in removal.

---

I also think this line is incorrect for ignore:

Remove comma from one-per-line

When using ignore, Ruff ignores the trailing comma and removes it if the call expression now fits on a single line.

You're right — I verified that ignore does NOT remove trailing commas from one-per-line output. I have fixed the table in the issue.

The full behavior of the current `ignore`

# Input — one-per-line with trailing comma
result = func(
    arg1,
    arg2,
    arg3,
)

ignore reformats based on whether it fits:

a. Fits on one line → Layout 1 (trailing comma removed):

result = func(arg1, arg2, arg3)

b. Doesn't fit on one line but args fit on one indented line → Layout 2 (trailing comma removed):

result = func(
    arg1, arg2, arg3, long_arg4, long_arg5
)

c. Doesn't fit in Layout 1 or 2 → Layout 3 with trailing comma:

result = func(
    arg1,
    arg2,
    arg3,
    long_arg4,
    long_arg5,
    long_arg6,
)

So ignore only removes trailing commas in cases (a) and (b). In case (c), the trailing comma is re-emitted by the formatter.

[MichaReiser]

@XuehaiPan can you please try to write concise messages and in your own words (see our AI policy).

[WhyNotHugo]

Can you say more why we can't always add the trailing comma if a single argument call is too long and expands too:

result = func(
this_function_actually(takes, two),
)

I want the formatter to "just work", without having to find places where it's skipped it's job and without needing to sparkle "magic" to trigger it. The current flow is:

• Run ruff format
• Review which parts it didn't format due to missing magic
• Insert magic
• Run ruff format again

Also, because of the magic comma, the following is not re-formatted either:

exceptions = list(
    only_one_arg_left,
)

In order for it to be formatted back into one line, one must remove the command and run the ruff format again.

Having to hunt down each location and add/remove magic is tedious, I want the formatter to just auto-format the whole code without micromanagement.

[MichaReiser]

In order for it to be formatted back into one line, one must remove the command and run the ruff format again.

This should not be the case when using skip-magic-trailing-comma=true

[ashrub-holvi]

that even layout 1 shouldn't exists for always have same style (Layout 3) for never see reformatting diffs

another option - if there a type hints always use Layout 3, even if line is short

[XuehaiPan]

that even layout 1 shouldn't exists for always have same style (Layout 3) for never see reformatting diffs

another option - if there a type hints always use Layout 3, even if line is short

One drawback for Layout 3 is that currently most of the coding agents use grep without context lines. Collapsing short argument lists back to a single line makes agents happy to reduce interaction turns.

[ashrub-holvi]

currently most of

Maybe, don't know is it real issue, but even if it is, I would prefer consistent and diff-friendly auto-formatting. IMO, humans first, tools will be adjusted if needed.