{"title":"Named Tuples","description":"","content":"Plain tuples are useful, but they have one rough edge: every field is identified by position. `product[0]` is the name and `product[2]` is the stock, and the reader has to remember that mapping. Named tuples fix this by giving each position a name, so you can write `product.name` and `product.stock` while keeping every property that made tuples nice in the first place. This lesson covers both ways Python ships them, `collections.namedtuple` and `typing.NamedTuple`, and when to pick each.\n\n---\n\n# Why Positional Tuples Get Painful\n\nA small tuple is fine to read. `(29.99, 5)` is obviously a price and a quantity, and you can unpack it as `price, qty = line` and be done. The problem shows up when the tuple grows past two or three fields, or when the same kind of record gets passed through many functions.\n\n\n```python\nproduct = (\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\n# What does this code do? You have to count fields to be sure.\nif product[3] < 5:\n print(f\"Restock {product[0]}\")\n```\n\n\nNothing prints, because there are 12 in stock and the threshold is 5. But that's not the issue. The issue is that `product[3]` is a mystery to anyone reading this for the first time. Is it the stock? The rating? Some flag? You'd have to find where the tuple was created and count fields.\n\nIt gets worse when somebody reorders the fields. Move price to the end and every `product[2]` in the codebase is now wrong, silently. The code still runs, the numbers just stop meaning what they used to. There is no error and no warning.\n\nA named tuple turns this:\n\n\n```python\nproduct = (\"Wireless Mouse\", \"Electronics\", 29.99, 12)\nprint(product[2])\n```\n\n\nInto this:\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nproduct = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\nprint(product.price)\n```\n\n\nSame data, same immutability, same speed, but the field has a name. `product.price` reads like English, and reordering the fields no longer breaks anything because nothing relies on position.\n\n---\n\n# Creating a Named Tuple With `collections.namedtuple`\n\n`namedtuple` is a factory function. You call it once to create a new tuple subclass, then you use that subclass to make instances.\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\n\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\nprint(mouse)\n```\n\n\nTwo things to notice. First, the call to `namedtuple` returns a **class**, which is why we capitalize the name (`Product`) by convention. Second, when you print an instance, Python shows the field names, not just the values. That alone makes debugging easier than with plain tuples.\n\nThe first argument to `namedtuple` is the type name, and it should match the variable you assign the result to. The second argument is the field names, and you have a few ways to write them.\n\n\n```python\nfrom collections import namedtuple\n\n# Field names as a list of strings.\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\n\n# Field names as a space-separated string.\nAddress = namedtuple(\"Address\", \"street city zip_code country\")\n\n# Field names as a comma-separated string (commas allowed but unusual).\nCoordinate = namedtuple(\"Coordinate\", \"latitude, longitude\")\n\nhome = Address(\"221B Baker St\", \"London\", \"NW1 6XE\", \"UK\")\nspot = Coordinate(40.7128, -74.0060)\n\nprint(home)\nprint(spot)\n```\n\n\nThe space-separated string form is the one you'll see most in real code. It's shorter, and there's a small payoff: when you read `\"street city zip_code country\"`, the field names line up like a header row in a table.\n\nA name has to be a valid Python identifier (letters, digits, underscores, no leading digit) and can't be a reserved keyword. You also can't reuse a name within the same tuple definition.\n\n\n```python\nfrom collections import namedtuple\n\n# This raises ValueError.\nBad = namedtuple(\"Bad\", [\"name\", \"name\"])\n```\n\n\n`namedtuple` has a `rename=True` flag for the rare cases where you're generating field names dynamically and might accidentally produce duplicates or invalid identifiers; it replaces bad names with `_0`, `_1`, etc. You won't use this in normal code, but it's good to know it exists.\n\n---\n\n# Creating Instances: Positional and Keyword\n\nInstances behave like any class constructor. You can pass arguments by position, by keyword, or mix the two.\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\n\n# All positional.\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\n# All keyword.\nkeyboard = Product(name=\"Mechanical Keyboard\", category=\"Electronics\", price=89.99, stock=4)\n\n# Mix: position for the first, keywords for the rest.\nwebcam = Product(\"HD Webcam\", category=\"Electronics\", price=49.99, stock=8)\n\nprint(mouse)\nprint(keyboard)\nprint(webcam)\n```\n\n\nKeyword arguments are the safer style once you have more than two or three fields. They survive field reordering, and they make the call site self-documenting.\n\nIf you pass the wrong number of arguments, you get the same error a regular function would raise:\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nbroken = Product(\"Wireless Mouse\", \"Electronics\", 29.99)\n```\n\n\nPython tells you exactly which field you forgot. With a plain tuple, missing a field is a silent bug that surfaces somewhere far from the cause.\n\n---\n\n# Attribute Access and Indexing, Both Work\n\nThis is the headline feature. A named tuple acts like an object when you want attribute access, and like a tuple when you want indexing. Same instance, two views.\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\n# Attribute access.\nprint(mouse.name)\nprint(mouse.price)\n\n# Index access.\nprint(mouse[0])\nprint(mouse[2])\n\n# Negative indexing.\nprint(mouse[-1])\n\n# len() and iteration work too.\nprint(len(mouse))\nfor value in mouse:\n print(value)\n```\n\n\nThe relationship between these two views is what makes named tuples worth using:\n\n\n```mermaid\nflowchart LR\n NT[\"Product
('Wireless Mouse',
'Electronics',
29.99, 12)\"]:::cyan\n\n NT -->|\"by index\"| I0[\"mouse[0]
'Wireless Mouse'\"]:::orange\n NT -->|\"by index\"| I2[\"mouse[2]
29.99\"]:::orange\n\n NT -->|\"by name\"| A1[\"mouse.name
'Wireless Mouse'\"]:::green\n NT -->|\"by name\"| A2[\"mouse.price
29.99\"]:::green\n\n NT -->|\"unpacked\"| U[\"name, category,
price, stock = mouse\"]:::teal\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```\n\n\nThe orange path (indexing) is what makes the instance a tuple. Existing code that loops over the values, unpacks them, or passes the tuple to a function expecting a sequence keeps working. The green path (attribute access) is the new ergonomics named tuples add. The teal path is unpacking, which behaves exactly like it does for any tuple of the same length.\n\nUnpacking is worth showing concretely because it's how named tuples often interact with the rest of your code:\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\nname, category, price, stock = mouse\nprint(name)\nprint(price)\n```\n\n\nYou also keep equality and hashing behavior. Two instances with the same field values compare equal, and named tuples are hashable (because tuples are), which means you can use them as dictionary keys or set members.\n\n\n```python\nfrom collections import namedtuple\n\nCoordinate = namedtuple(\"Coordinate\", \"lat lon\")\nwarehouse_a = Coordinate(40.7128, -74.0060)\nwarehouse_b = Coordinate(40.7128, -74.0060)\n\nprint(warehouse_a == warehouse_b)\nprint({warehouse_a, warehouse_b})\n```\n\n\nTwo `Coordinate` instances with the same values are equal and hash the same, so the set keeps only one. This is the kind of behavior you want for value types like coordinates, IDs, or RGB colors.\n\n---\n\n# Named Tuples Are Still Immutable\n\nA named tuple is a tuple. You can't change its fields after creation, by name or by index.\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\nmouse.price = 24.99\n```\n\n\nIndex assignment fails the same way as it does for any tuple:\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\nmouse[2] = 24.99\n```\n\n\nThis is by design. If you want a mutable record, a named tuple is the wrong tool; reach for a dataclass or a plain class. If you want a \"changed\" version of a named tuple, you don't change it, you make a new one. That's what `_replace` is for.\n\n---\n\n# Default Values With `defaults`\n\nReal records often have fields with sensible defaults. A product might default to `stock=0` when it's first registered. `namedtuple` supports this with the `defaults` parameter, added in Python 3.7.\n\n`defaults` is an iterable applied to the **rightmost** fields. If your tuple has four fields and you pass two defaults, they fill in the last two fields. The remaining fields are still required.\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\n \"Product\",\n [\"name\", \"category\", \"price\", \"stock\"],\n defaults=[0.0, 0],\n)\n\nmouse = Product(\"Wireless Mouse\", \"Electronics\")\nexpensive = Product(\"4K Monitor\", \"Electronics\", 399.99)\nfull = Product(\"USB Cable\", \"Cables\", 4.99, 50)\n\nprint(mouse)\nprint(expensive)\nprint(full)\n```\n\n\nThe rule about rightmost fields is the same rule Python uses for function default arguments. A field with a default can't come before a field without one, because positional arguments fill from the left. If you need a non-defaulted field after a defaulted one, reorder your fields.\n\nIf you pass too many defaults, Python raises an error:\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\n \"Product\",\n [\"name\", \"price\"],\n defaults=[\"Unknown\", 0.0, 0],\n)\n```\n\n\nYou can check what defaults a named tuple has via the `_field_defaults` dictionary, which is one of the inspection helpers the type carries:\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\n \"Product\",\n [\"name\", \"category\", \"price\", \"stock\"],\n defaults=[0.0, 0],\n)\n\nprint(Product._field_defaults)\n```\n\n\nOnly the fields with explicit defaults appear. `name` and `category` are required, so they're not in the dictionary.\n\n---\n\n# The Underscore Methods: `_asdict`, `_replace`, `_fields`, `_make`\n\nNamed tuples come with a small set of helper methods. They all start with an underscore, which is unusual for public API. The reason is that the underscore prefix keeps them from colliding with field names you choose. If a method were called `asdict`, you couldn't have a field called `asdict` without clobbering it. The leading underscore is a namespace, not a \"don't touch this\" marker. These methods are part of the public API and you're meant to use them.\n\n### `_asdict()`: Convert to a Dictionary\n\n`_asdict()` returns a regular `dict` with the field names as keys. This is handy for serializing to JSON, logging, or passing into something that expects a dict.\n\n\n```python\nfrom collections import namedtuple\nimport json\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\nas_dict = mouse._asdict()\nprint(as_dict)\nprint(json.dumps(as_dict))\n```\n\n\nSince Python 3.8, `_asdict()` returns a regular `dict` (it returned an `OrderedDict` in older versions, but regular dicts preserve insertion order since 3.7 anyway, so the change is mostly cosmetic).\n\n### `_replace(**kwargs)`: Make a Changed Copy\n\nBecause named tuples are immutable, you can't update a field in place. `_replace` builds a new instance with some fields swapped out, leaving the original unchanged.\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\ndiscounted = mouse._replace(price=24.99)\nrestocked = mouse._replace(price=24.99, stock=20)\n\nprint(mouse)\nprint(discounted)\nprint(restocked)\n```\n\n\nThe original `mouse` is untouched. `_replace` is the named-tuple equivalent of \"update this field\", just functional in style. You get a new value instead of mutating the old one. In a system where the same product gets passed around to many functions, that immutability is a feature: nobody can change your data behind your back.\n\n`_replace` only accepts keyword arguments, and the keywords must match real field names. A typo raises:\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\nmouse._replace(pirce=24.99)\n```\n\n\nThat early error is one of the small wins over dict-based records, where a typo on a key just creates a new key and silently breaks things later.\n\n### `_fields`: The Field Names\n\n`_fields` is a tuple of the field names. This is what makes the class self-describing.\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nprint(Product._fields)\n```\n\n\nYou can use this to drive generic code that works across any named tuple type, like a function that prints a record as a table or that builds a CSV header row.\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\n# Print as \"key=value\" pairs.\nfor field, value in zip(Product._fields, mouse):\n print(f\"{field}={value}\")\n```\n\n\n### `_make(iterable)`: Build From an Iterable\n\n`_make` is a class method that constructs an instance from any iterable of the right length. The most common use is reading rows out of a CSV or a database.\n\n\n```python\nfrom collections import namedtuple\n\nProduct = namedtuple(\"Product\", [\"name\", \"category\", \"price\", \"stock\"])\n\nrow = [\"Wireless Mouse\", \"Electronics\", 29.99, 12]\nmouse = Product._make(row)\nprint(mouse)\n\nrows = [\n (\"USB Cable\", \"Cables\", 4.99, 50),\n (\"HDMI Cable\", \"Cables\", 14.99, 25),\n]\nproducts = [Product._make(r) for r in rows]\nfor p in products:\n print(p.name, p.price)\n```\n\n\n`_make` does the same thing as unpacking the iterable into the constructor (`Product(*row)`), with one small advantage: the intent is clearer. Anyone reading `Product._make(row)` knows immediately you're taking an existing sequence and tagging its positions with names.\n\n---\n\n# The Class-Based Syntax: `typing.NamedTuple`\n\nPython 3.6 added a second way to define named tuples that uses class syntax with type annotations. It lives in the `typing` module and ends up creating the same kind of object: a tuple subclass with named fields.\n\n\n```python\nfrom typing import NamedTuple\n\nclass Product(NamedTuple):\n name: str\n category: str\n price: float\n stock: int\n\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\nprint(mouse)\nprint(mouse.price)\n```\n\n\nSame behavior as `collections.namedtuple`. The instance prints the same way, supports the same attribute and index access, has the same immutability, and carries the same underscore methods (`_asdict`, `_replace`, `_fields`, `_make`).\n\nWhat's different is the definition itself. You get three things the factory form doesn't easily give you.\n\n### Type Annotations\n\nThe fields carry types. This isn't enforced at runtime (Python doesn't refuse a string where you said `int`), but it's read by type checkers like mypy and by IDEs that offer autocomplete. For team codebases that use type checking, this alone is reason enough to prefer the class form.\n\n\n```python\nfrom typing import NamedTuple\n\nclass Product(NamedTuple):\n name: str\n category: str\n price: float\n stock: int\n\n# Python doesn't enforce types at runtime.\nbad = Product(\"Mouse\", \"Electronics\", \"twenty bucks\", 12)\nprint(bad)\n```\n\n\nmypy would flag the `\"twenty bucks\"` argument, but the runtime is happy to store whatever you pass. Type annotations on named tuples are documentation and tooling hooks, not validators.\n\n### Default Values\n\nDefaults are written directly on the field, the same way you'd write them on a class attribute or a function parameter.\n\n\n```python\nfrom typing import NamedTuple\n\nclass Product(NamedTuple):\n name: str\n category: str\n price: float = 0.0\n stock: int = 0\n\nmouse = Product(\"Wireless Mouse\", \"Electronics\")\nprint(mouse)\n```\n\n\nSame rule as before: defaulted fields have to come after non-defaulted ones. The class-based form is the more readable version of this, since the default sits right next to the field it applies to.\n\n### Methods\n\nYou can define methods on the class. These become instance methods, just like on a regular class. The fields stay immutable, but methods give you a clean place to put logic that depends on the data.\n\n\n```python\nfrom typing import NamedTuple\n\nclass Product(NamedTuple):\n name: str\n category: str\n price: float\n stock: int = 0\n\n def is_in_stock(self) -> bool:\n return self.stock > 0\n\n def discounted(self, percent: float) -> \"Product\":\n new_price = round(self.price * (1 - percent / 100), 2)\n return self._replace(price=new_price)\n\nmouse = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\nsold_out = Product(\"Limited Edition Mug\", \"Kitchen\", 19.99)\n\nprint(mouse.is_in_stock())\nprint(sold_out.is_in_stock())\nprint(mouse.discounted(20))\n```\n\n\n`is_in_stock` is a simple predicate. `discounted` returns a new product with the price adjusted; it uses `_replace` internally, which is the standard pattern for \"modify\" operations on immutable types.\n\nYou can't define instance state outside the declared fields, since the underlying tuple is fixed. Methods can only read fields and return new values.\n\n### Inheritance\n\nSubclassing a `typing.NamedTuple` is allowed if you're inheriting to add methods, but it has a sharp edge: you can't add fields to a subclass.\n\n\n```python\nfrom typing import NamedTuple\n\nclass Product(NamedTuple):\n name: str\n price: float\n\nclass DiscountedProduct(Product):\n def final_price(self, discount_percent: float) -> float:\n return round(self.price * (1 - discount_percent / 100), 2)\n\nmouse = DiscountedProduct(\"Wireless Mouse\", 29.99)\nprint(mouse.final_price(15))\n```\n\n\nAdding fields in a subclass produces an error. If you need a different set of fields, define a new named tuple rather than subclassing. The fixed shape is part of how named tuples stay small and fast, and the type system enforces that constraint.\n\n---\n\n# `collections.namedtuple` vs `typing.NamedTuple`\n\nBoth produce the same kind of object at runtime. The differences are about the definition site and the developer experience around it.\n\n\n| Feature | `collections.namedtuple` | `typing.NamedTuple` |\n| --- | --- | --- |\n| Style | Factory function | Class definition |\n| Type annotations | No | Yes |\n| Default values | `defaults=[...]` parameter | Inline on each field |\n| Methods | Not directly | Defined in the class body |\n| Docstrings | Set via `Product.__doc__ = \"...\"` | Standard class docstring |\n| Inheritance | Awkward | Allowed (no new fields) |\n| Module | `collections` (stdlib, always present) | `typing` (stdlib since 3.5) |\n| Available since | Python 2.6 | Python 3.6 |\n\n\nPick `typing.NamedTuple` when:\n\n- You want type annotations on the fields (most modern codebases).\n- The record has methods or a docstring.\n- You're already using type hints elsewhere.\n\nPick `collections.namedtuple` when:\n\n- You're generating named tuple types dynamically from data (e.g., reading a CSV header and building a class from the columns at runtime). The factory form is easier to call from code.\n- You're maintaining older code that already uses it; there's no benefit to converting.\n\nBoth are interchangeable for most purposes, and you'll see both forms in real codebases. New code in a typed codebase usually goes with `typing.NamedTuple`.\n\n---\n\n# When Named Tuples Are the Right Choice\n\nNamed tuples sit between plain tuples and full classes. They're not always the right tool; knowing when to reach for them is half the battle.\n\n\n```mermaid\nflowchart TD\n Q1{\"Do I need named
fields?\"}:::cyan\n Q2{\"Do I need to
mutate the record
after creation?\"}:::cyan\n Q3{\"Do field names
change at runtime?\"}:::cyan\n\n PT[\"Plain tuple
(x, y)\"]:::teal\n NT[\"Named tuple
(Product, OrderLine)\"]:::green\n DC[\"dataclass
or regular class\"]:::orange\n DICT[\"dict
{'name': '...'}\"]:::red\n\n Q1 -->|\"no\"| PT\n Q1 -->|\"yes\"| Q2\n Q2 -->|\"yes\"| DC\n Q2 -->|\"no\"| Q3\n Q3 -->|\"yes\"| DICT\n Q3 -->|\"no\"| NT\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef orange fill:#ffa94d,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\nThe four options each have their place:\n\n**Plain tuple** is right when the record is small, throwaway, and the positions are obvious. Returning `(min_value, max_value)` from a function doesn't need names; the function name tells you what you're getting.\n\n**Named tuple** is right when you have a small, fixed set of fields, you want immutability, and the record gets passed around enough that named access pays for the slightly heavier definition. Things like `Product`, `OrderLine`, `Address`, `Coordinate`, and `Customer` are classic fits.\n\n**Dataclass** is right when you need mutability, more methods, or a class that grows over time. `@dataclass` from the standard library gives you a similar concise definition with full class powers.\n\n**Dictionary** is right when the keys are dynamic (you don't know all field names at code-writing time), or when you're working with JSON-shaped data that's already a dict and there's no payoff to wrapping it.\n\nA short comparison of the same `Product` record across the four:\n\n\n```python\nfrom collections import namedtuple\nfrom typing import NamedTuple\nfrom dataclasses import dataclass\n\n# Plain tuple. No names, no validation, no constraints.\nproduct_tuple = (\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\n# Named tuple (factory).\nProduct = namedtuple(\"Product\", \"name category price stock\")\nproduct_nt = Product(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\n# Named tuple (class-based).\nclass ProductTyped(NamedTuple):\n name: str\n category: str\n price: float\n stock: int\n\nproduct_typed = ProductTyped(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\n\n# Dataclass (mutable).\n@dataclass\nclass ProductData:\n name: str\n category: str\n price: float\n stock: int\n\nproduct_dc = ProductData(\"Wireless Mouse\", \"Electronics\", 29.99, 12)\nproduct_dc.price = 24.99 # mutable\n\n# Dictionary (dynamic keys).\nproduct_dict = {\"name\": \"Wireless Mouse\", \"category\": \"Electronics\", \"price\": 29.99, \"stock\": 12}\n\nprint(product_nt.price)\nprint(product_typed.price)\nprint(product_dc.price)\nprint(product_dict[\"price\"])\n```\n\n\nAll four hold the same data. The differences are in how you reach the fields, whether you can mutate them, and what tooling you get for free. Named tuples are the right answer often enough to be worth knowing well, even if they're not the right answer every time.\n\n---\n\n# Named Tuples as Dictionary Keys\n\nBecause named tuples are tuples, they're hashable as long as every field value is hashable. That means they can serve as dictionary keys or set members. This is one of their most useful properties for code that needs to look up records by a composite key.\n\n\n```python\nfrom collections import namedtuple\n\nCoordinate = namedtuple(\"Coordinate\", \"lat lon\")\n\nwarehouses = {\n Coordinate(40.7128, -74.0060): \"NYC Warehouse\",\n Coordinate(34.0522, -118.2437): \"LA Warehouse\",\n Coordinate(41.8781, -87.6298): \"Chicago Warehouse\",\n}\n\nlookup = Coordinate(34.0522, -118.2437)\nprint(warehouses[lookup])\n```\n\n\nIf any field holds an unhashable value (a list, for instance), the whole named tuple becomes unhashable and you'll get a `TypeError` when you try to put it in a dict or set.\n\n---\n\n# Real-World Shape\n\nA few patterns show up often enough to be worth seeing:\n\n\n```python\nfrom collections import namedtuple\n\n# 1. Returning a structured result from a function.\nPriceBreakdown = namedtuple(\"PriceBreakdown\", \"subtotal tax shipping total\")\n\ndef compute_total(items, tax_rate=0.08, shipping=5.00):\n subtotal = sum(price * qty for price, qty in items)\n tax = round(subtotal * tax_rate, 2)\n total = round(subtotal + tax + shipping, 2)\n return PriceBreakdown(subtotal, tax, shipping, total)\n\ncart = [(29.99, 2), (14.99, 1), (4.99, 3)]\nbreakdown = compute_total(cart)\nprint(breakdown)\nprint(f\"Total: ${breakdown.total:.2f}\")\n```\n\n\nReturning a named tuple from a function is much friendlier than returning a four-element plain tuple. The caller can write `result.total` instead of `result[3]`, and the print output shows what each number means.\n\n\n```python\nfrom typing import NamedTuple\n\n# 2. A small immutable value with methods.\nclass OrderLine(NamedTuple):\n product_name: str\n unit_price: float\n quantity: int\n\n def line_total(self) -> float:\n return round(self.unit_price * self.quantity, 2)\n\ncart = [\n OrderLine(\"Wireless Mouse\", 29.99, 2),\n OrderLine(\"USB Cable\", 4.99, 3),\n OrderLine(\"HDMI Cable\", 14.99, 1),\n]\n\nfor line in cart:\n print(f\"{line.product_name}: ${line.line_total():.2f}\")\n\nprint(f\"Cart total: ${sum(line.line_total() for line in cart):.2f}\")\n```\n\n\n`OrderLine` is the kind of thing that would otherwise tempt you to write a full class. With `typing.NamedTuple` you get the same readability, plus immutability for free, in fewer lines.\n\n\n```python\nfrom collections import namedtuple\n\n# 3. Building records from rows of data.\nCustomer = namedtuple(\"Customer\", \"id name email country\")\n\nrows = [\n (1, \"Alice\", \"alice@shop.com\", \"US\"),\n (2, \"Bob\", \"bob@shop.com\", \"UK\"),\n (3, \"Carol\", \"carol@shop.com\", \"US\"),\n]\n\ncustomers = [Customer._make(row) for row in rows]\nus_customers = [c for c in customers if c.country == \"US\"]\nprint(us_customers)\n```\n\n\n`_make` is the bridge between positional data sources (CSV rows, query results) and the named-field world. Once the data is in named tuples, the rest of the code reads cleanly.","pageType":"python"}

Named Tuples

Get Premium