Python’s structural pattern matching is a game-changer for control flow. It’s like having a smart assistant that can understand complex data structures and react accordingly. I’ve been using it since its introduction in Python 3.10, and it’s transformed how I handle data in my code.

Let’s dive right in. At its core, structural pattern matching uses the ‘match’ statement. It’s similar to a switch statement in other languages, but way more powerful. Here’s a simple example:

def greet(name):
    match name:
        case "Alice":
            return "Hi, Alice!"
        case "Bob":
            return "Hello, Bob!"
        case _:
            return f"Nice to meet you, {name}!"

print(greet("Alice"))  # Output: Hi, Alice!
print(greet("Charlie"))  # Output: Nice to meet you, Charlie!

In this example, we’re matching against simple string patterns. But the real power comes when we start matching against more complex structures.

Let’s say we’re parsing different types of messages in a chat application. We might have something like this:

def handle_message(message):
    match message:
        case {"type": "text", "content": content}:
            print(f"Received text message: {content}")
        case {"type": "image", "url": url}:
            print(f"Received image at URL: {url}")
        case {"type": "location", "latitude": lat, "longitude": lon}:
            print(f"Received location: {lat}, {lon}")
        case _:
            print("Received unknown message type")

handle_message({"type": "text", "content": "Hello, world!"})
handle_message({"type": "image", "url": "http://example.com/image.jpg"})
handle_message({"type": "location", "latitude": 40.7128, "longitude": -74.0060})

This code can handle different message structures elegantly. It’s much cleaner than a series of if-elif statements checking for different dictionary keys.

One of the coolest features is the ability to destructure nested data. Imagine we’re working with a more complex data structure, like a JSON response from an API:

def parse_user_data(data):
    match data:
        case {"user": {"name": name, "age": age, "address": {"city": city, "country": country}}}:
            print(f"{name}, aged {age}, lives in {city}, {country}")
        case {"error": msg}:
            print(f"Error: {msg}")
        case _:
            print("Unknown data format")

parse_user_data({
    "user": {
        "name": "John Doe",
        "age": 30,
        "address": {
            "city": "New York",
            "country": "USA"
        }
    }
})

This code can easily extract nested values from a complex dictionary structure. It’s much more readable than traditional methods of accessing nested dictionary keys.

We can also use structural pattern matching with sequences like lists and tuples. Here’s an example:

def analyze_sequence(seq):
    match seq:
        case []:
            print("Empty sequence")
        case [x]:
            print(f"Single-element sequence: {x}")
        case [x, y]:
            print(f"Two-element sequence: {x} and {y}")
        case [x, *rest]:
            print(f"Sequence starting with {x}, followed by {len(rest)} more elements")

analyze_sequence([])
analyze_sequence([1])
analyze_sequence([1, 2])
analyze_sequence([1, 2, 3, 4, 5])

This code can handle sequences of different lengths, extracting elements as needed. The *rest syntax is particularly useful for capturing any remaining elements in a sequence.

Pattern matching isn’t limited to built-in types. We can use it with custom classes too. Let’s say we’re building a simple game with different types of characters:

class Character:
    def __init__(self, name):
        self.name = name

class Warrior(Character):
    def __init__(self, name, weapon):
        super().__init__(name)
        self.weapon = weapon

class Mage(Character):
    def __init__(self, name, spell):
        super().__init__(name)
        self.spell = spell

def describe_character(character):
    match character:
        case Warrior(name=name, weapon=weapon):
            print(f"{name} is a warrior wielding a {weapon}")
        case Mage(name=name, spell=spell):
            print(f"{name} is a mage who can cast {spell}")
        case Character(name=name):
            print(f"{name} is a mysterious character")
        case _:
            print("Not a valid character")

describe_character(Warrior("Conan", "sword"))
describe_character(Mage("Gandalf", "fireball"))
describe_character(Character("Unknown"))

This code can distinguish between different types of characters and extract their attributes, all in a single, readable match statement.

Guard clauses are another powerful feature of structural pattern matching. They allow us to add extra conditions to our patterns. Here’s an example:

def categorize_number(n):
    match n:
        case int(x) if x < 0:
            print(f"{x} is negative")
        case int(x) if x % 2 == 0:
            print(f"{x} is even")
        case int(x):
            print(f"{x} is odd")
        case float(x):
            print(f"{x} is a float")
        case _:
            print("Not a number")

categorize_number(-5)
categorize_number(4)
categorize_number(7)
categorize_number(3.14)
categorize_number("hello")

In this example, we’re using guard clauses (the if statements) to add extra conditions to our patterns. This allows for more fine-grained control over how we match and handle different cases.

One of the most powerful aspects of structural pattern matching is how it can simplify complex parsing tasks. Let’s say we’re building a simple calculator that can handle different types of operations:

def calculate(operation):
    match operation:
        case ("add", x, y):
            return x + y
        case ("subtract", x, y):
            return x - y
        case ("multiply", x, y):
            return x * y
        case ("divide", x, y) if y != 0:
            return x / y
        case ("power", x, y):
            return x ** y
        case ("negate", x):
            return -x
        case _:
            raise ValueError("Invalid operation")

print(calculate(("add", 5, 3)))
print(calculate(("multiply", 4, 6)))
print(calculate(("negate", 7)))
print(calculate(("divide", 10, 2)))
try:
    print(calculate(("divide", 10, 0)))
except ValueError as e:
    print(e)

This calculator can handle different operations with varying numbers of arguments, all in a single, readable match statement. The guard clause in the “divide” case prevents division by zero.

Structural pattern matching really shines when working with abstract syntax trees or other hierarchical data structures. Imagine we’re building a simple expression evaluator:

class Num:
    def __init__(self, value):
        self.value = value

class Add:
    def __init__(self, left, right):
        self.left = left
        self.right = right

class Mul:
    def __init__(self, left, right):
        self.left = left
        self.right = right

def evaluate(expr):
    match expr:
        case Num(value):
            return value
        case Add(left, right):
            return evaluate(left) + evaluate(right)
        case Mul(left, right):