Improve SyntaxError message for inconsistent name binding in OR-patterns

Feature or enhancement

Proposal:

Title

compiler: improve SyntaxError message for inconsistent name binding in OR-patterns

Summary

When using structural pattern matching (PEP 634), all alternatives of an OR-pattern (|) are required to bind the same set of names.

Currently, if this rule is violated, CPython raises a SyntaxError with the message:

SyntaxError: alternative patterns bind different names

While technically correct, this message does not indicate which names differ or how the bindings are inconsistent.

This issue proposes enhancing the diagnostic to explicitly report the mismatched bindings.

Reproducer

match value:
    case 1 | x:
        pass

Output:

SyntaxError: alternative patterns bind different names

The message does not clarify:

• Which variable(s) are inconsistently bound
• Which alternative introduces additional bindings
• What the required constraint is

Expected Behavior

The error message should clearly indicate the binding mismatch. For example:

SyntaxError: OR-pattern alternatives must bind the same names;
left alternative binds no names, right alternative binds {'x'}

or:

SyntaxError: inconsistent variable binding in OR-pattern: 'x' is not bound in all alternatives

The exact wording can be adjusted, but the diagnostic should identify the differing name(s).

Rationale

PEP 634 specifies that all OR-pattern alternatives must bind identical sets of names.

Providing more detailed diagnostics would:

• Improve developer experience
• Make the rule easier to understand
• Align with recent improvements in CPython error reporting
• Maintain consistency with Python’s philosophy of helpful error messages

Scope

• No syntax changes
• No semantic changes
• No AST changes
• Diagnostic enhancement only

Implementation Notes

The relevant validation logic appears to occur during semantic analysis of pattern matching (likely in Python/ast.c or related compiler validation code).

The change would involve augmenting the existing name-set comparison logic to include information about the differing bindings in the raised SyntaxError.

Backward Compatibility

This change affects only the wording of an error message and does not alter runtime behavior.

Tests

Regression tests can be added to Lib/test/test_patma.py to assert that the improved diagnostic includes information about mismatched variable names.

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Linked PRs

• gh-145939

Start by reviewing linked PR #145939, then inspect the OR-pattern validation logic in Python/ast.c and related compiler code. Run the relevant pattern-matching tests in Lib/test/test_patma.py. Done means regression coverage verifies that inconsistent bindings identify the mismatched names without changing syntax or runtime behavior.