match statements and structural pattern matching

Understanding match statements and structural pattern matching

A match statement (Python 3.10 and later) evaluates one subject expression and then tries each case in written order until a pattern fits. The important difference from an elif chain is what a case contains: not a boolean expression, but a pattern describing the shape of the data. `case [x, y]` asks "is this a sequence of exactly two items?" and, if so, binds those items to x and y in a single step. That combination of test-and-unpack is the whole reason the feature exists.

Patterns compose recursively, so `case {'type': 'click', 'pos': (x, y)}` checks that the subject is a mapping, that it has a 'type' key equal to 'click', that it has a 'pos' key whose value is a two-element sequence, and only then binds x and y. Mapping patterns match a subset: extra keys are ignored, which suits event dictionaries and parsed JSON well. Sequence patterns match lists and tuples interchangeably and support one starred name, `*rest`, to absorb the remainder; strings and bytes are deliberately excluded so that 'abc' never matches `[a, b, c]`.

Two behaviours surprise people. First, a bare lowercase or uppercase name is a capture pattern: it always matches and rebinds that name, so `case LIMIT:` swallows every subject rather than comparing against the constant. Use a dotted name such as `Config.LIMIT` or an enum member, which is a value pattern compared with ==. Second, if no case matches, the whole statement is simply skipped with no error, so any variable you expected to be assigned stays unbound; add a final `case _:` when you want a guaranteed outcome.

def describe(event):
    match event:
        case {'type': 'click', 'pos': (x, y)}:
            return f'click at {x},{y}'
        case {'type': 'key', 'key': str() as k} if k.isdigit():
            return f'digit {k}'
        case {'type': 'key', 'key': k}:
            return f'key {k}'
        case [first, *rest]:
            return f'batch of {1 + len(rest)} starting with {first!r}'
        case _:
            return 'unknown'


for event in [
    {'type': 'click', 'pos': (3, 9)},
    {'type': 'key', 'key': '7'},
    {'type': 'key', 'key': 'esc'},
    ['a', 'b', 'c'],
    42,
]:
    print(describe(event))

Worked examples

from dataclasses import dataclass


@dataclass
class Point:
    x: int
    y: int


def where(p):
    match p:
        case Point(0, 0):
            return 'origin'
        case Point(x=0, y=y):
            return f'on y-axis at {y}'
        case Point(x, 0):
            return f'on x-axis at {x}'
        case Point():
            return 'somewhere else'


print(where(Point(0, 0)))
print(where(Point(0, 5)))
print(where(Point(-3, 0)))
print(where(Point(2, 2)))

RED = 'red'


class Color:
    RED = 'red'
    GREEN = 'green'


def loose(c):
    match c:
        case RED:
            return 'stop'
        case _:
            return 'other'


def strict(c):
    match c:
        case Color.RED:
            return 'stop'
        case _:
            return 'other'


print(loose('green'))
print(strict('green'))
print(strict('red'))

def run(cmd):
    match cmd.split():
        case ['quit' | 'exit']:
            return 'bye'
        case ['go', ('north' | 'south' | 'east' | 'west') as direction]:
            return f'walking {direction}'
        case ['take', *items] if items:
            return 'taking ' + ', '.join(items)
        case [verb, *_]:
            return f'I do not know how to {verb}'
        case []:
            return 'say something'


for line in ['exit', 'go north', 'take lamp key', 'dance a lot', '']:
    print(run(line))

Important notes

Common mistakes

Try it yourself