Python Structural Pattern Matching: The `match` Statement

January 18, 2026

Python Structural Pattern Matching: The `match` Statement

Beginner

Python 3.10+ introduces structural pattern matching, a powerful way to control flow based on the structure of data.

Core Concept

The `match` statement allows you to compare a value against a series of patterns and execute code based on the first match found. It's more than just a simple `if-elif-else` chain; it inspects the *structure* of the data.

Basic Example

example.py


  def http_status(status):
      match status:
          case 200:
              return "OK"
          case 404:
              return "Not Found"
          case 500:
              return "Internal Server Error"
          case _:  # Wildcard pattern
              return "Unknown Status Code"

  print(http_status(200))
  print(http_status(404))
  print(http_status(503))

How It Works

The `match` statement evaluates the subject (the value after `match`). It then sequentially checks each `case`'s pattern against the subject. If a pattern matches, the code block associated with that case is executed, and the `match` statement terminates. The wildcard `_` acts as a default if no other pattern matches.

Advanced Example

example.py




  def process_command(command):
      match command:
          case ["quit"]:
              print("Exiting...")
          case ["move", x, y]:
              print(f"Moving to coordinates ({x}, {y})")
          case ["add", *items]:
              print(f"Adding items: {items}")
          case _:
              print(f"Unknown command: {command}")

  process_command(["quit"])
  process_command(["move", 10, 20])
  process_command(["add", "apple", "banana", "cherry"])
  process_command(["delete", "item1"])

Common Use Cases

Parsing command-line arguments or API responses.
Handling different types of messages or events.
Implementing state machines.
Destructuring complex data structures like lists and dictionaries.

Common Pitfalls

Forgetting the wildcard `_` can lead to unhandled cases.
Patterns are evaluated sequentially; order matters.
Not all data structures can be matched directly; consider how you represent them.

FAQs

What versions of Python support `match`?

Structural pattern matching was introduced in Python 3.10.

Can `match` be used with dictionaries?

Yes, you can match dictionary keys and values, and even extract them.

What's the difference between `match` and `if-elif-else`?

`match` is designed for structural matching and can deconstruct data, while `if-elif-else` primarily performs boolean comparisons.

Conclusion

Python's structural pattern matching (`match` statement) offers a more readable and powerful way to handle complex conditional logic based on data structure. Embrace it for cleaner, more expressive code.

Search This Blog

CODE