Dictionaries

Dicts map hashable keys to arbitrary values with average O(1) lookup. They are the default tool for records, indexes, caches, and dispatch tables in Python application code.

Recipe

defaults = {"retries": 3, "timeout": 30}
overrides = {"timeout": 60}
config = defaults | overrides
 
for key in config:
    print(key, config[key])
 
if "retries" not in config:
    config["retries"] = 1

When to reach for this:

• JSON-like records and API payloads
• Counting and grouping (often with Counter)
• Memoization caches keyed by arguments
• String-to-handler dispatch tables

Working Example

from collections.abc import Callable
 
Handler = Callable[[dict], str]
 
def dispatch(handlers: dict[str, Handler], event: dict) -> str:
    kind = str(event.get("type", "unknown"))
    handler = handlers.get(kind, handlers["unknown"])
    return handler(event)
 
def merge_records(base: dict[str, object], patch: dict[str, object]) -> dict[str, object]:
    merged = base.copy()
    merged.update(patch)
    return merged
 
def invert_unique(mapping: dict[str, int]) -> dict[int, str]:
    return {value: key for key, value in mapping.items()}
 
if __name__ == "__main__":
    handlers: dict[str, Handler] = {
        "user.created": lambda e: f"create {e['id']}",
        "unknown": lambda e: "noop",
    }
    print(dispatch(handlers, {"type": "user.created", "id": 42}))
    print(merge_records({"a": 1}, {"b": 2}))

What this demonstrates:

• handlers.get(kind, default) avoids KeyError for unknown events
• dict.copy + update shallow-merges records
• Dict comprehension inverts mapping when values are unique
• Callable values turn dicts into dispatch tables

Deep Dive

How It Works

• Hash table - Keys hashed to buckets; open addressing resolves collisions.
• Insertion order - Iteration order matches insert order (re-insert moves key to end in 3.7+).
• Views - keys(), values(), items() are dynamic views, not snapshots.
• Equality - Two dicts equal if same key-value pairs regardless of order.
• fromkeys - dict.fromkeys(keys, default) builds dict with shared default caution.

Merge Options

Python Notes

# setdefault only when missing
counts: dict[str, int] = {}
counts.setdefault("a", 0)
counts["a"] += 1
 
# pop with default
value = config.pop("missing", None)

Gotchas

• Mutable values shared via fromkeys - dict.fromkeys(keys, []) shares one list. Fix: Comprehension with fresh mutable.
• Iterating keys then deleting - RuntimeError if size changes during iteration. Fix: list(d) snapshot first.
• Using float NaN as key - NaN != NaN breaks uniqueness assumptions. Fix: Avoid or normalize.
• Large dict memory - Every key object stored. Fix: Consider DB, disk index, or __slots__ objects for records.
• Relying on order for equality tests - Order differs across constructions. Fix: Compare as dicts, not key lists.

Alternatives

FAQs

Related

• Sets & Frozensets - complementary uniqueness ops
• collections Module - defaultdict, Counter
• Immutability & Hashability - valid keys
• TypedDict & NamedTuple - typed records

External Related Links

• Python Tutorial (Official) - Official beginner-to-intermediate tutorial.
• Python Standard Library Reference - Complete documentation for built-in modules and functions.
• Real Python - In-depth tutorials, courses, and practical guides.
• Fluent Python (2nd Edition) - Intermediate to advanced Python idioms (Luciano Ramalho).
• Python Crash Course (Penguin Random House) - Same title via publisher.

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.