Structural Pattern Matching

Welcome to the third lesson in the Functional Patterns & Pattern Matching in Python course! You've made excellent progress so far. In the first lesson, we built production-ready decorators with retry logic and exponential backoff. In the second lesson, we explored single-dispatch generic functions, creating a type-aware JSON serializer that adapts behavior based on input types.

Today, we're diving into structural pattern matching, a feature introduced in Python 3.10 that transforms how we handle complex conditional logic. While single dispatch selects implementations based on types, pattern matching inspects the structure and content of data itself. This is particularly powerful when working with dictionaries, sequences, and nested data structures. We'll build a command router that processes user management operations, validates inputs, handles multiple action aliases, captures extra parameters, and routes bulk requests. By the end of this lesson, you'll be able to write expressive, maintainable code that clearly describes what data shapes your functions expect.

When building systems that handle multiple command types, we often end up with long chains of if-elif statements that check keys, validate types, and extract values. Consider a user management API that processes commands like creating users, updating profiles, or deleting accounts.

The traditional approach might look like this: check if the action is "create_user", then verify that "name" and "email" keys exist, validate their types, extract optional fields, and finally execute the logic. Each command type requires its own set of checks, leading to deeply nested conditionals that are hard to read and maintain. Missing a validation check or adding a new command type means carefully navigating this nested structure.

Structural pattern matching provides a declarative alternative. Instead of imperatively checking conditions one by one, we describe the structure we expect and let Python match against it. This approach makes the code more readable, reduces errors, and clearly documents what data shapes are valid.

The match statement introduces a new control flow mechanism in Python. It takes an expression and compares it against a series of patterns defined in case clauses. When a pattern matches, the corresponding block executes, and the match statement completes:

def process_command(command):
    match command:
        case {"action": "ping"}:
            return {"ok": True, "response": "pong"}
        case {"action": "echo", "payload": data}:
            return {"ok": True, "echo": data}
        case _:
            return {"ok": False, "error": "unknown_command"}

Each case clause contains a pattern that describes a data structure. The first pattern matches any dictionary with exactly {"action": "ping"}. The second pattern matches dictionaries with an "action" key set to "echo" and a "payload" key, capturing the payload value in the variable data. The final case _: is a catch-all wildcard that matches anything, similar to else in if-elif chains.