Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt

Use this file to discover all available pages before exploring further.

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
Master Python with Deep Grasping Methodology!Learn More