Python Group Pattern

A group pattern in Python’s structural pattern matching consists of a single sub-pattern enclosed in parentheses. It is used to explicitly define evaluation precedence within complex patterns, without altering the matching semantics of the enclosed sub-pattern itself. A group pattern (P) succeeds if and only if the sub-pattern P succeeds. It does not enforce any type checking or structural constraints on the subject beyond what P already dictates.

Syntax

( <pattern> )

Mechanics and Precedence

The primary function of a group pattern is to explicitly control the parsing associativity of pattern operators, particularly the OR pattern (|) and the AS pattern (as). According to Python’s pattern matching grammar, the as operator binds less tightly than the | operator. Consequently, an as pattern cannot be directly embedded as an alternative inside an OR pattern. Group patterns are grammatically required to isolate the as binding to individual alternatives.

match subject:
    # Default precedence: The 'as' operator binds to the result of the entire OR pattern.
    case str() | int() as x:
        pass
        
    # Group patterns override precedence: The 'as' operator binds to each 
    # alternative individually before the OR pattern is evaluated.
    case (str() as x) | (int() as x):
        pass

Disambiguation from Sequence Patterns

A critical technical distinction in Python’s pattern matching grammar is the difference between a group pattern and a sequence pattern (which matches tuples). Parentheses alone do not denote a tuple in pattern matching; the presence of a comma dictates the sequence.

(P): Group pattern. Matches whatever P matches.
(P,): Sequence pattern. Matches a sequence (like a tuple or list) containing exactly one element that matches P.
(): Sequence pattern. Matches an empty sequence.

match subject:
    case (int()):
        # GROUP PATTERN
        # Matches the integer 42. Does NOT match the tuple (42,).
        pass
        
    case (int(),):
        # SEQUENCE PATTERN
        # Matches the tuple (42,). Does NOT match the integer 42.
        pass

Variable Binding Constraints

Group patterns can be nested arbitrarily deep. However, when using group patterns to encapsulate alternatives within an OR pattern (|), Python’s compiler strictly enforces that all alternatives bind the exact same set of variables. Failing to bind the identical variable names across all branches of an OR pattern results in a compile-time SyntaxError. This prevents runtime scenarios where a variable might be unexpectedly unbound in the case block.

match subject:
    # VALID: Both grouped alternatives bind the exact same variable name ('x').
    case (str() as x) | (int() as x):
        pass
        
    # INVALID: Raises SyntaxError: alternative patterns bind different names.
    # The left group binds 's', while the right group binds 'i'.
    # case (str() as s) | (int() as i):
    #     pass