Pattern matching with match and case

A match statement takes one value and checks it against a list of patterns, one case at a time, until one of them fits. It can replace a long chain of if and elif tests that all look at the same value, and it can do more than compare: a pattern can also pull values out into names for the code that follows.

This lesson covers the patterns you will use most: fixed values, alternatives, a catch-all, names that capture the value, and conditions called guards. The next lesson takes patterns further, into lists, dictionaries and objects.

How a match statement works

The value after match is the subject. Python evaluates it once and then tries the case lines from top to bottom. The first case whose pattern fits, and whose guard (if it has one) is true, runs its indented block. Then the whole statement is finished: no other case runs, even if it would have fitted too, and there is no break to write.

If no case fits, the statement does nothing at all. Python raises no error, which is convenient and, as you will see, also an easy way to hide a bug.

Literal patterns, OR patterns and the wildcard

The simplest pattern is a literal: a number, a string, True, False or None written in the case line. It fits when the subject equals it. This calculator chooses what to do from the operator the user typed:

def calculate(a, operator, b):
    match operator:
        case "+":
            return a + b
        case "-":
            return a - b
        case "*" | "x" | "×":
            return a * b
        case "/" | "÷":
            return a / b
        case _:
            raise ValueError(f"unknown operator: {operator!r}")


print(calculate(7, "+", 5))
print(calculate(7, "×", 5))
print(calculate(7, "/", 2))
try:
    print(calculate(7, "^", 2))
except ValueError as error:
    print("ValueError:", error)

12
35
3.5
ValueError: unknown operator: '^'

Three kinds of pattern are at work:

• case "+": is a literal pattern. It fits when operator == "+".
• case "*" | "x" | "×": is an OR pattern: the | lists alternatives, and the case fits if any one of them does. People type multiplication in several ways, and one case handles them all.
• case _: is the wildcard. The underscore fits any subject, so a last case _ handles everything the cases above it did not. Here it raises a ValueError that names the operator the calculator does not know.

True, False and None are the exception to “equals”: they are compared by identity (is), so case True: does not fit the number 1, even though 1 == True.

A common mistake: no case for the rest

Leave out the wildcard and an unexpected subject simply falls through the whole statement:

def size_name(code):
    match code:
        case "S":
            return "small"
        case "M":
            return "medium"
        case "L":
            return "large"


print(size_name("M"))
print(size_name("XL"))

medium
None

"XL" fits none of the three cases, so the match does nothing, the function reaches its end without a return, and it returns None. The program carries on with a wrong value and fails later, somewhere else, which makes the bug hard to trace. Unless doing nothing really is right, end with case _: and return a clear value or raise an exception, as the calculator does.

Capture patterns and guards

A bare name in a pattern, such as code, is a capture pattern. It fits any subject and assigns the subject to that name, which the case can then use. On its own that matches everything, so it is usually combined with a guard: if and a condition after the pattern. Python checks the guard only once the pattern has fitted; if the guard is false, it goes on to the next case.

Every HTTP response carries a three-digit status code, and the HTTP standard sorts them into five classes by their first digit. This function names two common codes exactly and classifies the rest:

def describe(status):
    match status:
        case 200:
            return "200 OK"
        case 404:
            return "404 Not Found"
        case code if 100 <= code <= 199:
            return f"{code}: informational"
        case code if 200 <= code <= 299:
            return f"{code}: successful"
        case code if 300 <= code <= 399:
            return f"{code}: redirection"
        case code if 400 <= code <= 499:
            return f"{code}: client error"
        case code if 500 <= code <= 599:
            return f"{code}: server error"
        case _:
            return f"{status}: not an HTTP status code"


for status in [200, 204, 301, 404, 429, 503, 99]:
    print(describe(status))

200 OK
204: successful
301: redirection
404 Not Found
429: client error
503: server error
99: not an HTTP status code

Notice the order of the cases. 200 is also in the range of the “successful” guard, but case 200 comes first, so it wins. Put specific cases above general ones: a broad case placed early would answer for every value it covers, and the cases below it would never run.

The guards compare numbers, so describe("404"), with the code as text, would raise a TypeError inside the first guard: a guard that fails with an error stops the whole match. The next lesson shows patterns that check the type of the subject before any guard runs.

The capture trap: a bare name never compares

Because a bare name captures, it cannot be used to compare with a constant, and the mistake is easy to make because the code reads naturally. The program below means “if the status is the value of SHIPPED”, but that is not what it says:

SHIPPED = "shipped"

for status in ["packed", "shipped", "cancelled"]:
    match status:
        case "packed":
            print(status, "-> being packed")
        case SHIPPED:
            print(status, "-> on its way")

print("SHIPPED is now", repr(SHIPPED))

packed -> being packed
shipped -> on its way
cancelled -> on its way
SHIPPED is now 'cancelled'

case SHIPPED: fits every subject and assigns it to SHIPPED. The cancelled order is reported as on its way, and because this loop runs at the top level of the file, the constant itself has been overwritten with 'cancelled'.

Python catches one form of this mistake for you. When a capture pattern without a guard is followed by more cases, those cases could never run, and Python refuses to run the file:

SHIPPED = "shipped"


def label(status):
    match status:
        case SHIPPED:
            return "on its way"
        case _:
            return "something else"


print(label("cancelled"))

  File "capture_error.py", line 6
    case SHIPPED:
         ^^^^^^^
SyntaxError: name capture 'SHIPPED' makes remaining patterns unreachable

To compare with a named value, use a dotted name, such as Status.SHIPPED. A name with a dot in it is a value pattern: Python looks the value up and compares the subject with ==. An enumeration (an Enum class) is a natural home for such names, and a StrEnum’s members are strings, so they compare equal to text such as "shipped" read from a file or typed by a user:

from enum import StrEnum


class Status(StrEnum):
    PACKED = "packed"
    SHIPPED = "shipped"


def label(status):
    match status:
        case Status.PACKED:
            return "being packed"
        case Status.SHIPPED:
            return "on its way"
        case _:
            return "unknown status"


for status in ["packed", "shipped", "cancelled"]:
    print(status, "->", label(status))

packed -> being packed
shipped -> on its way
cancelled -> unknown status

The rule to remember: literals and dotted names compare; a bare name captures, and the single underscore matches anything without capturing. If you would rather not write a class, a literal (case "shipped":) works too.

match and case are soft keywords

match and case are keywords only where a match statement can stand. Everywhere else they are ordinary names, so programs written before Python 3.10 that use a variable called match still run. The keyword module calls them soft keywords:

import keyword
import re

print("match is a keyword:", keyword.iskeyword("match"))
print("match is a soft keyword:", keyword.issoftkeyword("match"))
print("soft keywords:", keyword.softkwlist)

# Outside a match statement, match is an ordinary name.
match = re.search(r"\d+", "Invoice 381 is paid")
print(match.group())

match is a keyword: False
match is a soft keyword: True
soft keywords: ['_', 'case', 'match', 'type']
381

The underscore is on the list because it is special inside patterns only, and type because it starts a type alias statement; outside those places, all four are names you may use.

match or if and elif?

Both choose between blocks of code, and many choices can be written either way. Reach for match when several cases look at the same subject: each case then reads as one line, “this value” or “one of these values”, and the patterns of the next lesson can take the subject apart while they test it. Keep if and elif for two or three tests, and for conditions that involve different values, such as if age < 18 and not signed_by_parent:. The two share one habit worth keeping: when nothing fits, nothing runs, so end a match with case _ and an if chain with else whenever every value needs an answer.

Key takeaways

• match evaluates the subject once and runs the first case whose pattern fits and whose guard is true; there is no fall-through and no break.
• Literal patterns compare with == (True, False and None with is), | gives alternatives, and case _ catches everything else.
• When no case fits, nothing happens and no error is raised, so end with case _ unless doing nothing is right.
• A bare name captures the subject; a guard (case code if code < 200:) adds a condition that is checked after the pattern fits.
• To compare with a constant, use a dotted name such as Status.SHIPPED or a literal, never a bare name.