Structural Pattern Matching (match-case)

15 min · Beginner

Introduced in Python 3.10 (PEP 634), structural pattern matching (match-case) is a powerful control flow feature that goes far beyond traditional switch statements.

Basic match-case syntax

Match statement compares one value, called the subject, with each case pattern from top to bottom. It runs the block of the first case that matches. Python 3.10 added it.

A match statement inspects a subject value and executes the first matching case block.

Python

1status = 4042match status:3    case 200:4        print("OK")5    case 404:6        print("Not Found")7    case _:8        print("Unknown Status")

Example 1 · Order status messages

Python

1order_status = "shipped"2
3match order_status:4    case "placed":5        print("We received your order")6    case "shipped":7        print("Your order is on the way")8    case "delivered":9        print("Order delivered")10    case _:11        print("Unknown status")

Output

Your order is on the way

What this code does

The subject is compared with each string in order. "shipped" matches the second case.
Only that block runs. There is no break and no fall-through to the next case.

The underscore _ acts as a wildcard default case, matching anything that was not caught by previous cases.

Multiple patterns with the pipe | operator

Or pattern is several patterns joined with | on one case line. The case matches when the subject fits any one of them, so one block can serve many values.

Combine multiple matching values in a single case statement using the pipe | symbol.

Python

1command = "quit"2match command:3    case "quit" | "exit" | "q":4        print("Terminating session")5    case "help" | "h":6        print("Displaying manual")7    case _:8        print("Command unrecognized")

Example 2 · Grouping HTTP codes

Python

1http_code = 5032
3match http_code:4    case 200 | 201:5        print("Success response")6    case 400 | 401 | 403 | 404:7        print("Client error response")8    case 500 | 502 | 503:9        print("Server error response")10    case _:11        print("Unrecognized HTTP code")

Output

Server error response

What this code does

Matches HTTP status code 503 against multiple error codes.
Triggers the Server error response branch cleanly.

The pipe operator acts as an OR condition between matching patterns.

Pattern guards with if

Guard is an if condition written after a case pattern. The case matches only when the pattern fits and the guard is also True, which allows ranges and other tests.

You can attach an if guard to a case. The case succeeds only if both the pattern matches and the guard condition evaluates to true.

Python

1age = 222match age:3    case n if n < 18:4        print("Minor")5    case n if 18 <= n <= 65:6        print("Working age")7    case _:8        print("Senior")

Example 3 · Fee bands with guards

Python

1weight_kg = 72
3match weight_kg:4    case w if w <= 2:5        fee = 406    case w if w <= 5:7        fee = 808    case _:9        fee = 12010print(f"Fee: {fee}")

Output

Fee: 120

What this code does

w takes the value of the subject, and the guard tests it. 7 fails both guards.
The wildcard _ catches everything left, so fee is 120.

Guards provide powerful filtering without requiring nested if statements inside case bodies.

Next step

Check your understanding

8 quick questions

1order_status = "shipped"2 3match order_status:4 case "placed":5 print("We received your order")6 case "shipped":7 print("Your order is on the way")8 case "delivered":9 print("Order delivered")10 case _:11 print("Unknown status")

1command = "quit"2match command:3 case "quit" | "exit" | "q":4 print("Terminating session")5 case "help" | "h":6 print("Displaying manual")7 case _:8 print("Command unrecognized")

1http_code = 5032 3match http_code:4 case 200 | 201:5 print("Success response")6 case 400 | 401 | 403 | 404:7 print("Client error response")8 case 500 | 502 | 503:9 print("Server error response")10 case _:11 print("Unrecognized HTTP code")