{"title":"Dictionaries Basics","description":"","content":"A dictionary stores pairs of values: a **key** you use to find something, and the **value** the key points to. Looking up a product by its name, finding a customer by their email, fetching the price of an item by its product code, all of these are dictionary jobs. This lesson covers what a dictionary actually is, the three common ways to create one, how to read values by key, and the rule about which kinds of things can be used as keys.\n\n---\n\n# What a Dictionary Is\n\nA dictionary is a **mutable** collection of **key-value pairs**, where each key maps to one value. The classic mental model is a phone book: you don't search the whole book to find a number, you look up the name and the number is right next to it. A Python dictionary works the same way. You give it a key, it gives you the value, in roughly the time it takes to read one slot.\n\n\n```python\nproduct_prices = {\n \"Wireless Mouse\": 29.99,\n \"USB Cable\": 4.99,\n \"HDMI Cable\": 14.99,\n}\n\nprint(product_prices[\"Wireless Mouse\"])\n```\n\n\nThree pairs, written as `key: value` with commas between them and curly braces around the whole thing. The key on the left, the value on the right, separated by a colon. When you write `product_prices[\"Wireless Mouse\"]`, Python finds the matching key and hands you back the value next to it.\n\nThe same kind of lookup with a list would force you to walk the items until you found the one you wanted. With a dictionary, the lookup is direct.\n\n\n```mermaid\nflowchart LR\n K1[\"'Wireless Mouse'\"]:::cyan\n K2[\"'USB Cable'\"]:::cyan\n K3[\"'HDMI Cable'\"]:::cyan\n\n V1[\"29.99\"]:::orange\n V2[\"4.99\"]:::orange\n V3[\"14.99\"]:::orange\n\n K1 -->|\"maps to\"| V1\n K2 -->|\"maps to\"| V2\n K3 -->|\"maps to\"| V3\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n```\n\n\nThe cyan boxes are the keys, the orange boxes are the values, and each arrow is one pair. You can think of the dictionary as a small table with two columns. The keys column is what you search by, the values column is what you get back.\n\nA dictionary is the right tool any time you have a \"look up X by Y\" relationship. Product to price, customer ID to customer record, order number to order status, country code to country name. If the question your code keeps asking is \"given this key, what's the value?\", a dictionary is almost always the answer.\n\n---\n\n# Creating Dictionaries\n\nThere are three common ways to make a dictionary. You'll write the first one most of the time and reach for the other two in specific situations.\n\n### The Dictionary Literal: `{}`\n\nA **dictionary literal** is curly braces around a comma-separated list of `key: value` pairs. This is what you'll write in everyday code.\n\n\n```python\nempty_cart = {}\nsingle_pair = {\"Wireless Mouse\": 29.99}\nprices = {\n \"Wireless Mouse\": 29.99,\n \"USB Cable\": 4.99,\n \"HDMI Cable\": 14.99,\n}\n\nprint(empty_cart)\nprint(single_pair)\nprint(prices)\n```\n\n\n`{}` is an empty dictionary, ready to have pairs added later. One small gotcha: empty curly braces are a dict, not a set. An empty set is written `set()`, not `{}`, because the braces were claimed by dictionaries first.\n\nThe trailing comma on the last pair is allowed and conventional for multi-line literals:\n\n\n```python\ncustomer = {\n \"name\": \"Alice\",\n \"email\": \"alice@shop.com\",\n \"country\": \"US\",\n}\nprint(customer)\n```\n\n\nThe trailing comma is the same convenience as with lists: future edits are cleaner because adding a new line doesn't require remembering to add a comma to the previous one.\n\nThe values in a dictionary can be any type at all: strings, numbers, booleans, lists, even other dictionaries. Mixing types within one dictionary is normal and useful. The keys are stricter, and we'll get to that rule in a moment.\n\n\n```python\norder = {\n \"id\": \"ORD-1023\",\n \"total\": 89.94,\n \"shipped\": True,\n \"items\": [\"Wireless Mouse\", \"USB Cable\"],\n}\nprint(order)\n```\n\n\nFour pairs, four different value types. The `items` value is a list, which is fine; values can be any object. This kind of mixed-value dictionary is how you'd describe one order record before reaching for a dataclass or a class.\n\n### The `dict()` Constructor\n\nThe second way is `dict()`, the constructor. With no arguments, it's the same as `{}`:\n\n\n```python\nempty_a = dict()\nempty_b = {}\n\nprint(empty_a)\nprint(empty_b)\nprint(empty_a == empty_b)\n```\n\n\nMost Python developers prefer `{}` because it's shorter and reads as \"an empty dict\" at a glance. `dict()` earns its keep when you have data in another shape that you want to turn into a dictionary, like a list of pairs:\n\n\n```python\npairs = [(\"Wireless Mouse\", 29.99), (\"USB Cable\", 4.99), (\"HDMI Cable\", 14.99)]\nprices = dict(pairs)\nprint(prices)\n```\n\n\nEach two-item tuple becomes one key-value pair. This is exactly the shape you get back from things like `enumerate`, `zip`, or rows from a CSV file, so `dict(...)` is the bridge between sequence-shaped data and dictionary-shaped data.\n\n\n```python\nproducts = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\nprices = [29.99, 4.99, 14.99]\n\nprice_lookup = dict(zip(products, prices))\nprint(price_lookup)\n```\n\n\n`zip(products, prices)` pairs each product with its price, and `dict(...)` turns those pairs into a dictionary. This pattern shows up constantly when you have two parallel lists and want to look up one by the other.\n\n### The Keyword-Argument Form: `dict(key=value)`\n\nThe third way is also the constructor, but called with **keyword arguments**: `dict(name=value, name=value, ...)`. Every keyword name becomes a key in the resulting dictionary, and every keyword value becomes its value.\n\n\n```python\ncustomer = dict(name=\"Alice\", email=\"alice@shop.com\", country=\"US\")\nprint(customer)\n```\n\n\nThis is a shorter, often nicer-looking way to build a dictionary when the keys are all simple strings that happen to be valid Python identifiers. You don't have to put quotes around the keys, and the result is the same dict you'd get from `{\"name\": \"Alice\", ...}`.\n\nThe catch is in that phrase \"valid Python identifiers\". Keyword argument names must be plain identifiers: letters, digits, underscores, no leading digit, no spaces, no reserved words. That means this form can't build dictionaries with keys like `\"first name\"`, `\"123\"`, or `\"class\"`. For those, you need the literal `{}` syntax or a list of pairs.\n\n\n```python\n# This works.\ncustomer = dict(name=\"Alice\", country=\"US\")\n\n# This fails: \"first name\" has a space, not a valid identifier.\n# customer = dict(first name=\"Alice\") # SyntaxError\n\n# This fails: \"class\" is a reserved word.\n# product = dict(class=\"Electronics\") # SyntaxError\n\n# Use the literal form when keys aren't valid identifiers:\ncustomer = {\"first name\": \"Alice\", \"country\": \"US\"}\nproduct = {\"class\": \"Electronics\", \"price\": 29.99}\nprint(customer)\nprint(product)\n```\n\n\nPick the literal `{}` form for everyday dictionary creation. Reach for `dict(pairs)` or `dict(zip(...))` when you have pair-shaped or two-list-shaped data. Use `dict(key=value)` when every key is a plain identifier and the keyword style reads cleaner than quoting.\n\n---\n\n# Reading Values With `[]`\n\nThe headline operation on a dictionary is **lookup by key**. The bracket syntax `prices[\"Wireless Mouse\"]` finds the value that's mapped to that key and returns it.\n\n\n```python\nprices = {\n \"Wireless Mouse\": 29.99,\n \"USB Cable\": 4.99,\n \"HDMI Cable\": 14.99,\n}\n\nprint(prices[\"Wireless Mouse\"])\nprint(prices[\"USB Cable\"])\nprint(prices[\"HDMI Cable\"])\n```\n\n\nThe syntax looks like list indexing (`cart[0]`), but it works differently underneath. With a list, the number in the brackets is a position. With a dictionary, the value in the brackets is a key, and Python uses that key's **hash** to jump directly to where the value is stored.\n\nThe lookup cost is what makes dictionaries special. Whether the dictionary has 10 pairs or 10 million, looking up one key takes roughly the same amount of time. This is the property worth remembering above all others.\n\n\n> **INFO**\n>\n> **Cost:** Dictionary lookup by key is O(1) on average. The dictionary hashes the key and uses that hash to jump straight to the right slot, without scanning the other pairs. The worst case is O(n) if many keys hash to the same slot, but that's rare with normal use.\n\n\nThe contrast with a list is what makes dictionaries useful for lookup. With a list of `(product, price)` pairs, finding the price of `\"Wireless Mouse\"` means walking the list until you find a matching name, which is an O(n) operation. With a dictionary keyed on product name, the same lookup is O(1).\n\n\n```python\n# List-of-pairs approach: O(n) to find a price by name.\npairs = [(\"Wireless Mouse\", 29.99), (\"USB Cable\", 4.99), (\"HDMI Cable\", 14.99)]\n\ndef find_price_in_list(items, name):\n for product, price in items:\n if product == name:\n return price\n raise KeyError(name)\n\nprint(find_price_in_list(pairs, \"USB Cable\"))\n\n# Dictionary approach: O(1) on average.\nprices = dict(pairs)\nprint(prices[\"USB Cable\"])\n```\n\n\nSame answer, much less work in the dictionary version, and the gap grows as the data gets bigger. A thousand-product catalog with a price lookup is barely slower in the dict version. The list version does a thousand times more work in the worst case.\n\n\n> **INFO**\n>\n> **Cost:** `name in some_list` and `some_list.index(name)` are O(n). If you find yourself doing membership checks or lookups against the same list over and over, build a dict (or a set) once and check against it instead.\n\n\n---\n\n# What Happens When the Key Isn't There\n\nAsking for a key that isn't in the dictionary raises `KeyError`. Python doesn't return `None`, doesn't return an empty string, doesn't silently invent the key. It tells you loudly:\n\n\n```python\nprices = {\n \"Wireless Mouse\": 29.99,\n \"USB Cable\": 4.99,\n}\n\nprint(prices[\"Webcam\"])\n```\n\n\nLoud failure is the right behavior. A silent default would let bugs hide, and \"the value at this key is missing\" is almost never the same situation as \"the value at this key is `None`\". `KeyError` tells you the line that's wrong, and the key that wasn't found.\n\nIf you actually want a default for missing keys, there's a method called `get` that handles that. For now, the rule is simple: bracket lookup assumes the key exists, and raises if it doesn't.\n\n---\n\n# Dictionaries Are Mutable\n\nA dictionary can be changed after it's created. Adding a new key, replacing the value at an existing key, both happen with the same assignment syntax: `prices[key] = value`.\n\n\n```python\nprices = {\"Wireless Mouse\": 29.99, \"USB Cable\": 4.99}\n\n# Add a new key.\nprices[\"HDMI Cable\"] = 14.99\nprint(prices)\n\n# Replace the value at an existing key.\nprices[\"Wireless Mouse\"] = 24.99\nprint(prices)\n```\n\n\nThe first assignment adds `\"HDMI Cable\"` as a new key with value `14.99`. The second assignment finds the existing `\"Wireless Mouse\"` key and replaces its value with `24.99`. Same syntax, different effect, depending on whether the key already exists.\n\nThis is the big behavior split between list indexing and dict indexing. With a list, `cart[5] = \"Webcam\"` fails if there's no slot 5; index assignment only replaces existing slots. With a dict, `prices[\"Webcam\"] = 89.99` works whether or not `\"Webcam\"` is already a key; assignment **creates** the key if it's missing.\n\nThe dictionary itself is the same object before and after. Only its contents change. If two variables point to the same dictionary, both see the update:\n\n\n```python\nprices = {\"Wireless Mouse\": 29.99}\nalias = prices\n\nalias[\"Webcam\"] = 89.99\nprint(prices)\n```\n\n\n`alias = prices` doesn't copy the dictionary, it just binds another name to the same one. Adding a key through `alias` is visible through `prices`. This is the same reference behavior as with lists, and the same caveat applies: if you want an independent copy, you need to copy explicitly.\n\n\n> **INFO**\n>\n> **Cost:** Adding a key and replacing a value are both O(1) on average, the same as lookup. Python computes the key's hash, finds the right slot, and writes the value. Growing the dictionary occasionally triggers an internal resize, but that cost averages out to O(1) per operation across many inserts.\n\n\nAssignment is the simplest way to grow a dictionary, but it's not the only one. Other tools like `update` and the merge operator `|` offer additional ways to add or change pairs.\n\n---\n\n# The Hashable-Key Rule\n\nNot anything can be a dictionary key. Python requires keys to be **hashable**, which is the property that lets the dictionary jump directly to a slot instead of scanning.\n\nA hashable object has two requirements: it has a `__hash__` method that returns a stable integer, and its value doesn't change over its lifetime. The second part is the important one for everyday use, because it's the reason **mutable** objects can't be keys. If you used a list as a key and then modified the list, the dictionary would look in the wrong slot the next time you tried to find it.\n\nIn practice, the rule comes down to a short list:\n\n\n| Type | Hashable? | Example as Key |\n| --- | --- | --- |\n| `str` | Yes | `\"name\"` |\n| `int` | Yes | `42` |\n| `float` | Yes | `3.14` |\n| `bool` | Yes | `True` |\n| `tuple` of hashables | Yes | `(\"US\", \"NYC\")` |\n| `frozenset` | Yes | `frozenset({\"a\", \"b\"})` |\n| `list` | **No** | `[1, 2]` raises `TypeError` |\n| `dict` | **No** | `{\"a\": 1}` raises `TypeError` |\n| `set` | **No** | `{1, 2}` raises `TypeError` |\n| `tuple` containing a list | **No** | `(1, [2])` raises `TypeError` |\n\n\nStrings are by far the most common key type. They're immutable, hashable, and human-readable, which makes them the natural fit for product names, customer emails, order IDs, and almost any other kind of label. Integers are the second most common; you'll see them used for things like a customer ID or a product code.\n\n\n```python\n# String keys, the everyday case.\nprices = {\"Wireless Mouse\": 29.99, \"USB Cable\": 4.99}\n\n# Integer keys, fine when the natural key is a number.\ncustomers = {1: \"Alice\", 2: \"Bob\", 3: \"Carol\"}\n\n# Tuple keys, useful for composite lookups.\nwarehouses = {\n (\"US\", \"NYC\"): \"Empire Warehouse\",\n (\"US\", \"LA\"): \"West Coast Warehouse\",\n (\"UK\", \"London\"): \"Baker Street Warehouse\",\n}\n\nprint(prices[\"Wireless Mouse\"])\nprint(customers[1])\nprint(warehouses[(\"US\", \"LA\")])\n```\n\n\nTuple keys are worth a second look. Because a tuple of hashable values is itself hashable, you can use a tuple to represent a composite key: `(country, city)`, `(category, brand)`, `(year, month)`. This is one of the small features that makes Python pleasant for data work.\n\nA tuple stops being hashable the moment it contains an unhashable value. `(1, 2, 3)` is hashable, but `(1, [2, 3])` is not, because the list inside it is mutable.\n\n\n```python\nwarehouses = {}\nwarehouses[(\"US\", [\"NYC\", \"Boston\"])] = \"East Coast\"\n```\n\n\nThe error says `unhashable type: 'list'` because the list is the part inside the tuple that broke the rule. If you needed that exact composite key, you'd convert the list to a tuple first: `(\"US\", (\"NYC\", \"Boston\"))`.\n\nLists themselves are the most common \"I tried to use this as a key\" mistake. Python rejects them outright:\n\n\n```python\nprefs = {}\nprefs[[\"Mouse\", \"Cable\"]] = \"favorites\"\n```\n\n\nThe fix depends on what you were trying to do. If you wanted a fixed group of items as one key, use a tuple: `prefs[(\"Mouse\", \"Cable\")] = \"favorites\"`. If you wanted to use the list's contents as a flat key, you probably wanted a different data shape entirely (maybe a set of keys, each mapping to the same value).\n\n---\n\n# When to Use a Dict vs a List vs a Tuple\n\nYou've now seen three different ways to hold a collection. The question worth answering before reaching for any of them is which one fits the problem.\n\n\n| Question | Use a... |\n| --- | --- |\n| Do I need to look things up by a label or ID? | **dict** |\n| Is the order of items what I care about? | **list** |\n| Is this a fixed, small record where each position has a known meaning? | **tuple** (or named tuple) |\n| Will the collection grow and shrink at runtime? | **list** or **dict** |\n| Is the collection a \"bag of items I'll iterate over\"? | **list** |\n| Do I need fast membership checks (`x in collection`)? | **dict** (or set) |\n\n\nA few concrete examples make the choice obvious:\n\n\n```python\n# A cart: an ordered collection of items you'll iterate over.\ncart = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\n\n# Prices keyed by product name: lookup by label.\nprices = {\n \"Wireless Mouse\": 29.99,\n \"USB Cable\": 4.99,\n \"HDMI Cable\": 14.99,\n}\n\n# A coordinate: a small fixed record where each position has a meaning.\nwarehouse_location = (40.7128, -74.0060)\n\n# A customer record: fields with names, mutable.\ncustomer = {\"name\": \"Alice\", \"email\": \"alice@shop.com\", \"country\": \"US\"}\n\nprint(cart[0])\nprint(prices[\"USB Cable\"])\nprint(warehouse_location[0])\nprint(customer[\"email\"])\n```\n\n\nThe cart wants a list because the items are in a specific order and the operations are \"add\", \"remove\", \"iterate\". The prices want a dictionary because the question is \"given a product name, what's the price?\". The coordinate wants a tuple because the shape is fixed and immutable. The customer wants a dictionary because the fields have names and the record might change.\n\nA common beginner instinct is to reach for parallel lists when a dictionary would be cleaner. Two lists, one of names and one of prices, where the i-th name matches the i-th price, can usually become one dictionary keyed on the name. That single change removes a whole class of bugs (the two lists getting out of sync) and makes lookups O(1) instead of O(n).\n\n\n```python\n# Parallel lists: fragile, slow to look up.\nnames = [\"Wireless Mouse\", \"USB Cable\", \"HDMI Cable\"]\nprices = [29.99, 4.99, 14.99]\n\n# Same data as a dictionary: safer, faster lookup.\nprices_by_name = dict(zip(names, prices))\nprint(prices_by_name[\"USB Cable\"])\n```\n\n\nThat said, parallel lists aren't always wrong. If the order matters and you'll iterate both lists together more often than you'll look up by name, a list (or a list of tuples) might be the right shape. The rule of thumb: when the dominant operation is lookup by label, a dictionary almost always wins.\n\n---\n\n# A Quick Word on Order\n\nOne last thing worth knowing: starting in Python 3.7, dictionaries **preserve insertion order**. The pairs come back out in the same order you put them in. This wasn't always true; in older Python versions, dictionary iteration order was unpredictable.\n\n\n```python\nprices = {}\nprices[\"Wireless Mouse\"] = 29.99\nprices[\"USB Cable\"] = 4.99\nprices[\"HDMI Cable\"] = 14.99\n\nprint(prices)\n```\n\n\nThe dictionary remembers that `\"Wireless Mouse\"` was added first, then `\"USB Cable\"`, then `\"HDMI Cable\"`, and prints them in that order. This is convenient for things like JSON output, where you want a stable field order. For now, just know that Python doesn't shuffle your keys behind your back.","pageType":"python"}

Dictionaries Basics

Get Premium