{"title":"Nested Dictionaries","description":"","content":"A **nested dictionary** is a dictionary where one or more values are themselves dictionaries. The shape mirrors how real data looks: an order has a customer, who has an address, which has a country. A configuration has sections, each with its own keys. A grouping has categories, each holding a sub-map of items. This lesson covers how to read, write, build, iterate, and update nested dicts, and when a different data model (a dataclass or a typed dict) is the better fit.\n\n---\n\n# What \"Nested\" Means\n\nA dictionary's values can be anything: numbers, strings, lists, other dictionaries. When a value is itself a dictionary, the result is a two-level (or three-level, or deeper) structure. Each inner dictionary stands on its own and follows the same rules as any other dictionary.\n\n\n```python\ncustomer = {\n \"name\": \"Alice\",\n \"email\": \"alice@shop.com\",\n \"address\": {\n \"street\": \"100 Market St\",\n \"city\": \"NYC\",\n \"country\": \"US\",\n },\n}\n\nprint(customer[\"address\"][\"city\"])\n```\n\n\nThe outer dictionary has three keys: `\"name\"`, `\"email\"`, and `\"address\"`. The value at `\"address\"` is another dictionary with its own three keys. Reading the city is two bracket lookups: first `customer[\"address\"]` to get the inner dict, then `[\"city\"]` on that result to get the value.\n\n\n```mermaid\nflowchart LR\n C[customer dict]:::cyan\n NAME[\"'name': 'Alice'\"]:::orange\n EMAIL[\"'email': 'alice@shop.com'\"]:::orange\n ADDR[address dict]:::cyan\n STREET[\"'street': '100 Market St'\"]:::teal\n CITY[\"'city': 'NYC'\"]:::teal\n COUNTRY[\"'country': 'US'\"]:::teal\n\n C --> NAME\n C --> EMAIL\n C --> ADDR\n ADDR --> STREET\n ADDR --> CITY\n ADDR --> COUNTRY\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```\n\n\nThe diagram shows the two-level structure. The outer dict points to the address dict, which has its own keys and values. From the outside, the address looks like a single value at one key. Inside, it's a whole dictionary with its own rules.\n\nNesting can go arbitrarily deep. The same access pattern keeps stacking brackets:\n\n\n```python\norder = {\n \"id\": \"ORD-1023\",\n \"customer\": {\n \"name\": \"Alice\",\n \"address\": {\n \"city\": \"NYC\",\n \"country\": \"US\",\n },\n },\n \"items\": [\n {\"name\": \"Wireless Mouse\", \"price\": 29.99},\n {\"name\": \"USB Cable\", \"price\": 4.99},\n ],\n}\n\nprint(order[\"customer\"][\"address\"][\"country\"])\n```\n\n\nThree brackets, three levels deep. The shape comes up constantly with JSON data, REST API responses, configuration files, and anywhere the world has a \"thing inside a thing\" structure. JSON objects map directly onto this representation in Python.\n\n---\n\n# Real-World Use Cases\n\nSeveral situations call for nested dictionaries.\n\n**JSON-shaped data.** Responses from web APIs and records stored in JSON files come back as nested dicts. The structure is whatever the producer chose, and the consuming code reads it with the same bracket pattern.\n\n\n```python\napi_response = {\n \"status\": \"ok\",\n \"data\": {\n \"user_id\": 42,\n \"cart\": {\n \"items\": [\"Wireless Mouse\", \"USB Cable\"],\n \"total\": 34.98,\n },\n },\n}\n\nprint(api_response[\"data\"][\"cart\"][\"total\"])\n```\n\n\n**Configuration files.** App configs often group settings by area: a `\"database\"` section, a `\"cache\"` section, a `\"logging\"` section. Each section has its own keys.\n\n\n```python\nconfig = {\n \"database\": {\n \"host\": \"localhost\",\n \"port\": 5432,\n },\n \"cache\": {\n \"host\": \"localhost\",\n \"port\": 6379,\n \"ttl_seconds\": 300,\n },\n}\n\nprint(config[\"cache\"][\"ttl_seconds\"])\n```\n\n\n**Grouped lookups.** For lookups by two keys, a nested dict keyed first by group, then by item, is one shape that works. Prices grouped by category, stock counts grouped by warehouse, ratings grouped by product.\n\n\n```python\nprices_by_category = {\n \"Audio\": {\n \"Bluetooth Speaker\": 49.99,\n \"Headphones\": 89.99,\n },\n \"Cables\": {\n \"USB Cable\": 4.99,\n \"HDMI Cable\": 14.99,\n },\n}\n\nprint(prices_by_category[\"Cables\"][\"HDMI Cable\"])\n```\n\n\nThe same data could live in a flat dict keyed on `(category, name)` tuples, or in a list of records, or in a proper class. The nested form wins when the outer keys are a natural grouping that will be iterated over as units (for example, \"print all prices for the Audio category\").\n\n**Multi-level groupings.** Aggregated reports often come as `year -> month -> total` or `country -> city -> orders`. Each level is a real group, not an artificial split.\n\n\n```python\nsales = {\n \"2025\": {\n \"Q1\": 145_000,\n \"Q2\": 162_000,\n },\n \"2026\": {\n \"Q1\": 178_000,\n },\n}\n\nprint(sales[\"2025\"][\"Q2\"])\n```\n\n\n---\n\n# Accessing Values\n\nReading from a nested dictionary chains bracket lookups. Each pair of brackets descends one level. The whole expression evaluates left-to-right.\n\n\n```python\ncustomer = {\n \"name\": \"Alice\",\n \"address\": {\n \"city\": \"NYC\",\n \"country\": \"US\",\n },\n}\n\ncity = customer[\"address\"][\"city\"]\nprint(city)\n```\n\n\nPython evaluates `customer[\"address\"]` first, which returns the inner dict `{\"city\": \"NYC\", \"country\": \"US\"}`. Then it evaluates `[\"city\"]` on that result, which returns `\"NYC\"`. The chained form is a shorthand for assigning the intermediate result to a variable.\n\n\n```python\naddress = customer[\"address\"]\ncity = address[\"city\"]\nprint(city)\n```\n\n\nSame result. The chained version is shorter; the two-step version shows the underlying steps.\n\nIf **any** key along the chain is missing, the lookup raises `KeyError` at that point, and the rest of the chain never runs.\n\n\n```python\ncustomer = {\"name\": \"Alice\"}\nprint(customer[\"address\"][\"city\"])\n```\n\n\nThe error is `KeyError: 'address'` because the outer `\"address\"` key is missing. Python doesn't try to look up `\"city\"`. The same thing happens at any level: if the outer key is there but the inner key isn't, the error is `KeyError: 'city'` instead.\n\n---\n\n# Safe Access With `.get()`\n\nWhen a missing key is a real possibility (data from an external source, optional config sections, user-supplied input), `KeyError` is too loud. The `.get()` method returns a default instead of raising. For nested access, the technique is to default to an **empty dict** at the intermediate levels so the next `.get()` call still works.\n\n\n```python\ncustomer = {\"name\": \"Alice\"}\n\ncity = customer.get(\"address\", {}).get(\"city\", \"unknown\")\nprint(city)\n```\n\n\nThe first `.get(\"address\", {})` returns `{}` because the key is missing. The second `.get(\"city\", \"unknown\")` runs on that empty dict, finds no `\"city\"`, and returns `\"unknown\"`. No exception, no crash, just a sensible fallback.\n\nThe same pattern works for three or more levels:\n\n\n```python\norder = {\"id\": \"ORD-1023\"}\n\ncountry = order.get(\"customer\", {}).get(\"address\", {}).get(\"country\", \"N/A\")\nprint(country)\n```\n\n\nEach `.get(..., {})` keeps the chain alive even when a level is missing. The final `.get(..., \"N/A\")` provides the real default value.\n\nEach `.get(...)` is one O(1) dictionary lookup. The chain `.get(...).get(...)` adds a few of these, plus the cost of creating the empty `{}` default. For deep optional access this is fine; for paths known to exist, direct bracket lookup is cleaner and slightly cheaper.\n\nA common mistake: defaulting to `None` instead of `{}` in the middle of the chain.\n\n**What's wrong with this code?**\n\n\n```python\ncustomer = {\"name\": \"Alice\"}\n\ncity = customer.get(\"address\", None).get(\"city\", \"unknown\")\nprint(city)\n```\n\n\n`None` is not a dictionary, so calling `.get()` on it raises `AttributeError`. The fix is to default to an empty dict `{}` at every intermediate level, not `None`. The last call in the chain can default to any value, since that value gets used directly.\n\n**Fix:**\n\n\n```python\ncity = customer.get(\"address\", {}).get(\"city\", \"unknown\")\n```\n\n\nFor very deep nesting, the chain of `.get(..., {})` calls becomes noisy. A small helper handles arbitrary depth cleanly:\n\n\n```python\ndef deep_get(d, *keys, default=None):\n for key in keys:\n if not isinstance(d, dict):\n return default\n d = d.get(key, default)\n return d\n\norder = {\"customer\": {\"address\": {\"country\": \"US\"}}}\n\nprint(deep_get(order, \"customer\", \"address\", \"country\"))\nprint(deep_get(order, \"customer\", \"phone\", default=\"N/A\"))\n```\n\n\n`deep_get` walks the keys one at a time. If any level isn't a dict or doesn't have the key, it returns the default. This pattern shows up often enough to keep in a utilities module.\n\n---\n\n# Writing and Updating Nested Values\n\nAssigning to a nested key uses the same chained-bracket syntax. The intermediate dictionaries must exist already, or the assignment fails.\n\n\n```python\ncustomer = {\n \"name\": \"Alice\",\n \"address\": {\"city\": \"NYC\", \"country\": \"US\"},\n}\n\ncustomer[\"address\"][\"city\"] = \"Boston\"\nprint(customer)\n```\n\n\n`customer[\"address\"]` evaluates to the inner dict, and `[\"city\"] = \"Boston\"` writes into it. The change happens in place; the outer dict still points to the same inner dict, but the inner dict's `\"city\"` is now updated.\n\nIf the intermediate key doesn't exist, the same syntax raises `KeyError`:\n\n\n```python\ncustomer = {\"name\": \"Alice\"}\ncustomer[\"address\"][\"city\"] = \"Boston\"\n```\n\n\nTo safely write to a path that may not exist yet, create the intermediate dict first, or use `setdefault`.\n\n### `setdefault`: Create Intermediate Dicts on Demand\n\nThe `setdefault(key, default)` method does two things at once: if the key exists, it returns the current value; if the key doesn't exist, it inserts the default and returns it. For nested writes, this creates the inner dict on first use, then writes into it on subsequent calls.\n\n\n```python\nwarehouses = {}\n\nwarehouses.setdefault(\"US\", {})[\"NYC\"] = \"Empire Warehouse\"\nwarehouses.setdefault(\"US\", {})[\"LA\"] = \"West Coast Warehouse\"\nwarehouses.setdefault(\"UK\", {})[\"London\"] = \"Baker Street Warehouse\"\n\nprint(warehouses)\n```\n\n\nThe first call `warehouses.setdefault(\"US\", {})` creates an empty inner dict at `\"US\"` and returns it. The `[\"NYC\"] = \"Empire Warehouse\"` writes into that inner dict. The second `setdefault(\"US\", {})` finds `\"US\"` already there and returns the existing inner dict (it does **not** replace it with a fresh empty one), so the next assignment adds to the same inner dict.\n\nWithout `setdefault`, the equivalent code needs an `if`-check at every level:\n\n\n```python\nwarehouses = {}\nif \"US\" not in warehouses:\n warehouses[\"US\"] = {}\nwarehouses[\"US\"][\"NYC\"] = \"Empire Warehouse\"\n```\n\n\nThat works, but it gets verbose fast with multiple levels. `setdefault` collapses the check-then-create pattern into one call.\n\n### `defaultdict`: Auto-Create Missing Keys\n\nFor repeated nested writes, the `collections.defaultdict` class is even cleaner. A `defaultdict` calls a factory function the moment a missing key is accessed, producing a default value automatically.\n\n\n```python\nfrom collections import defaultdict\n\nwarehouses = defaultdict(dict)\nwarehouses[\"US\"][\"NYC\"] = \"Empire Warehouse\"\nwarehouses[\"US\"][\"LA\"] = \"West Coast Warehouse\"\nwarehouses[\"UK\"][\"London\"] = \"Baker Street Warehouse\"\n\nprint(dict(warehouses))\n```\n\n\n`defaultdict(dict)` means \"any missing key gets a fresh empty dict as its value\". The first write to `warehouses[\"US\"][\"NYC\"]` causes Python to look up `\"US\"` in `warehouses`, find nothing, call the factory `dict()` to make `{}`, store that as the value at `\"US\"`, and then write `\"NYC\"` into the new inner dict. After that point, `\"US\"` is a real key.\n\nFor two levels of nesting, a `defaultdict` of `defaultdict(dict)` handles the inner level too:\n\n\n```python\nfrom collections import defaultdict\n\nratings = defaultdict(lambda: defaultdict(dict))\nratings[\"Electronics\"][\"Mouse\"][\"score\"] = 4.5\nratings[\"Electronics\"][\"Mouse\"][\"count\"] = 1200\nratings[\"Audio\"][\"Headphones\"][\"score\"] = 4.7\n\nprint(dict(ratings))\n```\n\n\nThe `lambda: defaultdict(dict)` is the factory for the outer `defaultdict`: every missing outer key gets a fresh `defaultdict(dict)` as its value, which in turn auto-creates inner dicts on demand. Three levels of auto-creation, no `setdefault` or `if`-checks anywhere.\n\n`defaultdict` access is the same O(1) as a regular dict on existing keys. On missing keys, it pays an extra factory call (one function call) before the assignment. For building nested structures from streams of data, this is faster than the equivalent `setdefault` or `if`-then-create chains.\n\n---\n\n# Iterating Over Nested Dictionaries\n\nIterating a nested dict means iterating the outer dict, then iterating each inner dict. The pattern is a pair of nested loops.\n\n\n```python\nprices_by_category = {\n \"Audio\": {\n \"Bluetooth Speaker\": 49.99,\n \"Headphones\": 89.99,\n },\n \"Cables\": {\n \"USB Cable\": 4.99,\n \"HDMI Cable\": 14.99,\n },\n}\n\nfor category, products in prices_by_category.items():\n print(f\"{category}:\")\n for name, price in products.items():\n print(f\" {name}: ${price:.2f}\")\n```\n\n\nThe outer `.items()` yields `(category, products)` pairs, where `products` is the inner dict. The inner `.items()` yields the `(name, price)` pairs from that inner dict. Two levels of unpacking, no indexing.\n\nIf the values are mixed (some inner dicts, some not), check the type before iterating:\n\n\n```python\ndata = {\n \"name\": \"Alice\",\n \"address\": {\"city\": \"NYC\", \"country\": \"US\"},\n \"active\": True,\n}\n\nfor key, value in data.items():\n if isinstance(value, dict):\n for inner_key, inner_value in value.items():\n print(f\"{key}.{inner_key}: {inner_value}\")\n else:\n print(f\"{key}: {value}\")\n```\n\n\n`isinstance(value, dict)` decides whether to descend or print the value directly. This pattern applies when the structure isn't uniform across all keys.\n\n### Flattening With Recursion\n\nFor arbitrarily deep nested dicts (think config files or JSON responses), a recursive function flattens the whole thing into a flat dict with dotted keys. Each recursive call descends one level deeper.\n\n\n```python\ndef flatten(d, prefix=\"\"):\n result = {}\n for key, value in d.items():\n new_key = f\"{prefix}.{key}\" if prefix else key\n if isinstance(value, dict):\n result.update(flatten(value, new_key))\n else:\n result[new_key] = value\n return result\n\nnested = {\n \"customer\": {\n \"name\": \"Alice\",\n \"address\": {\n \"city\": \"NYC\",\n \"country\": \"US\",\n },\n },\n \"total\": 89.94,\n}\n\nprint(flatten(nested))\n```\n\n\nThe function walks each key-value pair. If the value is itself a dict, it recurses and merges the result with the accumulated `prefix`. If the value isn't a dict, it stores it directly under the dotted key. The result is one flat dict where every key encodes the original path.\n\nFlattening visits every leaf value exactly once, so it's O(N) in the number of leaves. The recursion depth equals the deepest level of nesting, which is rarely a problem in practice (Python's default recursion limit is 1,000).\n\n---\n\n# Shared Mutable Values\n\nA bug shows up when multiple inner dicts that appear independent share the same object. The classic mistake is using a mutable default in a function or in `dict.fromkeys`.\n\n**What's wrong with this code?**\n\n\n```python\nwarehouses = dict.fromkeys([\"US\", \"UK\", \"DE\"], {})\nwarehouses[\"US\"][\"NYC\"] = \"Empire Warehouse\"\n\nprint(warehouses)\n```\n\n\n`dict.fromkeys(keys, value)` uses the **same** value object for every key, so all three countries point to the same inner dict. A write into one of them is visible through all of them.\n\n**Fix:**\n\n\n```python\nwarehouses = {country: {} for country in [\"US\", \"UK\", \"DE\"]}\nwarehouses[\"US\"][\"NYC\"] = \"Empire Warehouse\"\n\nprint(warehouses)\n```\n\n\nA dict comprehension creates a **fresh** `{}` for each key, so the inner dicts are independent. The same trap exists with mutable default arguments to functions (`def f(d={}): ...` shares one dict across every call). The rule: never use the same mutable object as the value for multiple keys unless the sharing is intentional.\n\n---\n\n# Updating Nested Values: Merging Doesn't Go Deep\n\nPython's `dict.update()` (and the `|=` operator added in 3.9) replaces keys at the **top level**. It doesn't merge inner dicts; it overwrites them entirely.\n\n\n```python\nconfig = {\n \"database\": {\"host\": \"localhost\", \"port\": 5432},\n \"cache\": {\"host\": \"localhost\", \"port\": 6379},\n}\n\nconfig.update({\"database\": {\"port\": 6543}})\nprint(config)\n```\n\n\nThe `\"host\"` key inside `\"database\"` is gone. `update` replaced the entire inner dict with the new one. To keep the host and only change the port, merge manually:\n\n\n```python\nconfig = {\n \"database\": {\"host\": \"localhost\", \"port\": 5432},\n \"cache\": {\"host\": \"localhost\", \"port\": 6379},\n}\n\nconfig[\"database\"].update({\"port\": 6543})\nprint(config)\n```\n\n\nCalling `update` on the inner dict directly merges at the inner level. This is the correct form for \"change one field in this section without touching the rest\".\n\nFor deep merges across arbitrary levels, a small helper does the job:\n\n\n```python\ndef deep_merge(base, overrides):\n for key, value in overrides.items():\n if isinstance(value, dict) and isinstance(base.get(key), dict):\n deep_merge(base[key], value)\n else:\n base[key] = value\n return base\n\nconfig = {\n \"database\": {\"host\": \"localhost\", \"port\": 5432},\n \"cache\": {\"host\": \"localhost\", \"port\": 6379, \"ttl_seconds\": 300},\n}\n\noverrides = {\n \"database\": {\"port\": 6543},\n \"cache\": {\"ttl_seconds\": 600},\n}\n\ndeep_merge(config, overrides)\nprint(config)\n```\n\n\nThe helper recurses when both the existing value and the override are dicts; otherwise it overwrites. This pattern fits layered config files where a base file defines defaults and overrides only change specific fields.\n\n---\n\n# When NOT to Use Nested Dictionaries\n\nNested dicts are convenient for free-form data with unknown shape, like JSON from an external source. They become a liability when the shape is fixed and known up front, because:\n\n1. **No autocomplete or type checking.** A typo like `customer[\"adress\"]` (missing `d`) raises `KeyError` only at runtime, often far from where the bug was introduced.\n2. **No documentation of expected fields.** A reader has to infer the structure from how it's used.\n3. **No invariants.** Nothing stops code from putting the wrong type at a key, or omitting a required field.\n\nThree alternatives apply to known shapes.\n\n### Dataclasses\n\nA `dataclass` describes a record with named fields and types. It's a regular Python class with auto-generated boilerplate.\n\n\n```python\nfrom dataclasses import dataclass\n\n@dataclass\nclass Address:\n street: str\n city: str\n country: str\n\n@dataclass\nclass Customer:\n name: str\n email: str\n address: Address\n\ncustomer = Customer(\n name=\"Alice\",\n email=\"alice@shop.com\",\n address=Address(street=\"100 Market St\", city=\"NYC\", country=\"US\"),\n)\n\nprint(customer.address.city)\n```\n\n\nAttribute access (`.address.city`) replaces bracket access. Editors can autocomplete the fields. Type checkers warn on a misspelled `adress`. The structure is documented in the class definition. Dataclasses appear properly in the classes and objects section.\n\n### TypedDict\n\n`TypedDict` describes the expected shape of a dict so a type checker (`mypy`, `pyright`) catches typos and wrong types, while the actual value is still a regular dict.\n\n\n```python\nfrom typing import TypedDict\n\nclass Address(TypedDict):\n street: str\n city: str\n country: str\n\nclass Customer(TypedDict):\n name: str\n email: str\n address: Address\n\ncustomer: Customer = {\n \"name\": \"Alice\",\n \"email\": \"alice@shop.com\",\n \"address\": {\n \"street\": \"100 Market St\",\n \"city\": \"NYC\",\n \"country\": \"US\",\n },\n}\n\nprint(customer[\"address\"][\"city\"])\n```\n\n\nThe dictionary works exactly like a normal nested dict at runtime. The benefit is at edit-and-check time: the type checker knows the expected fields and flags mistakes. `TypedDict` bridges \"everything is a dict\" code (JSON-shaped data) and \"everything is a class\" code (real records).\n\n### Pydantic Models\n\nFor data coming in from outside the program (HTTP requests, config files, message queues), libraries like `pydantic` validate and convert nested dicts into typed objects. The cost is an extra dependency and a bit more code; the gain is automatic validation, conversion, and clear errors when the shape is wrong. This is beyond the scope of this lesson; the library exists for cases where plain nested dicts aren't enough.\n\nA rule of thumb:\n\n\n| Situation | Best fit |\n| --- | --- |\n| JSON response with unknown or varying shape | Nested dict |\n| Small lookup or grouping where keys vary at runtime | Nested dict |\n| Known, fixed record passed around in code | `dataclass` |\n| JSON-shaped data with a known schema that needs type checks | `TypedDict` |\n| External input that must be validated | `pydantic` (or similar) |\n\n\nThe nested dict is the right starting point. Use the alternatives once the structure stabilizes and the code starts documenting it in comments or chasing typo-bugs.","pageType":"python"}

Nested Dictionaries

Get Premium