Pattern matching

Matching dictionaries: events and API messages

Mapping patterns match dictionaries by the keys they name, and ignore any other keys. That's exactly how events from APIs and webhooks look: a type field says which kind, and each kind has its own fields.

def handle(event):
    match event:
        case {"type": "order.created", "order_id": oid, "total": total} if total >= 500:
            return f"big order {oid}: notify the manager"
        case {"type": "order.created", "order_id": oid}:
            return f"new order {oid}"
        case {"type": "order.refunded", "order_id": oid, "reason": str(reason)}:
            return f"refund on {oid}: {reason}"
        case {"type": "stock.low", "items": [first, *more]}:
            return f"low stock: {first} and {len(more)} more"
        case {"type": str(kind)}:
            return f"ignored event {kind}"
        case _:
            raise ValueError(f"not an event: {event!r}")

events = [
    {"type": "order.created", "order_id": 50231, "total": 1240, "store": "online"},
    {"type": "order.created", "order_id": 50232, "total": 60},
    {"type": "order.refunded", "order_id": 50101, "reason": "arrived damaged"},
    {"type": "stock.low", "items": ["TE-101", "PA-108", "FO-120"]},
    {"type": "customer.updated", "id": 9},
]
for e in events:
    print(handle(e))

{"type": "order.created", "order_id": oid} matches any dictionary whose "type" is that string and which has an "order_id" key, capturing its value; extra keys like "store" are ignored. str(reason) matches only if the value is a string (it's a class pattern, covered next). Patterns nest, so "items": [first, *more] checks the list inside the dictionary too.

Matching objects

A class pattern like Point(x=0) matches objects of that class, and checks or captures their attributes. Dataclasses work with it straight away:

from dataclasses import dataclass

@dataclass
class Text:
    body: str

@dataclass
class Image:
    url: str
    width: int

@dataclass
class ToolCall:
    name: str
    args: dict

def render(block):
    match block:
        case Text(body=""):
            return "(empty text)"
        case Text(body=body):
            return body
        case Image(width=w, url=url) if w > 1000:
            return f"[large image {url}, will be resized]"
        case Image(url=url):
            return f"[image {url}]"
        case ToolCall(name="get_weather", args={"trailhead": place}):
            return f"(checking the weather at {place})"
        case ToolCall(name=name):
            return f"(calling tool {name})"

reply = [Text("Here's the forecast:"), ToolCall("get_weather", {"trailhead": "fern-hollow"}),
         Image("map.png", 2400), Text("")]
for block in reply:
    print(render(block))

This is the shape of code that handles a language model's reply, where each content block is text, an image or a tool call. The class pattern checks the type, like isinstance, and the keyword arguments check or capture attributes, all in one line. Built-in types work as patterns too: int(n), str(s), list().

def fee(order):
    pass


print(fee({"dest": "domestic", "total": 30}), fee({"dest": "domestic", "total": 80, "member": True}))

When to use match, and when not to

match shines when you're branching on the shape of data and pulling pieces out of it: events with a type field, commands, parsed messages, tree structures. One case replaces an isinstance check, a few key lookups and the variable assignments that would follow them.

For simple comparisons it adds nothing. if price > 100: is clearer than a match with a guard. A dictionary from keys to functions (from the functions-as-values lesson) is often better when every case just calls a different handler.

Two traps catch newcomers:

• A bare name always captures. case MAX_QTY: doesn't compare with a constant called MAX_QTY; it matches anything and rebinds the name. To compare with a constant, use a dotted name like case Limits.MAX_QTY: or an enum member like case Color.RED:.
• Strings aren't sequences in patterns. case [first, *rest]: doesn't match the string "add", even though a string is a sequence elsewhere in Python. Split it into a list first.

Finally, remember that match checks shape, not truth. A mapping pattern only proves the keys exist: a "total" of "lots" or None still matches {"total": total}. Where the type of a value matters, say so in the pattern with int(total) or str(name), or check it with a guard, especially for data that came from outside the program, such as a webhook or a file.

Comparing with constants: enums

The bare-name trap has a clean fix. An enum gives a fixed set of named values, and because its members are written with a dot (Status.SHIPPED), match compares with them instead of capturing:

from enum import Enum

class Status(Enum):
    PLACED = "placed"
    SHIPPED = "shipped"
    DELIVERED = "delivered"
    RETURNED = "returned"

def next_step(status, days_since):
    match status:
        case Status.PLACED if days_since > 2:
            return "chase the warehouse"
        case Status.PLACED:
            return "wait"
        case Status.SHIPPED | Status.DELIVERED:
            return "nothing to do"
        case Status.RETURNED:
            return "refund"

for status, days in [(Status.PLACED, 1), (Status.PLACED, 4), (Status("delivered"), 9), (Status.RETURNED, 0)]:
    print(status.name, "->", next_step(status, days))

Status("delivered") turns a string from a database or an API into the enum member, and raises ValueError for anything that isn't a real status. That catches bad data at the edge of the program, instead of letting a typo like "delivred" quietly match nothing deep inside it. Enums and match work well together: every possible value has a name, and each case reads as one rule of the business.

stock = {"TE-101": 4, "PA-108": 0}

def execute(line):
    match line.strip().lower().split():
        case ["stock", sku]:
            return f"{sku.upper()}: {stock.get(sku.upper(), 'unknown')}"
        case ["receive", sku, qty] if qty.isdigit() and int(qty) > 0:
            stock[sku.upper()] = stock.get(sku.upper(), 0) + int(qty)
            return f"received {qty} of {sku.upper()}"
        case ["receive", *_]:
            return "usage: receive SKU QTY (QTY a positive whole number)"
        case ["empty"]:
            return ", ".join(sku for sku, n in stock.items() if n == 0) or "nothing is out of stock"
        case [verb, *_]:
            return f"unknown command {verb!r}"
        case []:
            return "type a command"

for line in ["stock te-101", "receive pa-108 6", "receive pa-108 lots", "empty", "STOCK PA-108", "sell te-101", "  "]:
    print(f"{line!r:24} -> {execute(line)}")