
The smallest runnable Python program prints a message to the console. Run it with `python file.py`, or add a shebang line (`#!/usr/bin/env python3`) to make the file executable directly. The `if __name__ == "__main__":` guard lets the same file act as both a runnable script and an importable module.

<ExamplePair>
<ExampleProse>

`print()` writes its argument to stdout, followed by a newline. This is how Python says hello to the world.

</ExampleProse>
<ExampleCode>

```python
print("Hello, World!")
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Running the script produces:

</ExampleProse>
<ExampleCode>

```shell
Hello, World!
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Wrapping your script logic inside `if __name__ == "__main__":` lets the file be imported by another module without running the script body. `__name__` is the module's name when imported, or `"__main__"` when run directly.

</ExampleProse>
<ExampleCode>

```python
def greet(name):
    print(f"Hello, {name}!")

if __name__ == "__main__":
    greet("World")
```

</ExampleCode>
</ExamplePair>

<InProduction>
`print()` is fine for scripts and CLIs. Production services need the stdlib `logging` module (or structlog) so log levels, structured fields, and request-correlation IDs survive into Datadog or Loki. Plain `print()` writes to stdout with no level metadata and cannot be silenced without code changes.
</InProduction>


The smallest runnable Python program - printing a message and understanding the script guard pattern.

Hello World


Python has six built-in scalar types: `int`, `float`, `str`, `bool`, `None`, and `bytes`. Everything in Python is an object, so every value carries its type with it. `type(x)` returns the object's class; `isinstance(x, SomeType)` tests membership, including subclasses.

<ExamplePair>
<ExampleProse>

Each scalar type has a literal form. `type()` returns the class of any value.

</ExampleProse>
<ExampleCode>

```python
type(42)        # <class 'int'>
type(3.14)      # <class 'float'>
type("hi")      # <class 'str'>
type(True)      # <class 'bool'>
type(None)      # <class 'NoneType'>
type(b"bytes")  # <class 'bytes'>
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`isinstance(x, T)` is the idiomatic way to check a value's type at runtime because it respects inheritance. `bool` is a subclass of `int`, so `isinstance(True, int)` is `True`. This can produce surprises if you expect the check to be strict.

</ExampleProse>
<ExampleCode>

```python
isinstance(42, int)      # True
isinstance(3.14, float)  # True
isinstance("hi", str)    # True

# bool is a subclass of int
isinstance(True, int)    # True  <- not False
isinstance(True, bool)   # True
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`==` compares values; `is` compares identity (whether two names point to the exact same object in memory). Use `==` for value comparison and `is` only for `None`, `True`, `False`, and sentinel singletons.

</ExampleProse>
<ExampleCode>

```python
1 == 1.0    # True  - same value, different types
1 is 1.0    # False - different objects

x = None
x is None   # True  - canonical None check
x == None   # True  - works, but non-idiomatic
```

</ExampleCode>
</ExamplePair>

<InProduction>
`bool` is a subclass of `int` (`True == 1`, `isinstance(True, int)` is `True`) and this leaks into JSON serialisation, `sum()`, and dict keys - a function expecting an integer silently accepts `True`. Use `is` only for `None`, `True`, `False`, and sentinel singletons; use `==` for value comparison everywhere else.
</InProduction>


Python's built-in scalar types: int, float, str, bool, None, and bytes - with identity versus equality.

Values


Variables in Python are name bindings, not declarations. An assignment `x = 1` creates a name `x` that points to the integer `1`; re-assigning `x = 2` rebinds the name to a different object. The original object is unchanged, and Python's garbage collector reclaims it if no other names point to it.

<ExamplePair>
<ExampleProse>

Simple assignment, multiple assignment on one line, and in-place swap all work without a temporary variable.

</ExampleProse>
<ExampleCode>

```python
x = 10
a, b = 1, 2        # multiple assignment
a, b = b, a        # swap without a temp variable

print(a, b)        # 2 1
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

When a function reads a variable, Python searches scopes in LEGB order: Local, Enclosing, Global, Built-in. A function can read an outer variable without any extra keyword.

</ExampleProse>
<ExampleCode>

```python
x = "global"

def show():
    print(x)   # reads the global x - no keyword needed

show()         # global
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The `UnboundLocalError` trap: if a function assigns to a name anywhere in its body, Python treats that name as local for the *entire* function, even before the assignment line. Reading it before the assignment raises `UnboundLocalError`. Use `nonlocal` (for a name in an enclosing function) or `global` (for a module-level name) when a rebinding is intentional.

</ExampleProse>
<ExampleCode>

```python
count = 0

def broken():
    print(count)  # UnboundLocalError! assignment below makes count local
    count = count + 1

def fixed():
    global count
    print(count)  # 0 - now unambiguously the global
    count = count + 1
```

</ExampleCode>
</ExamplePair>

<InProduction>
Python rebinds names; it does not declare them. A function that assigns to `x` shadows any outer `x` for the entire function body, even before the assignment line - reading it earlier raises `UnboundLocalError`. Reach for `nonlocal` only when closure state genuinely belongs to the enclosing function; class state belongs on `self`.
</InProduction>


Variables in Python are name bindings. Understand multiple assignment, LEGB scope, and the UnboundLocalError trap.

Variables


Python has three built-in numeric types: `int` (arbitrary precision - no overflow), `float` (IEEE 754 double), and `complex`. The standard library adds `decimal.Decimal` for exact decimal arithmetic and `fractions.Fraction` for rational numbers.

<ExamplePair>
<ExampleProse>

`int` in Python has no fixed size, so it never overflows. Integer division uses `//`, the remainder operator is `%`, and `pow(base, exp, mod)` computes modular exponentiation efficiently without building a huge intermediate number.

</ExampleProse>
<ExampleCode>

```python
2 ** 100          # 1267650600228229401496703205376 - exact, no overflow

10 // 3           # 3  (integer division, rounds toward negative infinity)
10 % 3            # 1  (remainder)

pow(2, 10, 1000)  # 24  (2**10 mod 1000, fast even for huge exponents)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`float` uses IEEE 754 binary representation, which cannot represent most decimal fractions exactly. The classic example: `0.1 + 0.2` is not `0.3`. Use `math.isclose(a, b)` when comparing floats by tolerance rather than exact equality.

</ExampleProse>
<ExampleCode>

```python
import math

0.1 + 0.2           # 0.30000000000000004
0.1 + 0.2 == 0.3    # False

math.isclose(0.1 + 0.2, 0.3)           # True  (relative tolerance 1e-9)
math.isclose(0.1 + 0.2, 0.3, rel_tol=1e-6)  # True
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`decimal.Decimal` stores numbers as exact decimal fractions - the same way humans write them. This makes it the right choice for money and accounting, where rounding rules matter. Pass values as strings to avoid inheriting float imprecision at construction time.

</ExampleProse>
<ExampleCode>

```python
from decimal import Decimal, ROUND_HALF_EVEN, getcontext

Decimal("0.1") + Decimal("0.2")   # Decimal('0.3')  - exact

# Set rounding mode for the current thread's context
getcontext().rounding = ROUND_HALF_EVEN

price = Decimal("19.995")
price.quantize(Decimal("0.01"))   # Decimal('20.00')  - banker's rounding
```

</ExampleCode>
</ExamplePair>

<InProduction>
Never store monetary values as `float` - `0.1 + 0.2 != 0.3` ships production bugs that staging never catches; use `decimal.Decimal` with an explicit rounding mode (`ROUND_HALF_EVEN` for accounting). The small-integer interning trap means `a is b` returns `True` for integers in roughly -5 to 256 but `False` for larger values; always use `==` for numeric value comparison.
</InProduction>


Python's three numeric types: int (arbitrary precision), float (IEEE 754), and complex - plus Decimal for exact arithmetic.

Numbers


A Python `str` is an immutable sequence of Unicode code points - not bytes. The separate `bytes` type holds raw binary data. Converting between them requires an explicit `.encode()` call (str to bytes) or `.decode()` call (bytes to str), and you must name the encoding each time.

<ExamplePair>
<ExampleProse>

f-strings (formatted string literals) embed expressions directly inside `{}`. They support Python's full format-spec syntax for alignment, padding, and number formatting - the same spec used by `format()` and `str.format()`.

</ExampleProse>
<ExampleCode>

```python
name = "Ada"
f"Hello, {name}!"         # 'Hello, Ada!'

value = 3.14159
f"{value:.2f}"            # '3.14'  (2 decimal places)

n = 42
f"{n:>10}"                # '        42'  (right-aligned in 10 chars)
f"{n:0>10}"               # '0000000042'  (zero-padded)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`str` and `bytes` are separate types and Python never converts between them automatically. `.encode(encoding)` produces `bytes`; `.decode(encoding)` produces `str`. If the bytes do not match the encoding you name, Python raises `UnicodeDecodeError` - pass `errors="replace"` to substitute replacement characters instead of crashing.

</ExampleProse>
<ExampleCode>

```python
s = "héllo"
b = s.encode("utf-8")       # b'h\xc3\xa9llo'  (5 chars -> 6 bytes)

b.decode("utf-8")            # 'héllo'

# Wrong codec raises UnicodeDecodeError
b.decode("ascii")            # UnicodeDecodeError: invalid start byte

# Safety valve: replace undecodable bytes with the replacement character
b.decode("ascii", errors="replace")   # 'h��llo'
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`len(s)` counts Unicode code points, not characters as humans perceive them (graphemes). A single visible character can be multiple code points when combining marks are used - for example, the letter `a` followed by a combining accent. Naive slicing can split a grapheme in the middle. Normalising with `unicodedata.normalize("NFC", s)` folds as many combining sequences as possible into single composed code points before slicing or comparing.

</ExampleProse>
<ExampleCode>

```python
import unicodedata

# 'a' + combining acute accent = two code points, one visible character
composed = "á"          # á  (precomposed, 1 code point)
decomposed = "á"       # a + combining acute, 2 code points

len(composed)                # 1
len(decomposed)              # 2

# Normalize to NFC before comparing or slicing user input
unicodedata.normalize("NFC", decomposed) == composed   # True
```

</ExampleCode>
</ExamplePair>

<InProduction>
f-strings evaluate arbitrary expressions inside `{...}` - never format untrusted input as if it were a template string; use `str.format_map` with a restricted mapping, or better, keep user input as data rather than embedding it in format strings. `len(s)` counts code points, not graphemes - naive slicing of user input with emoji or combining marks produces mojibake; normalise with `unicodedata.normalize("NFC", s)` or reach for the `regex` package before truncating display strings.
</InProduction>


Python str is an immutable sequence of Unicode code points, not bytes. Encoding, f-strings, and grapheme-aware slicing.

Strings


A Python `bool` is one of two values: `True` or `False`. Comparisons (`==`, `<`, `in`) and logical operators (`and`, `or`, `not`) produce booleans. Beyond the two bool literals, many other values behave as true or false in a boolean context - this is called "truthiness."

<ExamplePair>
<ExampleProse>

`bool(x)` converts any value to its boolean equivalent. The falsy values are: `0`, `0.0`, `""`, `b""`, `[]`, `()`, `{}`, `set()`, and `None`. Every other value is truthy. You can rely on this in `if` conditions without calling `bool()` explicitly.

</ExampleProse>
<ExampleCode>

```python
# All falsy
bool(0)     # False
bool("")    # False
bool([])    # False
bool({})    # False
bool(None)  # False

# All truthy
bool(1)         # True
bool("hello")   # True
bool([0])       # True  - a list with one item, even if the item is 0
bool(0.001)     # True
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`and` and `or` do not necessarily return `True` or `False` - they return one of their operands. `or` returns the first truthy operand (or the last operand if all are falsy). `and` returns the first falsy operand (or the last operand if all are truthy). This short-circuit behaviour is useful for defaults, but it also creates a common footgun.

</ExampleProse>
<ExampleCode>

```python
# or returns the first truthy value
0 or "fallback"         # 'fallback'
"primary" or "fallback" # 'primary'
[] or [1, 2]            # [1, 2]

# and returns the first falsy value
1 and 2                 # 2   (all truthy, returns last)
0 and "unreachable"     # 0   (0 is falsy, short-circuits)

# Footgun: silently uses the fallback when 0 or "" is a valid value
count = 0
display = count or "no items"   # 'no items' -- wrong when count is a valid 0
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`is` checks identity - whether two names refer to the same object in memory. `==` checks value equality. For `None`, `is` is the canonical idiom and is faster. For `True` and `False`, use truthiness (`if x:`) rather than `is True` or `is False` - they are fragile if the value is a truthy non-bool.

</ExampleProse>
<ExampleCode>

```python
x = None
x is None       # True  - canonical None check
x == None       # True  - works, but non-idiomatic

# is True / is False are footguns
result = 1      # truthy, but not the bool True
result == True  # True
result is True  # False  - 1 and True are different objects

# Prefer plain truthiness checks
if result:       # idiomatic - "do I have a value?"
    pass
if result is not None:  # idiomatic - "was something provided?"
    pass
```

</ExampleCode>
</ExamplePair>

<InProduction>
`if my_list:` treats empty containers as false - convenient for "do I have items?", but catastrophic when `0`, `""`, or `[]` is a legitimate value (a counter starting at zero, an empty form field, a response body that is intentionally empty). Use `if x is not None:` when the distinction between "absent" and "falsy but present" matters. `and`/`or` return operands not booleans, so `default = config_value or "fallback"` silently uses the fallback for `0`, `""`, and `[]`.
</InProduction>


Python bool - True and False, truthy and falsy values, short-circuit operators, and when to use is vs ==.

Booleans and Truthiness


Python's branching uses `if`, `elif`, and `else`. For a quick inline choice there is the conditional expression (`a if condition else b`). Since Python 3.10 there is also structural pattern matching with `match` and `case`, which matches on the shape and contents of a value rather than just equality.

<ExamplePair>
<ExampleProse>

An `if`/`elif`/`else` chain evaluates each condition in order and runs the first branch that is true. `elif` is short for "else if" - you can have as many as you need. The `else` branch runs when no earlier condition matched.

</ExampleProse>
<ExampleCode>

```python
def classify_status(code: int) -> str:
    if code < 200:
        return "informational"
    elif code < 300:
        return "success"
    elif code < 400:
        return "redirect"
    elif code < 500:
        return "client error"
    else:
        return "server error"

classify_status(200)  # 'success'
classify_status(404)  # 'client error'
classify_status(503)  # 'server error'
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The conditional expression (`value_if_true if condition else value_if_false`) fits a two-way choice on one line. It is useful for short, readable choices. Nesting conditional expressions inside one another is a code-review smell - use a regular `if`/`else` block instead.

</ExampleProse>
<ExampleCode>

```python
n = 7
label = "even" if n % 2 == 0 else "odd"
label  # 'odd'

# Readable: one level deep
status = "active" if user.is_logged_in else "guest"

# Avoid: nested ternaries are hard to read at a glance
# result = "a" if x else ("b" if y else "c")  -- use if/elif/else
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`match`/`case` (Python 3.10+) is structural pattern matching - it inspects the shape and contents of a value, not just its equality. A `case` clause can destructure a dict, pull out fields by name, and bind them as local variables in one step. One important detail: `case x:` with a bare name always binds (it never compares), so use a dotted name like `case Color.RED:` to compare against a constant.

</ExampleProse>
<ExampleCode>

```python
def handle(event: dict) -> str:
    match event:
        case {"type": "click", "x": x, "y": y}:
            return f"click at ({x}, {y})"
        case {"type": "keypress", "key": key}:
            return f"key: {key}"
        case {"type": str(t)}:
            return f"unknown event type: {t}"
        case _:
            return "malformed event"

handle({"type": "click", "x": 10, "y": 20})   # 'click at (10, 20)'
handle({"type": "keypress", "key": "Enter"})   # 'key: Enter'
```

</ExampleCode>
</ExamplePair>

<InProduction>
`match` is structural pattern matching, not a C-style switch - it matches shape, not just equality. Reach for it on tagged dicts, parsed JSON, AST nodes, and message envelopes where you want to destructure and bind fields in one step; for plain equality dispatch a chain of `elif` is clearer. `case x:` with a bare name binds rather than compares - use a dotted name (`case Color.RED:`) or a guard (`case x if x == sentinel:`) when you need literal comparison.
</InProduction>


Python branching with if/elif/else, conditional expressions, and structural pattern matching with match/case (3.10+).

Conditionals


Python has two loop forms: `for` iterates over a collection or range, and `while` runs as long as a condition is true. Both support `break` (exit early) and `continue` (skip to the next iteration). Both also accept an `else` clause - uncommon but worth knowing.

<ExamplePair>
<ExampleProse>

`for x in xs:` works with any iterable - lists, ranges, strings, dicts, files. `range(n)` produces integers 0 through n-1. `enumerate(xs)` gives you each item paired with its index, removing the need for a separate counter. `zip(a, b)` steps through two iterables in parallel, pairing items at the same position.

</ExampleProse>
<ExampleCode>

```python
fruits = ["apple", "banana", "cherry"]

# Basic for loop
for fruit in fruits:
    print(fruit)

# range: 0, 1, 2, 3, 4
for i in range(5):
    print(i)

# enumerate: index + value
for i, fruit in enumerate(fruits):
    print(i, fruit)   # 0 apple, 1 banana, 2 cherry

# zip: iterate two lists in parallel
prices = [1.20, 0.50, 2.00]
for fruit, price in zip(fruits, prices):
    print(f"{fruit}: ${price:.2f}")
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`while` runs as long as its condition is true. Use `break` to exit early when a goal is reached, and `continue` to skip the rest of the loop body for the current iteration. A `while True:` loop with an explicit `break` is a common pattern for "keep reading until a sentinel value."

</ExampleProse>
<ExampleCode>

```python
# Read lines until the user types "quit"
lines = []
while True:
    line = input("> ")
    if line == "quit":
        break
    lines.append(line)

print(f"Collected {len(lines)} line(s)")

# continue: skip blank lines
for line in lines:
    if not line.strip():
        continue
    process(line)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Both `for` and `while` accept an optional `else` clause. The `else` block runs when the loop finishes normally - that is, without hitting a `break`. It reads as "no early exit occurred." Most teams avoid this because readers unfamiliar with Python expect `else` to mean "condition was false," not "loop completed." A sentinel variable is usually clearer.

</ExampleProse>
<ExampleCode>

```python
# for/else: runs the else block only when break was never hit
def find(items: list, target: int) -> str:
    for item in items:
        if item == target:
            break
    else:
        return "not found"
    return f"found {target}"

find([1, 2, 3], 2)  # 'found 2'
find([1, 2, 3], 9)  # 'not found'

# Same logic, clearer with a sentinel variable
def find_v2(items: list, target: int) -> str:
    found = False
    for item in items:
        if item == target:
            found = True
            break
    return f"found {target}" if found else "not found"
```

</ExampleCode>
</ExamplePair>

<InProduction>
The `for`/`else` clause runs when the loop exits without `break` - it reads as "no match found." Most teams use a sentinel variable instead because `else` on a loop is widely misunderstood and will surprise reviewers unfamiliar with Python. Modifying a list while iterating it (`for x in xs: xs.remove(x)`) skips elements because the iterator's position shifts after each removal; iterate over a copy (`for x in xs[:]:`) or build a new list with a comprehension.
</InProduction>


Python for and while loops, enumerate and zip for cleaner iteration, break and continue, and the for/else clause.

Loops


A Python `list` is a mutable, ordered sequence of items. You create one with square brackets (`[1, 2, 3]`) or by calling `list(iterable)`. Lists grow with `.append()` and `.extend()`, shrink with `.pop()` and `.remove()`, and can be sliced with `xs[start:stop]`.

<ExamplePair>
<ExampleProse>

The most common list operations: `.append(x)` adds one item to the end, `.extend(iterable)` appends every item from another iterable, `.insert(i, x)` inserts at a specific index, `.pop()` removes and returns the last item, and `.remove(x)` removes the first occurrence of a value. Appending and popping at the right end (index -1) is O(1) - fast regardless of list size. Inserting or removing at the left end (index 0) is O(n) because every other item must shift.

</ExampleProse>
<ExampleCode>

```python
xs = [1, 2, 3]

xs.append(4)        # [1, 2, 3, 4]
xs.extend([5, 6])   # [1, 2, 3, 4, 5, 6]
xs.insert(0, 0)     # [0, 1, 2, 3, 4, 5, 6]  -- O(n), shifts everything
xs.pop()            # returns 6, list is [0, 1, 2, 3, 4, 5]
xs.remove(0)        # removes first 0, list is [1, 2, 3, 4, 5]

len(xs)             # 5
3 in xs             # True
xs.index(3)         # 2  (position of the value 3)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Slicing returns a new list containing the selected items. `xs[a:b]` gives items from index `a` up to (but not including) `b`. Negative indices count from the end: `xs[-1]` is the last item. `xs[::-1]` steps backwards and returns a reversed copy. `xs[:]` copies the entire list shallowly - useful when you need a separate list that starts with the same values.

</ExampleProse>
<ExampleCode>

```python
xs = [10, 20, 30, 40, 50]

xs[1:3]     # [20, 30]          -- items at index 1 and 2
xs[:2]      # [10, 20]          -- first two
xs[2:]      # [30, 40, 50]      -- from index 2 to end
xs[-1]      # 50                -- last item
xs[::-1]    # [50, 40, 30, 20, 10]  -- reversed copy
xs[:]       # [10, 20, 30, 40, 50]  -- shallow copy

copy = xs[:]
copy.append(99)
xs   # [10, 20, 30, 40, 50]  -- original unchanged
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`[[]] * n` looks like it creates `n` independent empty lists, but it actually creates `n` references to the same inner list. Appending to any one of them mutates all of them. The fix is a list comprehension: `[[] for _ in range(n)]` calls `[]` once per iteration, producing `n` distinct list objects.

</ExampleProse>
<ExampleCode>

```python
# Bug: all three rows point to the same list
grid = [[]] * 3
grid[0].append(1)
grid  # [[1], [1], [1]]  -- all three changed!

# Fix: comprehension creates a new [] each iteration
grid = [[] for _ in range(3)]
grid[0].append(1)
grid  # [[1], [], []]  -- only row 0 changed

# Same trap with any mutable default
row = [0] * 5     # [0, 0, 0, 0, 0]  -- safe: ints are immutable
matrix = [[0] * 5 for _ in range(3)]  # correct 3x5 grid
```

</ExampleCode>
</ExamplePair>

<InProduction>
`[[]] * n` creates n references to the same inner list - appending to one mutates all of them. Use `[[] for _ in range(n)]` instead. Lists are O(1) for `.append()` and `.pop()` at the right end but O(n) for `.pop(0)` and `.insert(0, x)` because every item must shift; for FIFO queues reach for `collections.deque`, which is O(1) at both ends.
</InProduction>


Python list basics: append, extend, slicing, shallow copies, and the shared-reference trap with [[]] * n.

Lists


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.

Tuples


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 comprehension builds a collection from an iterable in a single expression. Python has four forms: list (`[...]`), dict (`{k: v ...}`), set (`{v ...}`), and generator (`(...)`). They replace many for-loop-then-append patterns and express the intent more directly.

<ExamplePair>
<ExampleProse>

List, dict, and set comprehensions all follow the same shape: `[expression for item in iterable if condition]`. The `if` part is optional. Each form produces a different collection type.

</ExampleProse>
<ExampleCode>

```python
xs = [1, 2, 3, 4, 5]
d = {"a": 1, "b": 2, "c": 3}

# List comprehension
doubled = [x * 2 for x in xs]
doubled  # [2, 4, 6, 8, 10]

# With a filter
evens = [x for x in xs if x % 2 == 0]
evens  # [2, 4]

# Dict comprehension
scaled = {k: v * 2 for k, v in d.items()}
scaled  # {"a": 2, "b": 4, "c": 6}

# Set comprehension (duplicates removed automatically)
last_digits = {x % 10 for x in [11, 21, 31, 22]}
last_digits  # {1, 2}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A generator expression looks like a list comprehension but uses parentheses instead of square brackets. It is lazy: values are produced one at a time as the consumer asks for them, so the whole sequence is never held in memory at once. This makes generator expressions ideal when feeding functions that iterate once, like `sum()`, `any()`, `all()`, or `max()`.

</ExampleProse>
<ExampleCode>

```python
xs = range(1_000_000)

# List comprehension: builds the entire list in memory first
total_list = sum([x * 2 for x in xs])

# Generator expression: produces values lazily, uses constant memory
total_gen = sum(x * 2 for x in xs)

# Both give the same result, but the generator uses far less memory.
# When passing a generator expression as the sole argument to a
# function, you can drop the extra parentheses:
total_gen = sum(x * 2 for x in xs)   # not sum((x * 2 for x in xs))

any(x > 999_990 for x in xs)   # True  (stops early on first match)
all(x >= 0 for x in xs)        # True
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The walrus operator (`:=`, added in Python 3.8) assigns a value inside an expression. In a comprehension it lets you call an expensive function once and both filter and use the result in a single pass - no need for a temporary list or a two-step filter-then-transform.

</ExampleProse>
<ExampleCode>

```python
import re

logs = [
    "ERROR: disk full",
    "INFO: started",
    "ERROR: timeout",
    "DEBUG: ping",
]

# Without walrus: re.search called twice per item
errors = [line for line in logs if re.search(r"ERROR: (.+)", line)]

# With walrus: call once, bind to `m`, filter on it, use it
messages = [
    m.group(1)
    for line in logs
    if (m := re.search(r"ERROR: (.+)", line)) is not None
]
messages  # ["disk full", "timeout"]
```

</ExampleCode>
</ExamplePair>

<InProduction>
A generator expression `(x * 2 for x in xs)` is lazy and constant-memory - reach for it over a list comprehension when feeding `sum()`, `any()`, `all()`, or any consumer that iterates once. Two levels of nesting in a comprehension are readable; three are not - extract the inner level to a named function or a plain `for` loop. The walrus operator (`:=`) filters and binds in one pass, which is its clearest use case; overusing it in complex expressions hurts readability more than it helps.
</InProduction>


List, dict, set, and generator comprehensions: concise collection building, generator laziness, and the walrus operator for filter-and-bind.

Comprehensions


A function is defined with `def name(parameters):`. Python functions support positional arguments, keyword arguments, default values, `*args` for variadic positional arguments, and `**kwargs` for variadic keyword arguments. Two separator symbols - `/` and `*` - let you control exactly how callers may pass each argument.

<ExamplePair>
<ExampleProse>

Placing `*` in a parameter list means every argument after it must be passed by name (keyword-only). Placing `/` means every argument before it must be passed by position (positional-only). These are not just style rules - Python enforces them at call time. Keyword-only arguments make call sites self-documenting and prevent argument-order bugs.

</ExampleProse>
<ExampleCode>

```python
# timeout and retries are keyword-only (after *)
def fetch(url, *, timeout=10, retries=3):
    ...

fetch("https://example.com")                # ok
fetch("https://example.com", timeout=5)     # ok
fetch("https://example.com", 5)             # TypeError: too many positional arguments

# x is positional-only (before /); y can be either
def transform(x, /, y):
    return x + y

transform(1, 2)       # ok - both positional
transform(1, y=2)     # ok - y as keyword
transform(x=1, y=2)   # TypeError: x is positional-only

# Combining both: url is positional-only, timeout and retries are keyword-only
def request(url, /, *, timeout=10, retries=3):
    ...
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Default argument values are evaluated once when Python reads the `def` statement, not each time the function is called. For immutable defaults like strings and numbers this does not matter. For mutable objects like lists and dicts it causes a subtle bug: every call that omits the argument shares the same object. The fix is to use `None` as the sentinel and build the mutable default inside the function body.

</ExampleProse>
<ExampleCode>

```python
# Bug: items is created once; all calls share the same list
def append_item(value, items=[]):
    items.append(value)
    return items

append_item(1)   # [1]
append_item(2)   # [1, 2]  -- not [2]!
append_item(3)   # [1, 2, 3]

# Fix: use None as sentinel, build the default inside the body
def append_item_fixed(value, items=None):
    if items is None:
        items = []
    items.append(value)
    return items

append_item_fixed(1)   # [1]
append_item_fixed(2)   # [2]   -- fresh list each time
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A Python function can return multiple values by returning a tuple. The caller can unpack them directly into separate names. For shapes that will be passed around or stored, a `typing.NamedTuple` adds names and type annotations without the overhead of a full class.

</ExampleProse>
<ExampleCode>

```python
from typing import NamedTuple

# Plain tuple return: works, but callers must remember the order
def divmod_plain(a, b):
    return a // b, a % b

quotient, remainder = divmod_plain(17, 5)
# quotient=3, remainder=2

# NamedTuple: adds names, type annotations, and dot-access
class DivResult(NamedTuple):
    quotient: int
    remainder: int

def divmod_named(a, b):
    return DivResult(a // b, a % b)

result = divmod_named(17, 5)
result.quotient    # 3
result.remainder   # 2

# Still unpackable like a plain tuple
q, r = divmod_named(17, 5)
```

</ExampleCode>
</ExamplePair>

<InProduction>
`def f(items=[]):` evaluates the default once at definition time - every call without an argument shares the same list across the lifetime of the program; use `def f(items=None): items = items if items is not None else []`. Functions with more than two or three positional arguments become unreadable at call sites - use `*` to make the rest keyword-only (`def fetch(url, *, timeout, retries)`); positional arguments past three are a code-review signal. See the [idempotency key pattern](/patterns/idempotency-key) for how careful parameter design makes retry-safe APIs possible.
</InProduction>


Python function signatures: keyword-only and positional-only args, the mutable-default footgun, and returning multiple values cleanly.

Functions


A closure is a function that remembers variables from the scope where it was defined, even after that scope has finished executing. A decorator is a higher-order function - a function that takes another function and returns a (usually wrapped) replacement. Python's `@decorator` syntax is shorthand for `fn = decorator(fn)`.

<ExamplePair>
<ExampleProse>

When a function is defined inside another function, it has access to the outer function's local variables. Each call to the outer function creates its own independent set of those variables, so closures built from separate calls are isolated from each other.

</ExampleProse>
<ExampleCode>

```python
def multiplier(n):
    def multiply(x):
        return x * n   # n is captured from the enclosing scope
    return multiply

double = multiplier(2)
triple = multiplier(3)

double(5)   # 10
triple(5)   # 15

# Each closure has its own n; they don't share state
double(10)  # 20
triple(10)  # 30
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Closures capture the *variable*, not the *value* at the time of capture. When a loop builds closures that all reference the same loop variable, every closure sees the variable's final value - not the value it held during that iteration. This is called late binding and is a common source of bugs. The fix is to force an early bind by using a default argument or `functools.partial`.

</ExampleProse>
<ExampleCode>

```python
# Bug: all three lambdas capture the same variable i
funcs = [lambda: i for i in range(3)]
[f() for f in funcs]   # [2, 2, 2] -- all see i=2 (final value)

# Fix 1: bind eagerly with a default argument
funcs_fixed = [lambda i=i: i for i in range(3)]
[f() for f in funcs_fixed]   # [0, 1, 2]

# Fix 2: use functools.partial
import functools

def identity(x):
    return x

funcs_partial = [functools.partial(identity, i) for i in range(3)]
[f() for f in funcs_partial]   # [0, 1, 2]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A decorator is a function that wraps another function to add behaviour before or after the call. Always apply `@functools.wraps(fn)` to the inner wrapper: without it the decorated function loses its `__name__`, `__doc__`, and signature, which breaks introspection tools, API frameworks like FastAPI, and test helpers that inspect function metadata.

</ExampleProse>
<ExampleCode>

```python
import functools
import time

def timed(fn):
    @functools.wraps(fn)   # copies __name__, __doc__, __annotations__ from fn
    def wrapper(*args, **kwargs):
        start = time.perf_counter()
        result = fn(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{fn.__name__} took {elapsed:.4f}s")
        return result
    return wrapper

@timed
def slow_add(a, b):
    """Add two numbers slowly."""
    time.sleep(0.01)
    return a + b

slow_add(2, 3)
# slow_add took 0.0101s
# 5

# Without @functools.wraps these would return "wrapper" and None:
slow_add.__name__   # "slow_add"
slow_add.__doc__    # "Add two numbers slowly."
```

</ExampleCode>
</ExamplePair>

<InProduction>
Closures capture variables, not values - `[lambda: i for i in range(3)]` produces three lambdas that all return 2; bind eagerly with `lambda i=i: i` or restructure with `functools.partial`. Always use `@functools.wraps(fn)` inside a decorator - without it the wrapped function loses `__name__`, `__doc__`, and signature, breaking every tool that introspects (Sphinx docs, FastAPI route discovery, pytest fixture injection). Stacking multiple decorators is fine; the one closest to the `def` line applies first.
</InProduction>


Closures capture enclosing variables; decorators wrap functions. Covers the late-binding-in-loops bug and correct use of @functools.wraps.

Closures and Decorators


A generator is a function that uses `yield` instead of `return`. Calling it does not run the body - it returns a generator object, which is an iterator that produces values one at a time when asked. This means Python never needs to hold the entire sequence in memory, making generators the language-level primitive for streaming and pipelines.

<ExamplePair>
<ExampleProse>

A generator function looks like a regular function but contains at least one `yield` statement. Each time the caller calls `next()` on the generator object (or the `for` loop does it automatically), the function body runs up to the next `yield`, pauses, and hands the value back. The function's local state is frozen between yields.

</ExampleProse>
<ExampleCode>

```python
def squares(n):
    for i in range(n):
        yield i * i

gen = squares(5)

# Pull one value at a time
print(next(gen))  # 0
print(next(gen))  # 1
print(next(gen))  # 4

# Or iterate with a for loop (calls next() automatically)
for value in squares(5):
    print(value)
# 0
# 1
# 4
# 9
# 16
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

A generator can only be iterated once. After it has yielded all its values (or a `return` statement is reached), it is exhausted - any further call to `next()` raises `StopIteration`, and converting it to a list returns an empty list. If multiple callers each need a fresh sequence, pass the producing function, not the generator object itself.

</ExampleProse>
<ExampleCode>

```python
def count_up(n):
    for i in range(n):
        yield i

gen = count_up(3)
print(list(gen))  # [0, 1, 2]
print(list(gen))  # []  -- generator is exhausted

# Fix: pass the function (or a lambda/partial) so each caller
# creates a fresh generator
def make_gen():
    return count_up(3)

print(list(make_gen()))  # [0, 1, 2]
print(list(make_gen()))  # [0, 1, 2]
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

The `itertools` module in the standard library provides building blocks for working with iterators. They are all lazy - they produce values on demand and never materialise an intermediate list. `islice` limits how many values you take, `chain` concatenates multiple iterables, and `groupby` groups consecutive elements by a key.

</ExampleProse>
<ExampleCode>

```python
import itertools

# islice: take the first 3 values from an infinite counter
counter = itertools.count(start=10, step=2)  # 10, 12, 14, 16, ...
first_three = list(itertools.islice(counter, 3))
first_three  # [10, 12, 14]

# chain: iterate multiple iterables as one
a = [1, 2, 3]
b = [4, 5, 6]
together = list(itertools.chain(a, b))
together  # [1, 2, 3, 4, 5, 6]

# groupby: group consecutive items by a key (sort first if needed)
data = [
    {"dept": "eng", "name": "Alice"},
    {"dept": "eng", "name": "Bob"},
    {"dept": "sales", "name": "Carol"},
]
for dept, members in itertools.groupby(data, key=lambda x: x["dept"]):
    names = [m["name"] for m in members]
    print(dept, names)
# eng ['Alice', 'Bob']
# sales ['Carol']
```

</ExampleCode>
</ExamplePair>

<InProduction>
A generator can only be iterated once - `g = (x for x in xs); list(g); list(g)` returns an empty list the second time. Pass the producing function (`make_gen()`) when consumers need a fresh iterator, not the generator object itself. For pipelines over large or infinite streams, `itertools.chain`, `islice`, and `groupby` plus generator expressions stay constant-memory where the equivalent list-comprehension chain materialises every intermediate sequence.
</InProduction>


Generators produce values lazily with yield, iterate once, and pair with itertools for constant-memory pipelines.

Generators and Iterators


A class is a blueprint for objects. The `class` block defines attributes (data) and methods (behaviour). Every instance gets its own copy of the attributes set in `__init__`. The `@dataclass` decorator (available since Python 3.7) generates `__init__`, `__repr__`, and `__eq__` for you, cutting out a lot of boilerplate for classes whose job is mainly to hold data.

<ExamplePair>
<ExampleProse>

A class is defined with `class Name:`. The special method `__init__` runs when you create an instance and receives the new object as its first argument, conventionally called `self`. You attach per-instance data with `self.attribute = value`. Other methods access instance data the same way.

</ExampleProse>
<ExampleCode>

```python
class Counter:
    def __init__(self, start: int = 0) -> None:
        self._count = start

    def increment(self, by: int = 1) -> None:
        self._count += by

    def value(self) -> int:
        return self._count


c = Counter()
c.increment()
c.increment(by=5)
print(c.value())  # 6

c2 = Counter(start=10)
c2.increment()
print(c2.value())  # 11  -- c and c2 are independent instances
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

For classes that mainly hold data - configuration, domain values, events - `@dataclass` generates `__init__`, `__repr__`, and `__eq__` from the type-annotated class body. Adding `frozen=True` prevents attribute reassignment after construction and automatically generates `__hash__`, making instances usable as dict keys or set members. Adding `slots=True` (Python 3.10+) reduces memory usage by roughly 40%.

</ExampleProse>
<ExampleCode>

```python
from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class Point:
    x: float
    y: float


p1 = Point(1.0, 2.0)
p2 = Point(1.0, 2.0)
p3 = Point(3.0, 4.0)

print(p1)          # Point(x=1.0, y=2.0)
print(p1 == p2)    # True  (__eq__ generated)
print(p1 == p3)    # False

# frozen=True makes Point hashable
locations = {p1, p2, p3}
print(len(locations))  # 2  (p1 and p2 are equal)

# Mutation is blocked
# p1.x = 99.0  # raises FrozenInstanceError
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Python requires `__eq__` and `__hash__` to stay consistent: if two objects compare equal, they must produce the same hash. If you define `__eq__` without `__hash__`, Python sets `__hash__` to `None`, making instances unhashable. This breaks set membership and dict keys in ways that are easy to miss in tests. Dataclasses handle this rule automatically: `frozen=True` generates both; mutable dataclasses set `__hash__` to `None` when `__eq__` is generated.

</ExampleProse>
<ExampleCode>

```python
class BadPoint:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        return isinstance(other, BadPoint) and self.x == other.x and self.y == other.y

    # No __hash__ defined -- Python sets __hash__ = None


p = BadPoint(1, 2)
try:
    {p}  # TypeError: unhashable type: 'BadPoint'
except TypeError as e:
    print(e)


# Fix option 1: add __hash__ = __eq__ partner
class GoodPoint:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        return isinstance(other, GoodPoint) and self.x == other.x and self.y == other.y

    def __hash__(self):
        return hash((self.x, self.y))


# Fix option 2 (recommended): use @dataclass(frozen=True)
@dataclass(frozen=True, slots=True)
class BestPoint:
    x: float
    y: float
```

</ExampleCode>
</ExamplePair>

<InProduction>
Reach for `@dataclass(frozen=True, slots=True)` for value-shaped objects (data transfer objects, events, config) - `slots=True` cuts memory by roughly 40% and `frozen=True` makes them hashable as dict keys or set members. Class-level attributes are shared across all instances: `class Foo: items = []` is a single list shared by every `Foo`; use `__init__` for per-instance state. Overriding `__eq__` without `__hash__` makes the type unhashable, which breaks set and dict membership in non-obvious ways - dataclasses handle this consistently for you.
</InProduction>


Python classes group state and behaviour; dataclasses generate the boilerplate; frozen=True and slots=True give you hashable, memory-efficient value objects.

Classes and Dataclasses


Errors in Python are exceptions - objects that inherit from `BaseException` (or usually from its subclass `Exception`). When something goes wrong, Python `raise`s one of these objects. You catch it with a `try` / `except` block. The optional `else` clause runs only when `try` succeeds with no exception; `finally` runs no matter what.

<ExamplePair>
<ExampleProse>

The `try` block wraps code that might fail. Each `except` clause names the exception type (or types) it handles. You can catch multiple types in one clause with a tuple. The `else` clause - which many developers overlook - runs only when the `try` block completes without raising, which keeps "success" logic separate from "error" logic. `finally` always runs, making it the right place for cleanup.

</ExampleProse>
<ExampleCode>

```python
import json

def parse_config(text: str) -> dict:
    try:
        data = json.loads(text)
    except json.JSONDecodeError as err:
        print(f"Invalid JSON: {err}")
        return {}
    except (TypeError, ValueError) as err:
        print(f"Unexpected error: {err}")
        return {}
    else:
        # Only runs when json.loads succeeded
        print(f"Parsed {len(data)} keys")
        return data
    finally:
        # Always runs, even if an exception propagated
        print("parse_config done")


parse_config('{"key": "value"}')
# Parsed 1 keys
# parse_config done

parse_config("not json")
# Invalid JSON: ...
# parse_config done
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

When you catch an exception and raise a different one, you can preserve the original error as the "cause" using `raise NewError(...) from original`. Python then shows both errors in the traceback, which makes debugging much easier. Using `raise NewError(...)` without `from` discards the original context. The clause `raise ... from None` explicitly suppresses the cause - use it deliberately, not as a default.

Separately: `except Exception:` is the safe broad catch for user code, because it does not catch `KeyboardInterrupt` or `SystemExit` - those subclass `BaseException` directly and should propagate. Bare `except:` catches everything including `KeyboardInterrupt` and is almost always wrong.

</ExampleProse>
<ExampleCode>

```python
class DatabaseError(Exception):
    pass


def load_user(user_id: int) -> dict:
    try:
        # Simulate a low-level error
        raise ConnectionError("socket timeout after 30s")
    except ConnectionError as original:
        # Wrap with domain context, preserve the cause
        raise DatabaseError(f"Failed to load user {user_id}") from original


try:
    load_user(42)
except DatabaseError as err:
    print(err)           # Failed to load user 42
    print(err.__cause__)  # socket timeout after 30s
```

```python
# Safe broad catch
try:
    risky_operation()
except Exception as err:
    # KeyboardInterrupt and SystemExit still propagate
    log(err)

# Dangerous - catches KeyboardInterrupt too
try:
    risky_operation()
except:        # bare except - avoid
    pass
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Python 3.11 introduced `ExceptionGroup` for cases where multiple things fail at once - most commonly when several async tasks run concurrently and more than one raises an error. An `ExceptionGroup` holds a list of exceptions. The new `except*` syntax (note the asterisk) matches exception groups, letting you handle specific member types while letting others propagate.

</ExampleProse>
<ExampleCode>

```python
import asyncio

async def might_fail(name: str, should_fail: bool) -> str:
    await asyncio.sleep(0)
    if should_fail:
        raise ValueError(f"{name} failed")
    return name


async def main() -> None:
    # TaskGroup raises ExceptionGroup if any task fails
    try:
        async with asyncio.TaskGroup() as tg:
            tg.create_task(might_fail("a", False))
            tg.create_task(might_fail("b", True))
            tg.create_task(might_fail("c", True))
    except* ValueError as eg:
        for err in eg.exceptions:
            print(f"Caught ValueError: {err}")
    # Output:
    # Caught ValueError: b failed
    # Caught ValueError: c failed


asyncio.run(main())
```

</ExampleCode>
</ExamplePair>

<InProduction>
`except Exception:` catches almost everything but does not catch `KeyboardInterrupt` or `SystemExit` (those subclass `BaseException` directly), so `except Exception` is the safe broad catch and bare `except:` is the dangerous one. Always chain with `raise NewError(...) from original_error` so the traceback preserves the cause - bare `raise NewError(...)` discards the original context and makes bugs much harder to trace. `ExceptionGroup` and `except*` (3.11+) handle the asyncio fan-out case where multiple tasks fail concurrently.
</InProduction>


try/except/else/finally, raise...from for chaining, and ExceptionGroup for handling multiple concurrent failures in Python 3.11+.

Exceptions


A context manager is an object with two special methods: `__enter__` (runs when the `with` block starts) and `__exit__` (runs when the block ends, whether normally or via an exception). The classic example is a file handle: `with open("...") as f:` - `__exit__` closes the file even if the body raises, so you never forget cleanup.

<ExamplePair>
<ExampleProse>

`pathlib.Path` is the modern way to work with file paths in Python 3.4+. Calling `.open()` on a `Path` object returns a file handle that works exactly like the built-in `open()`. Wrapping it in `with` guarantees the file is closed when the block exits - no matter what happens inside. This replaces the older `os.path` + bare `open()` pattern.

</ExampleProse>
<ExampleCode>

```python
from pathlib import Path

p = Path("data.txt")

# Write something first
p.write_text("hello, world\n")

# Read it back - file is closed automatically when with block exits
with p.open() as f:
    data = f.read()

print(data)  # hello, world

# Works the same even if the body raises - __exit__ still closes the file
try:
    with p.open() as f:
        content = f.read()
        raise ValueError("something went wrong mid-read")
except ValueError:
    pass  # file is already closed here
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

You can write your own context manager by adding `__enter__` and `__exit__` methods to a class. `__enter__` runs first and returns the value that `with ... as x:` binds to `x`. `__exit__` receives three arguments about any exception that occurred (`exc_type`, `exc_val`, `traceback`) - returning a falsy value (or `None`) lets the exception propagate; returning a truthy value suppresses it.

</ExampleProse>
<ExampleCode>

```python
import time


class Timer:
    def __enter__(self):
        self.start = time.perf_counter()
        return self  # bound to the 'as' variable

    def __exit__(self, exc_type, exc_val, traceback):
        self.elapsed = time.perf_counter() - self.start
        return None  # do not suppress exceptions


def slow_work():
    total = sum(range(1_000_000))
    return total


with Timer() as t:
    result = slow_work()

print(f"Result: {result}")
print(f"Elapsed: {t.elapsed:.4f}s")
# Result: 499999500000
# Elapsed: 0.0312s  (varies by machine)
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Writing a full class for a one-off context manager is often more code than necessary. `contextlib.contextmanager` lets you write the same logic as a generator function: code before `yield` is the setup (`__enter__`), the yielded value is what `with ... as x:` receives, and code after `yield` is the teardown (`__exit__`). Wrap teardown in `try/finally` so it runs even when the body raises.

</ExampleProse>
<ExampleCode>

```python
import os
from contextlib import contextmanager


@contextmanager
def chdir(path):
    """Temporarily change working directory."""
    old = os.getcwd()
    os.chdir(path)
    try:
        yield  # caller's with-block runs here
    finally:
        os.chdir(old)  # always restore, even on exception


# Usage
print(os.getcwd())          # /some/original/path

with chdir("/tmp"):
    print(os.getcwd())      # /tmp
    # do work here

print(os.getcwd())          # /some/original/path  (restored)
```

</ExampleCode>
</ExamplePair>

<InProduction>
A context manager whose `__exit__` returns a truthy value silently suppresses the exception - this is one of the most common sources of swallowed errors in production; `__exit__` should return `None` (or `False`) unless suppression is explicitly intended. Reach for `contextlib.contextmanager` over a class for one-off cases - the value you `yield` is what `with ... as x:` binds, and cleanup runs in the `finally` after `yield`. `pathlib.Path.open()` combined with `with` is the modern file-I/O idiom - never call `open()` without `with`, and prefer `pathlib` over `os.path` in new code.
</InProduction>


Context managers pair setup and teardown in a with block. Use pathlib + with for files, contextlib.contextmanager for one-offs.

Context Managers


`async def` declares a coroutine - a function that can pause while waiting for I/O and let other work run in the meantime. `await` is how you pause: it suspends the current coroutine until the thing you are awaiting completes. `asyncio.run(main())` starts the event loop and runs your top-level coroutine. Important to say upfront: asyncio is *concurrency*, not parallelism. A single CPython process runs one Python bytecode instruction at a time, because the Global Interpreter Lock (GIL) prevents two threads from executing Python simultaneously. What asyncio gives you is the ability to overlap *I/O waits* - while one coroutine waits for a network response, another can run.

<ExamplePair>
<ExampleProse>

An `async def` function returns a coroutine object when called - it does not start running yet. You must `await` it (inside another async function) or hand it to `asyncio.run()` at the top level. `await asyncio.sleep(n)` is the async equivalent of `time.sleep(n)`: it pauses the coroutine for `n` seconds without blocking the event loop thread.

</ExampleProse>
<ExampleCode>

```python
import asyncio


async def fetch(url: str) -> str:
    # Simulate a network round-trip
    await asyncio.sleep(0.1)
    return f"response from {url}"


async def main() -> None:
    result = await fetch("https://example.com/api")
    print(result)


asyncio.run(main())
# response from https://example.com/api
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`asyncio.gather()` runs multiple coroutines concurrently and waits for all of them. Because the coroutines overlap their I/O waits, the total time is roughly the duration of the slowest one - not the sum of all of them. One important caveat: by default, `gather` does not cancel sibling coroutines when one of them fails. If task B raises an exception, tasks A and C keep running until they finish or you explicitly cancel them.

</ExampleProse>
<ExampleCode>

```python
import asyncio
import time


async def fetch(label: str, delay: float) -> str:
    await asyncio.sleep(delay)
    return f"{label} done"


async def main() -> None:
    start = time.perf_counter()

    # Run three fetches concurrently
    # Total time is ~0.3s (the slowest), not 0.1+0.2+0.3 = 0.6s
    results = await asyncio.gather(
        fetch("a", 0.1),
        fetch("b", 0.2),
        fetch("c", 0.3),
    )

    elapsed = time.perf_counter() - start
    print(results)      # ['a done', 'b done', 'c done']
    print(f"{elapsed:.2f}s")  # ~0.30s


asyncio.run(main())
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`asyncio.TaskGroup` (added in Python 3.11) gives you fail-fast fan-out with structured cancellation. When any task inside the group raises an exception, the group cancels all remaining tasks and then raises an `ExceptionGroup` containing all the errors that occurred. This is safer than `gather` for most fan-out work because no task silently keeps running after a sibling has already failed.

</ExampleProse>
<ExampleCode>

```python
import asyncio


async def fetch(label: str, should_fail: bool) -> str:
    await asyncio.sleep(0.1)
    if should_fail:
        raise ValueError(f"{label} failed")
    return f"{label} ok"


async def main() -> None:
    try:
        async with asyncio.TaskGroup() as tg:
            tg.create_task(fetch("a", should_fail=False))
            tg.create_task(fetch("b", should_fail=True))
            tg.create_task(fetch("c", should_fail=True))
        # If we reach here, all tasks succeeded
    except* ValueError as eg:
        # except* handles ExceptionGroup members by type
        for err in eg.exceptions:
            print(f"Caught: {err}")
    # Output:
    # Caught: b failed
    # Caught: c failed


asyncio.run(main())
```

</ExampleCode>
</ExamplePair>

<InProduction>
`asyncio` is concurrency, not parallelism - a single CPython process runs one Python bytecode instruction at a time under the GIL; asyncio overlaps I/O waits, not CPU work. For CPU-bound workloads reach for `multiprocessing` or `concurrent.futures.ProcessPoolExecutor`. `asyncio.gather(*tasks)` does not cancel sibling tasks on first failure by default; prefer `async with asyncio.TaskGroup()` (3.11+) for fail-fast semantics with structured cancellation.
</InProduction>


async/await runs concurrent I/O on a single thread via asyncio. TaskGroup (3.11+) gives fail-fast fan-out with structured cancellation.