Python Sequence Pattern

A sequence pattern is a structural pattern matching construct introduced in Python 3.10 that unpacks and matches a subject against a sequence of sub-patterns. It verifies that the subject is an instance of collections.abc.Sequence and that its elements satisfy the specified positional sub-patterns. Notably, sequence patterns explicitly exclude str, bytes, and bytearray objects to prevent unintended character-level or byte-level unpacking.

Syntax and Equivalence

Sequence patterns can be defined using either square brackets [] or parentheses (). At the compiler level, both syntaxes are evaluated identically; [a, b] and (a, b) represent the exact same pattern.

match subject:
    case [pattern_1, pattern_2]:
        # Matches a sequence of exactly length 2
    case (pattern_1, pattern_2, pattern_3):
        # Matches a sequence of exactly length 3

Length and Element Matching

By default, a sequence pattern enforces a strict length check. The subject sequence must contain the exact number of elements as the sub-patterns defined in the case clause. Each element in the subject is then evaluated against the corresponding sub-pattern from left to right.

match subject:
    case [1, x, 3]:
        # Matches a sequence of length 3 where index 0 is 1 and index 2 is 3.
        # The value at index 1 is bound to the variable 'x'.
    case [_, _]:
        # Matches any sequence of exactly length 2. 
        # The wildcard '_' discards the values.

Variable-Length Matching (Starred Expressions)

To match sequences of arbitrary lengths, sequence patterns support a single starred expression (*), similar to iterable unpacking. The starred name binds to a list containing all remaining elements that are not matched by the positional sub-patterns.

match subject:
    case [first, *middle, last]:
        # Matches a sequence of length >= 2.
        # Binds index 0 to 'first', the final index to 'last', 
        # and packs all intermediate elements into a list bound to 'middle'.
    case [*_, final_element]:
        # Matches a sequence of length >= 1.
        # Discards all elements except the last one, which is bound to 'final_element'.

Nested Sub-patterns

Sequence patterns are recursive. The sub-patterns within the sequence can be literal patterns, capture patterns, type patterns, or other structural patterns (including nested sequence or mapping patterns).

match subject:
    case [int(x), [str(y), z]]:
        # Matches a sequence of length 2 where:
        # 1. The first element is an integer (bound to 'x').
        # 2. The second element is a nested sequence of length 2.
        # 3. The first element of the nested sequence is a string (bound to 'y').
        # 4. The second element of the nested sequence is bound to 'z'.

Binding the Entire Sequence

The as pattern can be combined with a sequence pattern to capture the entire matched sequence object into a variable, while simultaneously unpacking its elements.

match subject:
    case [a, b, c] as full_sequence:
        # If the subject is a sequence of length 3, elements are bound to a, b, and c.
        # The original subject object itself is bound to 'full_sequence'.