Introduction

Pattern matching is a technique that checks a value against a structure or shape and, when it matches, extracts data from it. Python 3.10 introduced structural pattern matching via the match/case statement — far more powerful than a simple switch. It can match literals, types, sequences, mappings, and even the internal structure of objects, binding parts of the data to variables as it goes.

Real-World Analogy

Prerequisites

Basic Syntax

The match statement compares a subject value against several case patterns, running the first that matches.

def http_status(code):
    match code:
        case 200:
            return "OK"
        case 404:
            return "Not Found"
        case 500:
            return "Server Error"
        case _:                 # wildcard — matches anything
            return "Unknown"

print(http_status(404))   # Not Found

Core Pattern Types

Matching Sequences

Pattern matching shines when destructuring lists and tuples.

def describe(point):
    match point:
        case [0, 0]:
            return "Origin"
        case [0, y]:
            return f"On Y-axis at {y}"
        case [x, 0]:
            return f"On X-axis at {x}"
        case [x, y]:
            return f"Point at ({x}, {y})"
        case _:
            return "Not a 2D point"

print(describe([0, 5]))   # On Y-axis at 5
print(describe([3, 4]))   # Point at (3, 4)

Capturing the rest with *

match [1, 2, 3, 4]:
    case [first, *rest]:
        print(first)   # 1
        print(rest)    # [2, 3, 4]

Matching Dictionaries

def handle(event):
    match event:
        case {"type": "click", "x": x, "y": y}:
            return f"Click at ({x}, {y})"
        case {"type": "key", "value": v}:
            return f"Key pressed: {v}"
        case {"type": t}:
            return f"Unhandled event: {t}"

print(handle({"type": "click", "x": 10, "y": 20}))   # Click at (10, 20)

Matching Class Instances

You can match against object structure and pull out attributes directly.

from dataclasses import dataclass

@dataclass
class Point:
    x: int
    y: int

def locate(p):
    match p:
        case Point(x=0, y=0):
            return "Origin"
        case Point(x=0, y=y):
            return f"On Y-axis at {y}"
        case Point(x=x, y=0):
            return f"On X-axis at {x}"
        case Point(x=x, y=y):
            return f"At ({x}, {y})"

print(locate(Point(0, 7)))   # On Y-axis at 7

Guards (Extra Conditions)

Add an if guard to a case to match only when an extra condition is true.

def classify(point):
    match point:
        case [x, y] if x == y:
            return "On the diagonal"
        case [x, y] if x > 0 and y > 0:
            return "First quadrant"
        case [x, y]:
            return "Somewhere else"

print(classify([4, 4]))   # On the diagonal
print(classify([2, 5]))   # First quadrant

OR Patterns and Binding

def category(command):
    match command:
        case "start" | "run" | "go":       # OR pattern
            return "Begin execution"
        case "stop" | "halt" | "end":
            return "Stop execution"
        case str() as text:                # capture with type check
            return f"Unknown command: {text}"

print(category("go"))     # Begin execution
print(category("pause"))  # Unknown command: pause

match/case vs if/elif

Readability Insight

Handling \(N\) distinct data shapes with nested if/elif often needs manual type checks and unpacking, growing the cognitive load roughly with the number of conditions per branch. With pattern matching, each shape maps to a single declarative case:

\[ \text{Branches} = N \qquad\Rightarrow\qquad \text{Cases} = N \;\text{(one clean case each)} \]

The win isn't algorithmic speed — it's clarity: one shape, one case, with automatic binding.

Best Practices

Common Mistakes

Interview Questions

Quick Revision