Python structural pattern matching, introduced in Python 3.10, has matured into one of the language most powerful features. In 2026, with Python 3.13+ widely adopted, pattern matching is no longer experimental — it is essential. This guide walks you through practical, real-world uses of match/case that go far beyond simple switch statements.

What Is Structural Pattern Matching?

Structural pattern matching lets you match values against patterns and destructure them in a single step. Think of it as Python answer to switch/case — but with the ability to match complex data structures, types, and nested objects.

command = {"action": "move", "direction": "north", "steps": 3}

match command:
    case {"action": "move", "direction": str(d), "steps": int(n)}:
        print(f"Moving {d} by {n} steps")
    case {"action": "attack", "target": str(t)}:
        print(f"Attacking {t}")
    case _:
        print("Unknown command")

This is far more expressive than chaining if/elif blocks with dictionary key checks.

Pattern Matching with Dataclasses

One of the most powerful uses is matching against dataclass instances. This is perfect for building parsers, interpreters, and event-driven systems.

from dataclasses import dataclass

@dataclass
class HttpRequest:
    method: str
    path: str
    body: dict | None = None

@dataclass
class HttpResponse:
    status: int
    body: str

def handle_request(req: HttpRequest) -> HttpResponse:
    match req:
        case HttpRequest(method="GET", path="/health"):
            return HttpResponse(200, "OK")
        case HttpRequest(method="POST", path="/users", body={"name": str(name)}):
            return HttpResponse(201, f"User {name} created")
        case HttpRequest(method="DELETE", path=str(p)) if p.startswith("/users/"):
            user_id = p.split("/")[-1]
            return HttpResponse(200, f"User {user_id} deleted")
        case _:
            return HttpResponse(404, "Not Found")

Notice how we destructure the dataclass fields and even extract nested dictionary values — all in one case clause.

Guard Clauses with if

You can add conditions to any case using guard clauses. This keeps your matching logic clean and readable.

def classify_score(score: int) -> str:
    match score:
        case n if n >= 90:
            return "A"
        case n if n >= 80:
            return "B"
        case n if n >= 70:
            return "C"
        case n if n >= 60:
            return "D"
        case _:
            return "F"

Matching Sequences and Nested Structures

Pattern matching shines when working with JSON-like nested data — common in API responses and configuration files.

def process_event(event: dict):
    match event:
        case {"type": "push", "commits": [first, *rest]}:
            print(f"Push with {1 + len(rest)} commits")
        case {"type": "pr", "action": "opened", "pr": {"title": str(t), "author": str(a)}}:
            print(f"New PR by {a}: {t}")
        case {"type": "pr", "action": "merged", "pr": {"title": str(t)}}:
            print(f"PR merged: {t}")
        case {"type": str(t)}:
            print(f"Unhandled event type: {t}")

The star pattern [first, *rest] captures the first element and collects the remaining items — similar to destructuring in JavaScript.

Building a Mini CLI Parser

Here is a practical example: a command-line argument parser using pattern matching.

import sys

def cli(args: list[str]):
    match args:
        case ["init", str(project_name)]:
            print(f"Initializing project: {project_name}")
        case ["init"]:
            print("Error: project name required")
        case ["add", *packages] if packages:
            print(f"Installing: {", ".join(packages)}")
        case ["run", str(script), *flags]:
            flag_str = " ".join(flags)
            print(f"Running {script} {flag_str}".strip())
        case ["help" | "--help" | "-h"]:
            print("Usage: tool [init|add|run|help]")
        case []:
            print("No command provided")
        case _:
            print(f"Unknown command: {args}")

The OR pattern "help" | "--help" | "-h" matches any of those strings. Combined with star patterns for variadic arguments, this is a clean alternative to argparse for simple CLIs.

Type Matching for Polymorphism

Pattern matching can replace isinstance() chains, making type-based dispatch much cleaner.

def serialize(value) -> str:
    match value:
        case bool(b):  # Must come before int
            return "true" if b else "false"
        case int(n):
            return str(n)
        case float(f):
            return f"{f:.2f}"
        case str(s):
            return f'"'{s}'"'
        case list(items):
            inner = ", ".join(serialize(i) for i in items)
            return f"[{inner}]"
        case None:
            return "null"
        case _:
            raise TypeError(f"Cannot serialize {type(value)}")

Important: Always match bool before int, since bool is a subclass of int in Python.

When to Use Pattern Matching

• API/webhook handlers — match request shapes and dispatch logic
• CLI tools — parse and route subcommands cleanly
• State machines — match state transitions with guards
• AST/interpreter builders — destructure tree nodes naturally
• Data pipelines — classify and transform records by shape

When NOT to Use It

• Simple equality checks — a plain if is more readable
• Performance-critical hot loops — slightly more overhead than direct comparisons
• When your team is not familiar with it yet — readability matters more than cleverness

Conclusion

Structural pattern matching transforms how you write conditional logic in Python. It is not just syntactic sugar — it enables cleaner architecture for handling complex, nested data. If you are on Python 3.10+, start using it in your next API handler, CLI tool, or data pipeline. Your future self will thank you.