{"title":"match-case (Python 3.10+)","description":"","content":"Python 3.10 added `match` and `case` statements, a feature called **structural pattern matching**. It looks like a switch statement from other languages, but it does much more: it can decompose data structures, bind names to inner values, and dispatch on the shape of an object in a single expression. This lesson covers every pattern type with E-Commerce examples and points out the pitfalls that catch newcomers.\n\n\n> **INFO**\n>\n> **Version note:** Every code sample in this lesson needs **Python 3.10 or newer**. On older interpreters, `match` is treated as a regular identifier and `case` will trigger a `SyntaxError`. Run `python --version` if you're unsure.\n\n\n---\n\n# Why Structural Pattern Matching Exists\n\nIf you've written enough `if`/`elif` chains, you've felt the pain. Imagine you're handling order status updates, and the shape of each update varies. Sometimes it's a simple status string, sometimes a dict with extra tracking info, sometimes a class instance with several fields. A traditional `elif` chain looks like this:\n\n\n```python\ndef describe_event(event):\n if isinstance(event, str):\n if event == \"shipped\":\n return \"Order shipped\"\n elif event == \"delivered\":\n return \"Order delivered\"\n else:\n return \"Unknown status\"\n elif isinstance(event, dict):\n if \"status\" in event and \"tracking\" in event:\n return f\"Shipped with tracking {event['tracking']}\"\n else:\n return \"Status update without tracking\"\n else:\n return \"Unrecognized event\"\n\nprint(describe_event(\"shipped\"))\nprint(describe_event({\"status\": \"shipped\", \"tracking\": \"TRK-991\"}))\n```\n\n\nThe code works, but the logic is buried under repeated `isinstance` checks, key tests, and indexing. You're doing two jobs at once: figuring out the **shape** of the data, and pulling out the **values** you actually care about. `match`/`case` splits those jobs apart so the shape lives in the pattern and the values fall out automatically.\n\nThe same logic with `match`:\n\n\n```python\ndef describe_event(event):\n match event:\n case \"shipped\":\n return \"Order shipped\"\n case \"delivered\":\n return \"Order delivered\"\n case {\"status\": \"shipped\", \"tracking\": tracking}:\n return f\"Shipped with tracking {tracking}\"\n case {\"status\": status}:\n return f\"Status update: {status}\"\n case _:\n return \"Unrecognized event\"\n\nprint(describe_event(\"shipped\"))\nprint(describe_event({\"status\": \"shipped\", \"tracking\": \"TRK-991\"}))\nprint(describe_event({\"status\": \"preparing\"}))\nprint(describe_event(42))\n```\n\n\nEach `case` reads like \"if the event looks like *this shape*, run this branch and let me use the inner values directly\". That second job, pulling out the values, is what makes `match` more than a switch statement.\n\nHere's the high-level flow of how Python evaluates a `match` block:\n\n\n```mermaid\nflowchart TD\n SUBJ[match subject]:::cyan --> C1{Pattern 1
matches?}:::orange\n C1 -->|Yes| B1[Bind names
run case 1]:::green\n C1 -->|No| C2{Pattern 2
matches?}:::orange\n C2 -->|Yes| B2[Bind names
run case 2]:::green\n C2 -->|No| C3{...remaining
cases...}:::orange\n C3 -->|All fail| W[case _
fallthrough]:::teal\n C3 -->|Match| B3[Bind names
run that case]:::green\n B1 --> END[Exit match]:::red\n B2 --> END\n B3 --> END\n W --> END\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nPython tries each pattern in order, top to bottom. The first one that matches runs, and the rest are skipped. If none match, the `match` block does nothing (no error, no warning). Most lessons cover the basic syntax first, so let's do that.\n\n---\n\n# Basic Syntax\n\nThe structure has two keywords:\n\n\n```python\nmatch subject:\n case pattern_1:\n # body for pattern_1\n case pattern_2:\n # body for pattern_2\n case _:\n # body if nothing else matched\n```\n\n\n`match subject:` introduces the value you want to inspect. Each `case pattern:` checks whether the subject fits a pattern, and runs its body if it does. The `_` (underscore) is the **wildcard pattern**: it matches anything and is the standard \"default\" branch.\n\nA small order status example:\n\n\n```python\ndef status_message(status):\n match status:\n case \"placed\":\n return \"Order received\"\n case \"shipped\":\n return \"On the way\"\n case \"delivered\":\n return \"Order delivered\"\n case _:\n return \"Unknown status\"\n\nprint(status_message(\"placed\"))\nprint(status_message(\"shipped\"))\nprint(status_message(\"returned\"))\n```\n\n\nA few rules worth pinning down right away:\n\n- `match` and `case` are **soft keywords**. You can still name a variable `match` outside of a `match` statement, though doing so is a bad idea for readability.\n- There is no implicit fall-through to the next case. Each `case` body is independent; once one runs, the `match` block exits.\n- The wildcard `_` matches anything but does **not** bind a name. You can't reference `_` in the body and expect it to hold the subject (use a capture pattern for that).\n- A `match` with no matching case does nothing. There's no `MatchError` if every pattern misses.\n\n---\n\n# Literal Patterns\n\nThe simplest case: matching against a constant value. Literal patterns compare the subject with `==` (with one exception for `None`, `True`, and `False`, which use `is`).\n\n\n```python\ndef shipping_cost(weight_kg):\n match weight_kg:\n case 0:\n return 0\n case 1:\n return 5\n case 2:\n return 8\n return 15\n\nprint(shipping_cost(0))\nprint(shipping_cost(1))\nprint(shipping_cost(7))\n```\n\n\nLiteral patterns can be strings, numbers, booleans, or `None`:\n\n\n```python\ndef describe_stock(count):\n match count:\n case 0:\n return \"Out of stock\"\n case None:\n return \"Stock not tracked\"\n case True:\n return \"Always available\"\n\n return f\"In stock: {count}\"\n\nprint(describe_stock(0))\nprint(describe_stock(None))\nprint(describe_stock(True))\nprint(describe_stock(5))\n```\n\n\n\n> **INFO**\n>\n> **Cost:** Literal patterns are cheap comparisons. They don't allocate anything and run in roughly the time of a single `==` check. The cost only grows if your subject is an expensive expression; `match` evaluates the subject **once** even if you have twenty cases.\n\n\n---\n\n# Capture Patterns and the Critical Pitfall\n\nA **capture pattern** is just a bare name. It always matches, and it **binds** the subject to that name inside the case body.\n\n\n```python\ndef greet(customer_name):\n match customer_name:\n case name:\n return f\"Hello, {name}\"\n\nprint(greet(\"Alice\"))\nprint(greet(\"Bob\"))\n```\n\n\n`case name:` looks like it's comparing the subject with a variable called `name`. It isn't. It's binding the subject to a brand new local variable called `name`, the same way `name = customer_name` would.\n\nThis is where almost every beginner gets caught. Watch what happens when you try to compare against a variable:\n\n**What's wrong with this code?**\n\n\n```python\nSHIPPED = \"shipped\"\nDELIVERED = \"delivered\"\n\ndef describe(status):\n match status:\n case SHIPPED:\n return \"On the way\"\n case DELIVERED:\n return \"Done\"\n case _:\n return \"Other\"\n\nprint(describe(\"shipped\"))\nprint(describe(\"delivered\"))\nprint(describe(\"placed\"))\n```\n\n\nEvery call returns `\"On the way\"` because `case SHIPPED:` is interpreted as a capture pattern, not a comparison. It binds whatever the subject is to a local variable called `SHIPPED` (yes, even though `SHIPPED` already exists as a module-level constant), and the case always matches. The second and third `case` clauses are unreachable.\n\nPython actually warns you about this:\n\n\n```shell\nSyntaxError: name capture 'SHIPPED' makes remaining patterns unreachable\n```\n\n\nYou'll see the error at import or run time. There are three ways to fix it:\n\n**Fix 1: Use the literal value directly.**\n\n\n```python\ndef describe(status):\n match status:\n case \"shipped\":\n return \"On the way\"\n case \"delivered\":\n return \"Done\"\n case _:\n return \"Other\"\n```\n\n\n**Fix 2: Use a dotted name.** A name with a dot in it (like `module.CONST` or `EnumClass.MEMBER`) is treated as a **value pattern** and compared with `==`. This is the standard idiom for enum members.\n\n\n```python\nfrom enum import Enum\n\nclass OrderStatus(Enum):\n PLACED = \"placed\"\n SHIPPED = \"shipped\"\n DELIVERED = \"delivered\"\n\ndef describe(status):\n match status:\n case OrderStatus.SHIPPED:\n return \"On the way\"\n case OrderStatus.DELIVERED:\n return \"Done\"\n case _:\n return \"Other\"\n\nprint(describe(OrderStatus.SHIPPED))\nprint(describe(OrderStatus.PLACED))\n```\n\n\n`OrderStatus.SHIPPED` has a dot, so Python looks it up and compares the subject against the resolved value. No accidental binding.\n\n**Fix 3: Use a guard.** A `case` clause can have an `if` condition. `case s if s == SHIPPED:` works, though for plain constants the dotted-name fix is cleaner.\n\nThe rule to memorize: **a bare name in a pattern is always a capture, never a comparison**. If you want to compare against a constant, use a literal or a dotted name.\n\n---\n\n# OR Patterns\n\nYou can match several patterns in the same `case` using `|` (the pipe character):\n\n\n```python\ndef is_terminal(status):\n match status:\n case \"delivered\" | \"cancelled\" | \"refunded\":\n return True\n case _:\n return False\n\nprint(is_terminal(\"delivered\"))\nprint(is_terminal(\"cancelled\"))\nprint(is_terminal(\"shipped\"))\n```\n\n\nThe OR pattern matches if **any** of the sub-patterns match. Read `\"delivered\" | \"cancelled\" | \"refunded\"` as \"any of these three values\".\n\nYou can mix literal and capture patterns in an OR, but every sub-pattern must bind the same set of names. This works:\n\n\n```python\ndef shipping_tier(weight_kg):\n match weight_kg:\n case 0 | 1 | 2:\n return \"Light\"\n case 3 | 4 | 5:\n return \"Medium\"\n case _:\n return \"Heavy\"\n\nprint(shipping_tier(1))\nprint(shipping_tier(4))\nprint(shipping_tier(10))\n```\n\n\nOR patterns also pair nicely with the wildcard inside them, which is handy when you want \"this specific value, or anything else, but treat it the same\":\n\n\n```python\ndef is_active(status):\n match status:\n case \"placed\" | \"shipped\" | \"preparing\":\n return True\n case _:\n return False\n\nprint(is_active(\"shipped\"))\nprint(is_active(\"delivered\"))\n```\n\n\n---\n\n# Sequence Patterns\n\n`match` can take apart lists and tuples. A **sequence pattern** uses `[...]` (or `(...)`) and matches by length and element-wise position.\n\n\n```python\ndef describe_cart(cart):\n match cart:\n case []:\n return \"Empty cart\"\n case [item]:\n return f\"One item: {item}\"\n case [first, second]:\n return f\"Two items: {first}, {second}\"\n case [first, second, third]:\n return f\"Three items: {first}, {second}, {third}\"\n\n return \"Many items\"\n\nprint(describe_cart([]))\nprint(describe_cart([\"Wireless Mouse\"]))\nprint(describe_cart([\"Wireless Mouse\", \"USB Cable\"]))\nprint(describe_cart([\"A\", \"B\", \"C\", \"D\"]))\n```\n\n\nEach `case` pattern matches a list of the exact length. Inside the pattern, each position is itself a sub-pattern. The bare names (`item`, `first`, `second`) are capture patterns that bind the element at that position.\n\nFor variable-length matches, use the **star pattern** `*name` to collect \"the rest\" into a list:\n\n\n```python\ndef first_and_rest(cart):\n match cart:\n case []:\n return \"Cart is empty\"\n case [only]:\n return f\"Only item: {only}\"\n case [first, *rest]:\n return f\"First: {first}, rest: {rest}\"\n\nprint(first_and_rest([]))\nprint(first_and_rest([\"Wireless Mouse\"]))\nprint(first_and_rest([\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]))\n```\n\n\n`[first, *rest]` reads as \"at least one element; bind the first to `first` and the remaining elements (zero or more) to `rest` as a list\". `*rest` always binds to a list, even if it captures zero items.\n\nYou can put `*` in the middle too, which is useful when you want the first and last items:\n\n\n```python\ndef describe_order_history(history):\n match history:\n case []:\n return \"No history\"\n case [only]:\n return f\"Single event: {only}\"\n case [first, *_, last]:\n return f\"From {first} to {last}\"\n\nprint(describe_order_history([]))\nprint(describe_order_history([\"placed\"]))\nprint(describe_order_history([\"placed\", \"preparing\", \"shipped\", \"delivered\"]))\n```\n\n\n`*_` is the same as `*name` but throws away the captured items. Use it when you only care about the positions on either side.\n\nOne subtle behavior: sequence patterns don't match strings, even though strings are sequences. This is on purpose, because matching `\"abc\"` against `[first, *rest]` would feel surprising. They match lists, tuples, and most other sequence types, but not `str` and `bytes`.\n\n\n```python\ndef what_is_it(value):\n match value:\n case [first, *_]:\n return f\"Sequence starting with {first}\"\n case _:\n return \"Not a sequence we recognize\"\n\nprint(what_is_it([\"a\", \"b\"]))\nprint(what_is_it((\"a\", \"b\")))\nprint(what_is_it(\"ab\"))\n```\n\n\nThe tuple matches as a sequence. The string does not.\n\n\n> **INFO**\n>\n> **Cost:** Sequence patterns check the subject's length and iterate over its elements. For lists and tuples this is O(n) in the length of the pattern, not the subject. Patterns like `[first, *rest]` allocate a new list for the captured rest, so they're not free, but they're as cheap as `cart[1:]` would be.\n\n\n---\n\n# Mapping Patterns\n\nDictionaries get their own pattern syntax, written with `{...}`. A mapping pattern matches if the subject is a dictionary that contains **at least** the listed keys (extra keys are allowed and ignored).\n\n\n```python\ndef describe_event(event):\n match event:\n case {\"status\": \"shipped\", \"tracking\": tracking}:\n return f\"Shipped with tracking {tracking}\"\n case {\"status\": \"delivered\"}:\n return \"Already delivered\"\n case {\"status\": status}:\n return f\"Status: {status}\"\n case _:\n return \"Unrecognized event\"\n\nprint(describe_event({\"status\": \"shipped\", \"tracking\": \"TRK-991\"}))\nprint(describe_event({\"status\": \"shipped\", \"tracking\": \"TRK-77\", \"extra\": \"ignored\"}))\nprint(describe_event({\"status\": \"delivered\"}))\nprint(describe_event({\"status\": \"preparing\"}))\nprint(describe_event({}))\n```\n\n\nA few things to notice:\n\n- The keys in the pattern (`\"status\"`, `\"tracking\"`) are literal patterns. They must match exactly.\n- The values can be literals (`\"shipped\"`, `\"delivered\"`) or capture patterns (`tracking`, `status`).\n- Extra keys in the subject are fine. The pattern only requires the keys it names.\n- An empty dict matches `case {}:`, which is \"any mapping\", because every dict contains \"at least\" the zero keys listed.\n\nOrder matters in your case list: more specific patterns must come before more general ones. `{\"status\": \"shipped\", \"tracking\": tracking}` must appear before `{\"status\": status}`, otherwise the more general pattern would catch every shipped event first and the specific one would never run.\n\n\n```python\ndef cart_summary(cart):\n match cart:\n case {\"items\": items, \"total\": total, \"discount\": discount}:\n return f\"{len(items)} items, total ${total}, discount ${discount}\"\n case {\"items\": items, \"total\": total}:\n return f\"{len(items)} items, total ${total}\"\n case {\"items\": items}:\n return f\"{len(items)} items, total unknown\"\n case _:\n return \"Empty cart\"\n\nprint(cart_summary({\"items\": [\"A\", \"B\"], \"total\": 50, \"discount\": 5}))\nprint(cart_summary({\"items\": [\"A\", \"B\", \"C\"], \"total\": 75}))\nprint(cart_summary({\"items\": []}))\nprint(cart_summary({}))\n```\n\n\nTo capture the leftover keys (everything you didn't name), use `**rest`:\n\n\n```python\ndef split_known_unknown(event):\n match event:\n case {\"status\": status, \"tracking\": tracking, **extras}:\n return (status, tracking, extras)\n case _:\n return None\n\nprint(split_known_unknown({\n \"status\": \"shipped\",\n \"tracking\": \"TRK-991\",\n \"carrier\": \"FastShip\",\n \"eta_days\": 3,\n}))\n```\n\n\n`**extras` binds a dict of the keys you didn't pattern-match. The double-underscore wildcard form `**_` is not allowed; if you don't want the extras, just leave `**rest` out entirely.\n\n---\n\n# Class Patterns\n\n`match` can also dispatch on the **type** of an object and pull out its attributes in the same step. This is the **class pattern**, written as `ClassName(attr=pattern, ...)`.\n\nYou'll see class patterns most often with `dataclass`-style objects, but a regular class with attributes works the same way. Here's a minimal class for an order:\n\n\n```python\nclass Order:\n def __init__(self, status, total):\n self.status = status\n self.total = total\n\n def __repr__(self):\n return f\"Order(status={self.status!r}, total={self.total})\"\n\ndef label(order):\n match order:\n case Order(status=\"shipped\", total=total):\n return f\"Shipped, ${total}\"\n case Order(status=\"delivered\"):\n return \"Already delivered\"\n case Order(status=status):\n return f\"Status: {status}\"\n case _:\n return \"Not an order\"\n\nprint(label(Order(\"shipped\", 99)))\nprint(label(Order(\"delivered\", 49)))\nprint(label(Order(\"placed\", 19)))\nprint(label(\"not an order\"))\n```\n\n\nThe pattern `Order(status=\"shipped\", total=total)` does three things at once:\n\n1. Checks that the subject is an instance of `Order` (or a subclass).\n2. Checks that the `status` attribute equals `\"shipped\"`.\n3. Binds `total` to a new local variable holding `order.status`'s sibling, `order.total`.\n\nIf any of those checks fail, the pattern moves on to the next case. There's no separate `isinstance` call, no `getattr`, no nested `if`. The pattern carries all three concerns.\n\nYou can match on multiple classes for the same shape using OR:\n\n\n```python\nclass Refund:\n def __init__(self, amount):\n self.amount = amount\n\nclass Cancellation:\n def __init__(self, amount):\n self.amount = amount\n\ndef reversed_amount(event):\n match event:\n case Refund(amount=amount) | Cancellation(amount=amount):\n return amount\n case _:\n return 0\n\nprint(reversed_amount(Refund(amount=20)))\nprint(reversed_amount(Cancellation(amount=35)))\nprint(reversed_amount(\"nothing\"))\n```\n\n\nBoth sides of the `|` must bind the same names (here, `amount`), which they do.\n\nClasses can also support **positional** class patterns by defining a `__match_args__` tuple, but the keyword form (`status=...`, `total=...`) is the form to learn first. It reads clearly, doesn't depend on argument order, and works with any class out of the box.\n\n\n> **INFO**\n>\n> **Cost:** Class patterns do an `isinstance` check followed by attribute lookups. Both are fast in CPython, but they're not free. If your `match` has dozens of class cases and runs in a hot loop, profile before assuming `match` is automatically faster than a `dict` dispatch.\n\n\n---\n\n# Guards\n\nA pattern can have an `if` clause attached, called a **guard**. The case matches only when the pattern fits **and** the guard is true.\n\n\n```python\nclass Order:\n def __init__(self, total):\n self.total = total\n\ndef discount_tier(order):\n match order:\n case Order(total=total) if total > 100:\n return \"Big spender: 15% off\"\n case Order(total=total) if total > 50:\n return \"Medium: 10% off\"\n case Order(total=total) if total > 0:\n return \"Standard: 5% off\"\n case _:\n return \"No discount\"\n\nprint(discount_tier(Order(150)))\nprint(discount_tier(Order(75)))\nprint(discount_tier(Order(10)))\nprint(discount_tier(Order(0)))\n```\n\n\nThe pattern `Order(total=total)` matches every `Order`. The guard `if total > 100` is what narrows it down. Inside a guard, you can reference any name the pattern just bound.\n\nGuards are also the cleanest way to compare against a runtime variable when a dotted name isn't available:\n\n\n```python\ndef matches_preferred(category, preferred_category):\n match category:\n case name if name == preferred_category:\n return f\"Preferred category: {name}\"\n case _:\n return \"Not preferred\"\n\nprint(matches_preferred(\"electronics\", \"electronics\"))\nprint(matches_preferred(\"books\", \"electronics\"))\n```\n\n\n`case name if name == preferred_category:` binds `name` (capture pattern), then checks the guard. Without the guard, writing `case preferred_category:` would silently rebind `preferred_category` instead of comparing against it.\n\nGuards run **after** the structural match, so they only see the case body's local bindings, not the original subject (use the bound names instead). They're also evaluated lazily; later cases are still tried if an earlier guard returns false.\n\n\n```python\ndef cart_warning(cart):\n match cart:\n case {\"items\": items} if len(items) == 0:\n return \"Cart is empty\"\n case {\"items\": items} if len(items) > 50:\n return f\"Cart is huge: {len(items)} items\"\n case {\"items\": items}:\n return f\"Cart has {len(items)} items\"\n case _:\n return \"No cart\"\n\nprint(cart_warning({\"items\": []}))\nprint(cart_warning({\"items\": [\"A\"] * 60}))\nprint(cart_warning({\"items\": [\"A\", \"B\"]}))\nprint(cart_warning({}))\n```\n\n\nEach pattern is identical in shape (`{\"items\": items}`), but the guards split them apart by the captured value. This is a common idiom: use the pattern for shape, use the guard for values that need an expression beyond simple equality.\n\n---\n\n# Why match Isn't Just an if/elif Chain\n\nBy now you've seen what `match` does that `if`/`elif` doesn't. Three things make it qualitatively different:\n\n**1. Structural decomposition.** A single `case` checks the shape of a value and pulls out its parts at the same time. The equivalent `if`/`elif` needs `isinstance` plus key/attribute access plus value comparisons stacked together.\n\n**2. Binding.** When a pattern matches, the inner values are already in named local variables in the case body. You don't write `total = event[\"total\"]` or `total = order.total` after the check; the pattern does it.\n\n**3. One subject evaluation.** The expression after `match` is evaluated exactly once, no matter how many cases follow. An `elif` chain on a computed value usually re-evaluates the value or saves it to a temporary, which is more code to read.\n\nPut together, `match` shines when your data has **shape**: dicts with varying keys, lists with structural meaning (head/tail), or class hierarchies. For plain \"if x is 1, elif x is 2\" code, an `if`/`elif` chain is fine and often clearer. Reach for `match` when you'd otherwise write nested `isinstance` checks or repeated key access.\n\nA side-by-side comparison:\n\n\n| Concern | `if`/`elif` | `match`/`case` |\n| --- | --- | --- |\n| Compare a value to constants | Clean | Clean (literal patterns) |\n| Check type and extract fields | Verbose (`isinstance` + `getattr`) | One pattern |\n| Check shape of nested dict | Verbose (`in` + indexing) | One pattern |\n| Bind extracted values | Manual (`x = event[\"x\"]`) | Automatic |\n| Compare against a runtime variable | Direct (`if x == VAR:`) | Needs dotted name or guard |\n| One-time subject evaluation | Manual (temp variable) | Built in |\n\n\nUse `match` when you'd otherwise write nested type and shape checks. Use `if`/`elif` for plain value comparisons against runtime variables, where the capture pitfall would be a foot-gun.","pageType":"python"}

match-case (Python 3.10+)

Get Premium