{"title":"Tuple Unpacking","description":"","content":"Tuple packing and unpacking is the feature that makes tuples feel almost invisible in idiomatic Python. Writing `point = 12.5, 47.8` packs two numbers into a tuple, and writing `name, price = product` pulls a tuple apart into named variables. This chapter covers every pattern you'll meet in real code: writing tuples without parentheses, matching arity, the swap idiom, starred targets, ignoring values, unpacking function returns, and unpacking inside loops with `enumerate` and `zip`.\n\n---\n\n# Tuple Packing\n\nPacking is how Python builds a tuple from a comma-separated list of values. The parentheses are not what make a tuple; the comma is.\n\n\n```python\npoint = 12.5, 47.8\n\nprint(point)\nprint(type(point))\n```\n\n\nNo parentheses, no `tuple()` call, just two values and a comma. Python reads the comma as \"build a tuple\", and `point` ends up bound to a two-element tuple. The interactive output still shows parentheses because that's how `repr` chooses to display tuples; the parentheses are a print-time convenience, not a syntax requirement.\n\nYou can pack any number of values this way:\n\n\n```python\nproduct = \"Wireless Mouse\", 29.99, 120\n\nprint(product)\nprint(len(product))\n```\n\n\nThree values separated by commas produce a three-element tuple. The names of the variables on each side of the comma don't matter; only the commas do. Parentheses are a grouping tool, not a tuple constructor, so they're optional in most contexts.\n\nThere's one place where parentheses are genuinely required: inside another expression where the comma would mean something else. A function call, for example, uses commas to separate arguments, so a bare tuple inside a call needs parentheses to avoid being misread as several arguments.\n\n\n```python\ndef describe(value):\n print(f\"got {value} of type {type(value).__name__}\")\n\ndescribe((12.5, 47.8))\n```\n\n\nWithout the inner parentheses, `describe(12.5, 47.8)` would call `describe` with two arguments and raise `TypeError`. When in doubt, add the parentheses. They never hurt readability and they protect against ambiguity.\n\nThe singleton tuple is where the comma rule bites. A value in parentheses is just that value. To pack a single value into a tuple, you need a trailing comma.\n\n\n```python\nnot_a_tuple = (\"Wireless Mouse\")\na_tuple = (\"Wireless Mouse\",)\n\nprint(type(not_a_tuple).__name__)\nprint(type(a_tuple).__name__)\n```\n\n\nWithout the trailing comma, the parentheses are just grouping. With the trailing comma, Python sees a one-element tuple. Same rule as before, restated: the comma builds the tuple.\n\n---\n\n# Basic Unpacking\n\nUnpacking is the reverse direction. Put a tuple on the right and a comma-separated list of names on the left, and Python binds each name to the element at the matching position.\n\n\n```python\nproduct = (\"Wireless Mouse\", 29.99, 120)\n\nname, price, stock = product\n\nprint(name)\nprint(price)\nprint(stock)\n```\n\n\nThree names on the left, three elements on the right. The first name takes the first element, the second name takes the second, and so on. Parentheses on the left are optional too; `name, price, stock = product` is the same as `(name, price, stock) = product`.\n\nThe rule for basic unpacking is strict: the count of names on the left must equal the count of elements on the right. Anything else raises `ValueError`.\n\n\n```python\nproduct = (\"Wireless Mouse\", 29.99, 120)\n\nname, price = product\n```\n\n\nTwo names on the left, three elements on the right. Python won't drop the third value silently. The error names the expected count, which is the count on the left side of the equals sign.\n\nThe same error appears in the other direction when there aren't enough values:\n\n\n```python\nproduct = (\"Wireless Mouse\", 29.99)\n\nname, price, stock = product\n```\n\n\nThree names on the left, two elements on the right. Python tells you exactly what was expected and what was found. This strictness is intentional. If your code expects a tuple of `(name, price, stock)` and gets only `(name, price)`, you almost certainly want to know loudly rather than silently bind `stock` to nothing and crash a hundred lines later.\n\nA subtle pitfall: strings are iterable, so unpacking a string treats each character as one element. If you write `a, b, c = product_code` thinking `product_code` is a three-tuple but it turns out to be the string `\"ABC\"`, the unpacking succeeds and binds `a=\"A\"`, `b=\"B\"`, `c=\"C\"`.\n\n---\n\n# The Swap Idiom\n\nThe single line `a, b = b, a` swaps two variables without a temporary. It works because of how Python schedules evaluation around the equals sign.\n\n\n```python\nfirst_item = \"Wireless Mouse\"\nlast_item = \"HDMI Cable\"\n\nfirst_item, last_item = last_item, first_item\n\nprint(first_item)\nprint(last_item)\n```\n\n\nPython evaluates the right side completely before any assignment happens on the left. The right side `last_item, first_item` packs the current values into a temporary tuple `(\"HDMI Cable\", \"Wireless Mouse\")`. Only after that tuple exists does Python begin unpacking it into the names on the left.\n\nHere is the order of operations as a diagram:\n\n\n```mermaid\nflowchart LR\n START[a, b = b, a]:::cyan --> RHS[Step 1
Evaluate RHS
Build tuple
b_value, a_value]:::orange\n RHS --> TUPLE[Step 2
Temporary tuple
holds old values]:::teal\n TUPLE --> UNPACK[Step 3
Unpack into LHS
a = b_value
b = a_value]:::green\n UNPACK --> DONE[Swap complete]:::cyan\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe diagram shows why a temporary variable isn't needed: the temporary tuple is the temporary. Once both old values are safely captured in that tuple, assignment to `a` and `b` can happen in any order without one clobbering the other.\n\nThe same idea scales beyond two variables. You can rotate three or more values in one line:\n\n\n```python\ntop, second, third = \"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"\n\n# Rotate left: each value moves one slot\ntop, second, third = second, third, top\n\nprint(top, second, third)\n```\n\n\nThe right side packs `(second, third, top)` with the old values, then the left side unpacks into the same three names in the new order. The right side completing before any binding happens is what makes rotations safe.\n\n---\n\n# Starred Unpacking\n\nBasic unpacking requires the number of names to match exactly. The starred target `*name`, introduced by PEP 3132 in Python 3.0, relaxes that. A starred name captures any number of elements, including zero, into a **list**. You can place the star at the start, middle, or end of the pattern.\n\n\n```python\norder_items = (\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\", \"Webcam\", \"Charger\")\n\nfirst, *middle, last = order_items\n\nprint(first)\nprint(middle)\nprint(last)\n```\n\n\n`first` takes the first element. `last` takes the last element. `*middle` collects everything in between as a list. The fixed names at the edges are satisfied first, then the starred name absorbs whatever remains.\n\nA diagram makes the partitioning clearer:\n\n\n```mermaid\nflowchart LR\n SRC[order_items
5-element tuple]:::cyan --> F[first
= index 0
'Wireless Mouse']:::orange\n SRC --> M[*middle
= indices 1 to 3
collected as list]:::teal\n SRC --> L[last
= index 4
'Charger']:::green\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe two fixed names eat one element each from the edges, and the starred name takes whatever is left in the middle. The starred slot can hold zero, one, or many elements.\n\nHere is the surprise that catches people: the starred target produces a **list**, even though we unpacked from a tuple.\n\n\n```python\norder_items = (\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\", \"Webcam\", \"Charger\")\n\nfirst, *middle, last = order_items\n\nprint(type(middle).__name__)\n```\n\n\nThis isn't a typo in Python; it's a deliberate design choice. A starred target always collects into a list, regardless of the source type. The reasoning is that the captured chunk is usually inspected, iterated, or mutated by the caller, and a list is the natural type for that. If the source is a tuple and you want the chunk to be a tuple too, wrap it explicitly: `middle = tuple(middle)`.\n\nThe starred target also accepts an empty capture. If the fixed names eat every available element, the star ends up with an empty list, not an error:\n\n\n```python\norder_items = (\"Wireless Mouse\", \"Charger\")\n\nfirst, *middle, last = order_items\n\nprint(first)\nprint(middle)\nprint(last)\n```\n\n\n`first` and `last` consume both elements, and `middle` ends up as `[]`. The unpacking only fails when the fixed names can't be satisfied, like trying `first, *middle, last = (\"X\",)`, which raises `ValueError: not enough values to unpack (expected at least 2, got 1)`.\n\n\n> **INFO**\n>\n> **Cost:** A starred target allocates a new list and copies references into it. For `first, *rest = huge_tuple` with a million elements, `rest` allocates space for 999,999 references. If you only need to iterate the tail, slicing or `itertools.islice` may be cheaper.\n\n\nOnly one starred name is allowed per pattern. Two would make the split ambiguous, so Python rejects it at parse time:\n\n\n```python\norder_items = (\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\")\n\n*head, *tail = order_items\n```\n\n\nThis is a `SyntaxError`, not a `ValueError`. Python refuses to compile the code because the meaning isn't defined.\n\n---\n\n# Ignoring Values With `_`\n\nWhen you only care about some of the values in a tuple, the Python convention is to use `_` (a single underscore) for the names you want to ignore. The underscore is a regular variable; the convention is purely social.\n\n\n```python\nproduct = (\"Wireless Mouse\", 29.99, 120)\n\n_, price, _ = product\n\nprint(price)\n```\n\n\nTwo `_` slots are bound to `\"Wireless Mouse\"` and `120`, but the name signals \"I don't intend to use these\". Linters and reviewers recognize the convention and won't flag unused variables named `_`.\n\nA small detail: `_` is a normal name, so its value persists. After the unpacking above, `_` holds `120`, the last value bound to it. If you ran `print(_)`, you'd see `120`. The convention says \"don't read this\", not \"Python forbids it\".\n\nYou can combine `_` with a starred target to throw away the middle and keep only the edges. The idiom `first, *_, last` reads as \"give me the first and last, discard everything in between\":\n\n\n```python\nshipment = (\"Warehouse A\", \"Truck 17\", \"Driver 4\", \"Route 12\", \"Customer B\")\n\nfirst, *_, last = shipment\n\nprint(first)\nprint(last)\n```\n\n\nThe middle three elements end up in `_` (as a list), and the intent is clear at a glance. This is much cleaner than `shipment[0]` and `shipment[-1]` on two separate lines, especially inside a `for` loop where the same pattern would otherwise need two index lookups per pass.\n\n---\n\n# Returning Multiple Values From Functions\n\nPython doesn't actually have \"multiple return values\". When a function appears to return more than one value, it's returning a single tuple, and the caller unpacks it. This is one of the most common reasons tuples show up in real code.\n\n\n```python\ndef compute_summary(cart):\n total = sum(price for _, price in cart)\n item_count = len(cart)\n return total, item_count\n\ncart = [(\"Wireless Mouse\", 29.99), (\"USB Cable\", 4.99), (\"HDMI Cable\", 14.99)]\n\nresult = compute_summary(cart)\nprint(result)\nprint(type(result).__name__)\n```\n\n\nThe `return total, item_count` line packs the two values into a tuple. Without unpacking on the caller side, `result` is just that tuple. To work with the two values as separate names, unpack at the call site:\n\n\n```python\ndef compute_summary(cart):\n total = sum(price for _, price in cart)\n item_count = len(cart)\n return total, item_count\n\ncart = [(\"Wireless Mouse\", 29.99), (\"USB Cable\", 4.99), (\"HDMI Cable\", 14.99)]\n\ntotal, item_count = compute_summary(cart)\nprint(f\"Items: {item_count}\")\nprint(f\"Total: ${total:.2f}\")\n```\n\n\nThe call returns a two-tuple, and the unpacking on the left binds `total` and `item_count` in a single line. The function's interface reads as \"returns total and item count\", which is more honest than always returning a single value and forcing callers to index in.\n\nWhen a function returns more than three or four values, that's a hint to switch to a `namedtuple` or a `dataclass` so the fields have real names.\n\n---\n\n# Unpacking in `for` Loops\n\nThe loop variable in a `for` statement is just a binding target, the same as the left side of an `=`. Anywhere binding happens, an unpacking pattern works, and a `for` loop over a sequence of tuples is the most common place you'll use unpacking outside an assignment.\n\n\n```python\ncart = [\n (\"Wireless Mouse\", 2, 29.99),\n (\"USB Cable\", 3, 4.99),\n (\"HDMI Cable\", 1, 14.99),\n]\n\nfor name, qty, unit_price in cart:\n line_total = qty * unit_price\n print(f\"{name} x{qty}: ${line_total:.2f}\")\n```\n\n\nEach item in `cart` is a three-element tuple. The pattern `name, qty, unit_price` in the `for` header binds three names per pass. The loop body works with the names directly, with no `item[0]` or `item[2]` cluttering the math.\n\nThe same starred-target rules apply inside the loop header. If each tuple has a fixed prefix and a variable tail, capture the tail with a star:\n\n\n```python\norders = [\n (\"ORD-1001\", \"Wireless Mouse\"),\n (\"ORD-1002\", \"USB Cable\", \"HDMI Cable\"),\n (\"ORD-1003\", \"Webcam\", \"Charger\", \"Speaker\"),\n]\n\nfor order_id, *items in orders:\n print(f\"{order_id}: {len(items)} item(s) -> {items}\")\n```\n\n\n`order_id` takes the first element of each tuple, and `*items` captures the rest as a list. Each pass sees a different-sized `items`, and the unpacking handles every shape without modification to the loop.\n\n---\n\n# Unpacking With `enumerate`\n\nThe `enumerate` built-in yields `(index, value)` tuples while iterating. Unpacking the pair in the `for` header gives you both names in one step, which beats tracking a manual counter.\n\n\n```python\ncart = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\n\nfor index, item in enumerate(cart):\n print(f\"{index}: {item}\")\n```\n\n\n`enumerate(cart)` produces `(0, \"Wireless Mouse\")`, then `(1, \"USB Cable\")`, and so on. The pattern `index, item` in the loop header unpacks each pair as it arrives. Without unpacking, you'd write `pair = ...` and then `pair[0]`, `pair[1]` inside the body, which is exactly the kind of indexing that unpacking eliminates.\n\nYou can start counting at a different value with `enumerate(cart, start=1)`. The unpacking pattern doesn't change; only the values produced by `enumerate` do.\n\n---\n\n# Unpacking With `zip`\n\nThe `zip` built-in pairs elements from two or more iterables and yields a tuple per position. Like `enumerate`, it's a natural fit for unpacking in the loop header.\n\n\n```python\nnames = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\nprices = [29.99, 4.99, 14.99]\n\nfor product, price in zip(names, prices):\n print(f\"{product}: ${price:.2f}\")\n```\n\n\n`zip(names, prices)` produces `(\"Wireless Mouse\", 29.99)`, then `(\"USB Cable\", 4.99)`, then `(\"HDMI Cable\", 14.99)`. The pattern `product, price` unpacks each pair. The loop ends when the shortest of the zipped iterables is exhausted, so mismatched lengths silently truncate; pass `strict=True` (Python 3.10+) to raise an error on mismatch.\n\n`zip` works with three or more iterables, and the pattern just gets one more name. Three iterables produce three-element tuples per pass and need three names in the unpacking pattern. The shape of the data and the shape of the pattern always match.\n\n---\n\n# Nested Unpacking\n\nWhen a tuple contains other tuples, the unpacking pattern can mirror that shape. Group the inner names with parentheses (or square brackets; both work) to nest one level deeper.\n\n\n```python\nwarehouse = (\"Warehouse A\", (40.7, -74.0))\n\nname, (lat, lon) = warehouse\n\nprint(name)\nprint(lat)\nprint(lon)\n```\n\n\nThe outer tuple has two elements: a string and an inner tuple. The pattern `name, (lat, lon)` says \"the first element binds to `name`, and the second element is itself a two-element sequence I want to unpack into `lat` and `lon`\". The shape of the pattern has to match the shape of the data, or `ValueError` follows.\n\nNested unpacking shines in `for` loops over tuples-of-tuples:\n\n\n```python\ndeliveries = [\n (\"ORD-1001\", (40.7, -74.0)),\n (\"ORD-1002\", (34.0, -118.2)),\n (\"ORD-1003\", (41.9, -87.6)),\n]\n\nfor order_id, (lat, lon) in deliveries:\n print(f\"{order_id} -> ({lat}, {lon})\")\n```\n\n\nEach item is a two-element tuple whose second element is also a two-element tuple. The pattern `order_id, (lat, lon)` binds three names per pass. Without nesting, the loop body would need `coords = item[1]; lat = coords[0]; lon = coords[1]`, which is three lines of bookkeeping for what one line of unpacking does cleanly.\n\nNesting can go deeper, but readability degrades fast. Two levels are usually fine. Three or more is a signal to flatten the data, switch to a `namedtuple`, or unpack one level at a time inside the loop body.\n\n---\n\n# Common Pitfalls\n\nA few packing and unpacking mistakes show up repeatedly in real code. Each one has a clean fix.\n\n**Pitfall 1: Mismatched arity.** Forgetting that basic unpacking is strict produces `ValueError` at runtime. The fix is to count both sides, or use a starred target when the source size varies.\n\n\n```python\nproduct = (\"Wireless Mouse\", 29.99, 120, \"Electronics\")\n\nname, price, stock = product\n```\n\n\nThe source has four elements, the pattern has three names. Add a fourth name, discard the extra with `_`, or use `*` to absorb the tail:\n\n\n```python\nproduct = (\"Wireless Mouse\", 29.99, 120, \"Electronics\")\n\nname, price, stock, *_ = product\n\nprint(name, price, stock)\n```\n\n\nThe starred `*_` captures everything beyond the third element, so the unpacking succeeds whether the tuple has four elements or fourteen.\n\n**Pitfall 2: Unpacking a string by accident.** Strings are iterable. Unpacking one binds each character to a name, which almost never matches intent.\n\n\n```python\ncode = \"ABC\"\na, b, c = code\n\nprint(a, b, c)\n```\n\n\nIf you expected `code` to be a three-tuple and it turned out to be the string `\"ABC\"`, the unpacking silently splits the characters. The bug only surfaces when the values are used downstream and have the wrong type. Defensive fix: check `isinstance(code, tuple)` before unpacking, or pack the string into a one-tuple deliberately with `(code,)` if that's what you want.\n\n**Pitfall 3: Forgetting the comma in a singleton.** Parentheses without a trailing comma are just grouping. To pack a single value into a tuple, you need the comma.\n\n\n```python\nmaybe_tuple = (\"Wireless Mouse\")\nreal_tuple = (\"Wireless Mouse\",)\n\nprint(type(maybe_tuple).__name__)\nprint(type(real_tuple).__name__)\n```\n\n\nThis catches people when they write code like `def get_items(): return (\"Wireless Mouse\")` expecting a one-tuple, and the caller's `name, = get_items()` then raises `TypeError: cannot unpack non-iterable str object` ... actually it would unpack the string into characters because strings are iterable, and the bug would only manifest as a wrong-shape result downstream. Either way, the fix is the same: add the trailing comma whenever you mean a one-element tuple.","pageType":"python"}

Tuple Unpacking

Get Premium