How Does match-case Work in Python?

The match statement in Python 3.10 performs structural pattern matching. Each case offers one or more patterns, and the first pattern that matches the subject is the one that wins.

def describe(command):
    match command:
        case 'start':
            return 'starting'
        case 'stop' | 'quit':
            return 'stopping'
        case int() as number if number > 100:
            return 'big number: ' + str(number)
        case int():
            return 'a number'
        case [first, *rest]:
            return 'list starting with ' + str(first) + ', ' + str(len(rest)) + ' more'
        case {'type': kind}:
            return 'record of type ' + kind
        case _:
            return 'unknown'


print(describe('start'))            # starting
print(describe('quit'))             # stopping
print(describe(250))                # big number: 250
print(describe(7))                  # a number
print(describe([1, 2, 3]))           # list starting with 1, 2 more
print(describe({'type': 'ping'}))    # record of type ping
print(describe(3.5))                # unknown

Several features are visible in that example. The vertical bar in case 'stop' | 'quit' means that either pattern is acceptable. The int() pattern matches by type, and the as number part binds the matched value to a name. The if clause after that pattern is a guard, and it is only checked once the type has matched. If the guard fails, then that case does not match and the next case is tried instead. The sequence pattern with a star captures the first element and puts the rest into a list. The mapping pattern asks for the key to be present and binds its value.

Two rules catch people out here. The wildcard case _ matches anything, so it has to come last, because otherwise it would hide every case that comes after it. And a capture pattern binds a name without restricting the value at all, so a bare name matches everything. That is exactly why the wildcard is written with an underscore in front of it.

The last detail is that match and case are soft keywords, so you can still use them as ordinary variable names in other parts of your code.

The match statement is Python's version of structural pattern matching. That is a language feature which exists in Rust, Haskell, Scala, and Java, and it was added to Python in version 3.10 under PEP 634.

The problem that it solves is not the simple switch statement. Python already had if and elif chains that compare values perfectly well, and the PEP was explicit that match was not meant to be a better switch. The problem it solves is dispatching on the structure of a value, which means its type, the shape of a sequence, the keys of a mapping, or a combination of those. Writing that with if and elif means a pile of isinstance checks, length checks, indexing, and unpacking, spread over several branches.

With match, the structure is written once and it is written declaratively inside the pattern itself. A case can say that the value is an integer and bind it to the name number, or that it is a list whose first element is x and whose remaining elements are rest, or that it is a mapping with a key called type whose value is kind. The match statement then checks all of those conditions and unpacks the pieces in one go.

Two design decisions explain most of the surprising parts of the feature. The patterns are tried strictly from the top down, so the first match wins and the order of the cases matters. And match and case are soft keywords rather than reserved words, so existing code that used those words as variable names keeps working. That was a deliberate concession to backwards compatibility, and the PEP discusses it at length.

For an interview, the safe advice is that match is excellent for structural dispatch and it is overkill for a plain switch. Use if and elif when you are comparing values, and reach for match when the shape of the data is the thing that you are branching on.