
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


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.