Prerequisites

1. Python version: match works only on Python 3.10+. Check with python --version.
2. Editor/IDE: VS Code / PyCharm / IDLE — anything that runs Python scripts.
3. How to run: Save a file like match_demo.py and run python match_demo.py.

Syntax (What It Looks Like)

match subject_expression:
    case PATTERN_1:
        # actions
    case PATTERN_2:
        # actions
    case _:
        # wildcard (default)
    

How it works: Python evaluates subject_expression once, then checks cases from top to bottom. The first match runs. There is no fall-through.

Step-by-Step: Build Your First match–case

Step 1 — Create a function

We’ll map integers 0–6 to weekday names. Use _ as default for invalid input.

def weekday(n: int) -> str:
    match n:
        case 0: return "Monday"
        case 1: return "Tuesday"
        case 2: return "Wednesday"
        case 3: return "Thursday"
        case 4: return "Friday"
        case 5: return "Saturday"
        case 6: return "Sunday"
        case _: return "Invalid day number"
    

Step 2 — Test the function

print(weekday(3))  # Thursday
print(weekday(6))  # Sunday
print(weekday(7))  # Invalid day number
    

Step 3 — Combine multiple cases (OR pattern)

Use | to trigger the same action for multiple patterns.

def access(role: str) -> str:
    match role:
        case "admin" | "manager":
            return "Full access"
        case "guest":
            return "Limited access"
        case _:
            return "No access"

print(access("manager"))  # Full access
print(access("guest"))    # Limited access
print(access("Ravi"))     # No access
    

Step 4 — Add conditions with guards

Attach if to a case to refine a match after capturing the value.

def classify(n: int) -> str:
    match n:
        case x if x < 0:
            return "negative"
        case 0:
            return "zero"
        case x if x % 2 == 0:
            return "positive even"
        case _:
            return "positive odd"
    

Step 5 — Match sequences (lists/tuples)

Match list length and unpack items. *rest allows variable length.

def shape(items):
    match items:
        case [x, y]:
            return f"two items: {x}, {y}"
        case [first, *middle, last]:
            return f"first={first}, last={last}, middle={middle}"
        case []:
            return "empty list"
        case _:
            return "unknown shape"
    

Step 6 — Match dicts (mappings)

Match by keys; extra keys are allowed unless you use **rest.

def handle(payload: dict):
    match payload:
        case {"type": "user", "id": uid}:
            return f"user id = {uid}"
        case {"ok": True, **_}:
            return "success"
        case _:
            return "ignored"
    

Step 7 — Match classes (dataclasses/objects)

Unpack attributes via positional order (__match_args__) or keywords.

from dataclasses import dataclass

@dataclass
class Point:
    x: int
    y: int

def locate(p: Point) -> str:
    match p:
        case Point(0, y):
            return f"on Y axis at {y}"
        case Point(x=_, y=0):
            return "on X axis"
        case Point(x, y):
            return f"point at ({x}, {y})"
        case _:
            return "not a Point"
    

Common Pitfalls & Best Practices

• No fall-through: First match wins. Put specific cases before generic ones.
• Name capture vs compare: case x captures anything. To compare a constant, use a literal, an enum (e.g., Status.OK), or a guard (e.g., case x if x == LIMIT:).
• Wildcard: Use _ for “anything else”. Don’t reuse it inside the same match.
• Dict matching: Only the specified keys must exist; others can still be present unless you capture with **rest.
• Version: Works on Python 3.10+. On older versions, keep using if/elif.

Practice: Try These

1. FizzBuzz with guards: Print Fizz (3), Buzz (5), FizzBuzz (15), else number.
2. CSV row matcher: Match [date, sku, qty, price]; handle wrong shapes.
3. Event router: For dicts with type: "user.created" or "order.paid", extract fields and print messages.

Note: match-case is more powerful than switch because it supports patterns (shapes of data), not just single values.