
A Python `dict` is a mapping from keys to values. Keys must be hashable - strings, numbers, and tuples all work, but lists and other dicts do not. You write a dict literal with curly braces: `{"a": 1, "b": 2}`. Insertion order is preserved (guaranteed since Python 3.7), so iterating a dict always yields keys in the order they were added.

<ExamplePair>
<ExampleProse>

`d[key]` reads a value and raises `KeyError` if the key is missing. `d.get(key)` returns `None` instead of raising, and `d.get(key, default)` returns a custom fallback. Use `.get()` when a missing key is a normal case; use `d[key]` when missing keys are a bug you want to catch immediately.

</ExampleProse>
<ExampleCode>

```python
d = {"name": "Ada", "lang": "Python"}

d["name"]            # "Ada"
d["missing"]         # KeyError: 'missing'

d.get("name")        # "Ada"
d.get("missing")     # None
d.get("missing", 0)  # 0

# Membership check
"name" in d   # True
"age" in d    # False

# Iterating
for key, value in d.items():
    print(key, "->", value)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`collections.defaultdict` creates a missing value automatically when you access a key for the first time. Pass it a callable (like `list` or `int`) and it calls that callable to build the default. This is the standard way to bucket items into groups without checking "does this key exist yet?" on every iteration.

</ExampleProse>
<ExampleCode>

```python
from collections import defaultdict

# Group words by their first letter
words = ["apple", "avocado", "banana", "blueberry", "cherry"]

groups = defaultdict(list)
for word in words:
    groups[word[0]].append(word)

dict(groups)
# {"a": ["apple", "avocado"], "b": ["banana", "blueberry"], "c": ["cherry"]}

# Count occurrences with int default (starts at 0)
counter = defaultdict(int)
for ch in "mississippi":
    counter[ch] += 1

dict(counter)
# {"m": 1, "i": 4, "s": 4, "p": 2}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Python 3.9 introduced `|` to merge two dicts into a new one, and `|=` to merge in place. When keys overlap, the right-hand dict wins. This replaces the older `{**a, **b}` idiom, which still works but is harder to read at a glance.

</ExampleProse>
<ExampleCode>

```python
defaults = {"timeout": 30, "retries": 3, "debug": False}
overrides = {"timeout": 10, "debug": True}

# Merge into a new dict (right side wins on conflict)
config = defaults | overrides
config  # {"timeout": 10, "retries": 3, "debug": True}

# In-place merge (mutates defaults)
defaults |= overrides

# Equivalent older syntax
config = {**defaults, **overrides}

# setdefault: set key only if not already present
config.setdefault("timeout", 60)   # returns 10, does not overwrite
config.setdefault("log_level", "INFO")  # inserts "INFO"
```

</ExampleCode>
</ExamplePair>

<InProduction>
Insertion order is part of the language since Python 3.7 - `OrderedDict` is now reserved for the rare case needing `move_to_end()` or order-sensitive equality. The `|` operator merges dicts non-destructively (3.9+) and replaces `{**a, **b}` for clarity. `dict.setdefault(k, [])` is a one-line read-through cache idiom; for hot paths `defaultdict(list)` is faster because it skips the key lookup. See the [read-through cache pattern](/patterns/read-through-cache) for how this scales to a production caching layer.
</InProduction>


Python dict basics: safe access with .get(), defaultdict bucketing, merging with |, and the setdefault idiom.

Dicts


A Python `set` is an unordered collection of unique, hashable values. Two elements are "the same" if they compare equal and share the same hash. Sets are useful for membership testing (`x in s` is O(1)), deduplication, and set-algebra operations. `frozenset` is the immutable variant - it can be used as a dict key or a member of another set.

<ExamplePair>
<ExampleProse>

Set literals use curly braces with values inside: `{1, 2, 3}`. There is one important trap: `{}` is an empty *dict*, not an empty set. To create an empty set you must write `set()`. This silent type confusion is a real source of bugs because `{}` and `set()` look similar in code review.

</ExampleProse>
<ExampleCode>

```python
s = {1, 2, 3}
type(s)   # <class 'set'>

# The empty-set trap
empty_dict = {}        # dict, NOT a set
type(empty_dict)       # <class 'dict'>

empty_set = set()      # correct empty set
type(empty_set)        # <class 'set'>

# Basic operations
s.add(4)       # {1, 2, 3, 4}
s.remove(2)    # {1, 3, 4}   -- raises KeyError if missing
s.discard(99)  # no-op if missing, no error
3 in s         # True
len(s)         # 3
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Set algebra uses operators that mirror the mathematical notation. Union (`|`) gives all elements from both sets. Intersection (`&`) gives only elements present in both. Difference (`-`) removes elements of the right set from the left. Symmetric difference (`^`) gives elements that are in one set but not the other.

</ExampleProse>
<ExampleCode>

```python
a = {1, 2, 3, 4}
b = {3, 4, 5, 6}

a | b   # {1, 2, 3, 4, 5, 6}  -- union
a & b   # {3, 4}               -- intersection
a - b   # {1, 2}               -- difference (in a but not b)
b - a   # {5, 6}               -- difference (in b but not a)
a ^ b   # {1, 2, 5, 6}         -- symmetric difference

# Subset and superset checks
{1, 2} <= a    # True  (subset)
a >= {1, 2}    # True  (superset)
{1, 2} < a     # True  (proper subset, not equal)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Converting a list to a set and back is the fastest way to deduplicate, but it does not preserve order. For an "all needles present?" check, `set(needles) <= set(haystack)` is cleaner than a loop and runs in O(n+m) time. `frozenset` is the immutable variant and can be used wherever a hashable value is needed.

</ExampleProse>
<ExampleCode>

```python
# Deduplication (order not preserved)
xs = [3, 1, 4, 1, 5, 9, 2, 6, 5, 3]
unique = list(set(xs))
# e.g. [1, 2, 3, 4, 5, 6, 9]  -- order is arbitrary

# "All needles present?" check
required = {"name", "email", "age"}
provided = {"name", "email", "age", "country"}
required <= set(provided)   # True

# frozenset as a dict key
roles = frozenset({"admin", "editor"})
permissions = {
    frozenset({"admin"}):          ["read", "write", "delete"],
    frozenset({"admin", "editor"}): ["read", "write"],
}
permissions[roles]   # ["read", "write"]
```

</ExampleCode>
</ExamplePair>

<InProduction>
`{}` is an empty *dict*, not an empty set - use `set()` for empty sets; only `{1, 2, 3}` with elements is a set literal, and the silent type confusion bites code review. Sets require elements to be hashable, so lists and dicts cannot be set members; for a "set of records" reach for tuples of items or `frozenset(d.items())`.
</InProduction>


Python set basics: literals, the empty-set {} trap, set algebra, deduplication, and frozenset for immutable membership.

Sets


A Python `tuple` is an immutable, ordered sequence of values. You create one with parentheses (`(1, 2, 3)`) or just by separating values with commas (`1, 2, 3` - the parentheses are optional). Because tuples are immutable they can be used as dictionary keys and set members, which plain lists cannot.

<ExamplePair>
<ExampleProse>

Packing is creating a tuple; unpacking is pulling its values into separate names. You can pack without parentheses: `t = 1, 2` creates a two-tuple. To unpack, put the same number of names on the left: `a, b = t`. The one-tuple trap: `(1)` is just the integer 1 wrapped in parentheses. You need a trailing comma to make a real one-element tuple: `(1,)`.

</ExampleProse>
<ExampleCode>

```python
# Packing - parentheses are optional
t = 1, 2
t        # (1, 2)

# Unpacking
a, b = t
a  # 1
b  # 2

# Swap without a temp variable
a, b = b, a

# One-tuple trap
(1)     # just int 1
(1,)    # tuple with one element
type((1,))   # <class 'tuple'>
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The `*rest` syntax in unpacking lets you collect "the middle" or "the tail" into a list. `first, *middle, last = seq` splits the sequence at both ends, regardless of how long the middle is. The starred name always collects into a plain list even though it came from a tuple.

</ExampleProse>
<ExampleCode>

```python
seq = (1, 2, 3, 4, 5)

first, *rest = seq
first   # 1
rest    # [2, 3, 4, 5]  -- list, not tuple

first, *middle, last = seq
first   # 1
middle  # [2, 3, 4]
last    # 5

# Useful for splitting at known positions
host, *path_parts = "api.example.com/users/42".split("/")
host        # "api.example.com"
path_parts  # ["users", "42"]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`typing.NamedTuple` lets you give names to tuple positions and add type annotations. You access fields by name (`point.x`) instead of index (`point[0]`), which makes code easier to read. The class still behaves as a tuple - you can unpack it, use it as a dict key, and compare it with `==`. For legacy code you may see `collections.namedtuple`, which has no type annotation support.

</ExampleProse>
<ExampleCode>

```python
from typing import NamedTuple

class Point(NamedTuple):
    x: float
    y: float

p = Point(3.0, 4.0)
p.x       # 3.0
p.y       # 4.0
p[0]      # 3.0  -- still a tuple underneath

# Works as a dict key
distances = {Point(0.0, 0.0): "origin", Point(1.0, 0.0): "unit"}

# Unpacks like a plain tuple
x, y = p
```

</ExampleCode>
</ExamplePair>

<InProduction>
Tuple immutability is shallow - `t = ([], [])` lets you mutate `t[0].append(1)` even though `t` itself cannot be rebound; if you need deep immutability, use `frozenset` for sets, freeze contents explicitly, or build with `@dataclass(frozen=True)`. Prefer `typing.NamedTuple` or `@dataclass(frozen=True, slots=True)` over `collections.namedtuple` in new code - you get type checking, stricter equality semantics, and IDE autocomplete on field names.
</InProduction>


Python tuple basics: packing and unpacking, the one-tuple comma, *rest unpacking, and typing.NamedTuple for named fields.