{"title":"Iterators","description":"","content":"Every time you write `for product in cart:`, Python is doing two distinct jobs behind the scenes. It's asking the cart \"can I walk through your items?\", and then it's walking through them one at a time. Python splits those two jobs onto two different kinds of object: an **iterable** (the thing that can produce a walker) and an **iterator** (the walker itself). This lesson untangles those two roles, explains why Python keeps them separate, and shows the `iter()` and `next()` built-ins that let you control the walk by hand.\n\n---\n\n# The Two Roles in One Sentence\n\nAn **iterable** is anything you can ask for an iterator. A **list** is iterable. A **string** is iterable. A **dict** is iterable. So is a tuple, a set, a `range`, and an open file.\n\nAn **iterator** is a stateful cursor. It remembers where you are in the walk and produces the next item when you ask. Calling `next(iterator)` returns the next value; when there are no more values, it raises `StopIteration`.\n\nThe relationship is one-to-many. A single list can hand out many fresh iterators, each starting from the beginning. The list doesn't move when you walk it; the iterator does.\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\n\nwalker = iter(cart)\nprint(next(walker))\nprint(next(walker))\nprint(next(walker))\n```\n\n\n`iter(cart)` asked the list for a walker. Each `next(walker)` advanced that walker by one item. The list `cart` itself never changed. We didn't pop anything off it; we just stepped through it from the outside.\n\nThe `for` loop works on \"anything iterable.\" This lesson is the answer to \"what does iterable actually mean?\" For now, treat the two roles as a fact about Python and learn to spot them.\n\n---\n\n# `iter()` and `next()`: The Two Built-ins You Need\n\nPython exposes the iterator machinery through two built-in functions.\n\n`iter(obj)` takes an iterable and returns a fresh iterator over it. If `obj` isn't iterable, you get `TypeError`.\n\n`next(it)` takes an iterator and returns its next value. When the iterator is exhausted, it raises `StopIteration`.\n\nThat's the whole core API. Every iteration construct in Python, the `for` loop, comprehensions, the `in` operator on sequences, the `*` unpacking operator, ultimately runs `iter()` once and then calls `next()` in a loop until `StopIteration` shows up.\n\n\n```python\nprices = [29.99, 14.99, 9.99]\n\ncursor = iter(prices)\nprint(type(cursor))\nprint(next(cursor))\nprint(next(cursor))\nprint(next(cursor))\n```\n\n\nTwo things to notice. First, the iterator's type is `list_iterator`, not `list`. The list and the iterator are different objects with different jobs. Second, after three `next()` calls we've consumed every value. One more call and Python raises `StopIteration`:\n\n\n```python\nprices = [29.99, 14.99, 9.99]\ncursor = iter(prices)\nnext(cursor)\nnext(cursor)\nnext(cursor)\nnext(cursor)\n```\n\n\n`StopIteration` is the official \"I'm done\" signal. It isn't a bug; it's how iterators tell Python's loop machinery to stop. When you write `for price in prices:`, Python catches that exception for you and exits the loop cleanly, which is why you never see `StopIteration` in everyday code.\n\nYou can also supply a default to `next()` so the exception is swallowed:\n\n\n```python\nprices = [29.99, 14.99]\ncursor = iter(prices)\n\nprint(next(cursor, None))\nprint(next(cursor, None))\nprint(next(cursor, None))\nprint(next(cursor, None))\n```\n\n\nWith a second argument, `next()` returns it whenever the iterator is exhausted instead of raising. This is handy when you want to peek at the next value without crashing if the cart is empty.\n\n---\n\n# Why Python Splits the Two Roles\n\nSplitting iterable and iterator into two separate objects feels like extra machinery at first. A list could in principle \"know where it is\" all on its own. Most languages with `for-each` loops do exactly that. Python's split has three concrete benefits.\n\n### Reason 1: You Can Walk the Same Iterable Twice\n\nBecause the cursor lives on the iterator, not on the list, you can ask the list for a fresh iterator any time. Each one starts from the beginning.\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\n\nfor item in cart:\n print(f\"first pass: {item}\")\n\nfor item in cart:\n print(f\"second pass: {item}\")\n```\n\n\nEach `for` loop calls `iter(cart)` once, gets a brand-new iterator, and walks it to exhaustion. The list itself never \"moves.\" If lists tracked their own position, the second loop would print nothing.\n\n### Reason 2: You Can Walk Independently in Two Places at Once\n\nBecause iterators are separate objects, you can have two of them open on the same iterable and advance them independently.\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\", \"lamp\"]\n\ncursor_a = iter(cart)\ncursor_b = iter(cart)\n\nprint(next(cursor_a))\nprint(next(cursor_a))\nprint(next(cursor_b))\n```\n\n\n`cursor_a` has advanced two steps. `cursor_b` was created from scratch and has advanced one step. They don't interfere because they each carry their own position. If position lived on the list, this pattern would be impossible without copying the list.\n\n### Reason 3: Iterators Can Be Lazy\n\nAn iterator only has to produce the next value when you ask. It doesn't have to know what's coming after that, and the values don't have to exist in memory before you reach them. This is the whole reason generators work: they're iterators that compute each value on demand.\n\nThe lazy nature also matters for things you can only walk once, like data coming from a network socket or a file. Those producers can't restart; the only sensible model is \"give me the next value if you have one.\" That's exactly what an iterator is.\n\nThe takeaway is that splitting iterable from iterator makes lazy iteration possible.\n\n---\n\n# Every Built-in Collection Is Iterable\n\nThe core Python types all support `iter()`. Each one returns its own kind of iterator object, but they all behave the same way from your end: call `next()` to step, catch `StopIteration` when done.\n\n### Lists\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\ncursor = iter(cart)\nprint(type(cursor))\nprint(next(cursor))\nprint(next(cursor))\n```\n\n\n### Tuples\n\n\n```python\norder = (\"ORD-9001\", \"mug\", 12.99)\ncursor = iter(order)\nprint(type(cursor))\nprint(next(cursor))\nprint(next(cursor))\nprint(next(cursor))\n```\n\n\n### Strings\n\nStrings iterate one character at a time. A customer's name is a sequence of characters, and `iter()` treats it that way.\n\n\n```python\nname = \"Renée\"\ncursor = iter(name)\nprint(type(cursor))\nprint(next(cursor))\nprint(next(cursor))\nprint(next(cursor))\n```\n\n\n### Ranges\n\nA `range` object is iterable but isn't a list. It stores the start, stop, and step, and produces numbers on demand when you walk it.\n\n\n```python\norder_ids = range(1001, 1004)\ncursor = iter(order_ids)\nprint(type(cursor))\nprint(next(cursor))\nprint(next(cursor))\nprint(next(cursor))\n```\n\n\nNotice that `range(1001, 1004)` itself isn't an iterator. It's an iterable that hands out an iterator when asked. You can prove it by walking it twice in two separate loops, just like a list.\n\n### Sets\n\nA set is iterable, but the order in which it produces elements is an implementation detail. Don't rely on it.\n\n\n```python\ntags = {\"electronics\", \"kitchen\", \"office\"}\ncursor = iter(tags)\nprint(type(cursor))\nprint(next(cursor))\nprint(next(cursor))\nprint(next(cursor))\n```\n\n\n### Dictionaries\n\nA dict is iterable too, and by default `iter(some_dict)` walks its **keys**.\n\n\n```python\nstock = {\"mug\": 12, \"notebook\": 5, \"pen\": 100}\ncursor = iter(stock)\nprint(type(cursor))\nprint(next(cursor))\nprint(next(cursor))\nprint(next(cursor))\n```\n\n\nThe default cursor is over keys. To walk values or key-value pairs, use the dict view methods.\n\n\n```python\nstock = {\"mug\": 12, \"notebook\": 5, \"pen\": 100}\n\nfor qty in stock.values():\n print(qty)\n\nprint(\"---\")\n\nfor product, qty in stock.items():\n print(f\"{product}: {qty}\")\n```\n\n\n`stock.values()` and `stock.items()` return view objects, which are themselves iterable. You can call `iter()` on either of them and step manually if you need to.\n\n\n```python\nstock = {\"mug\": 12, \"notebook\": 5}\nvalue_cursor = iter(stock.values())\nprint(type(value_cursor))\nprint(next(value_cursor))\nprint(next(value_cursor))\n```\n\n\n\n> **INFO**\n>\n> **Cost:** Dict views (`keys()`, `values()`, `items()`) don't copy anything. They're lightweight wrappers around the underlying dict, so iterating them is the same cost as iterating the dict directly. Calling `list(stock.values())` would copy.\n\n\n### Files\n\nAn open file object is iterable, and walking it yields one line at a time. This is the line-by-line streaming pattern used for file handling.\n\n\n```python\nwith open(\"orders.txt\", \"w\", encoding=\"utf-8\") as f:\n f.write(\"ORD-9001: mug\\nORD-9002: notebook\\nORD-9003: pen\\n\")\n\nwith open(\"orders.txt\", \"r\", encoding=\"utf-8\") as f:\n cursor = iter(f)\n print(next(cursor).rstrip())\n print(next(cursor).rstrip())\n print(next(cursor).rstrip())\n```\n\n\nThe file is iterable. `iter(f)` returns an iterator that produces each line in turn. When the file is exhausted, the next `next()` call raises `StopIteration`. That's exactly the contract `for line in f:` relies on under the hood.\n\n---\n\n# How `for` Uses `iter()` and `next()` Under the Hood\n\nWhen you write a `for` loop, Python does roughly this:\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\n\n# What `for item in cart:` actually does:\n_cursor = iter(cart)\nwhile True:\n try:\n item = next(_cursor)\n except StopIteration:\n break\n print(item)\n```\n\n\nThat's the entire mechanism. The `for` loop is sugar around `iter()`, `next()`, and a try/except for `StopIteration`.\n\nThe same engine drives comprehensions, generator expressions, `*` unpacking, the `in` operator on sequences, and built-ins like `sum`, `max`, `min`, `any`, `all`, and `sorted`. All of them accept anything iterable, and all of them use the same protocol.\n\n\n```python\nprices = [29.99, 14.99, 9.99]\n\nprint(sum(prices))\nprint(max(prices))\nprint(any(p > 20 for p in prices))\n```\n\n\n`sum(prices)` runs `iter(prices)` once and calls `next` in a loop, accumulating the values. The generator expression `p > 20 for p in prices` is itself an iterator, and `any()` walks it the same way. Once you see iteration as \"iter then next,\" every loop-like construct in Python starts to feel like one mechanism instead of many.\n\n---\n\n# An Iterator Is Also Iterable, but a Spent One Is Empty\n\nHere's the part that trips people up the first time they see it. **Iterators are also iterables**. Calling `iter()` on an iterator returns the iterator itself, not a fresh one. This is so a `for` loop over an iterator \"just works\" without an extra unwrap step.\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\ncursor = iter(cart)\n\nprint(iter(cursor) is cursor)\n```\n\n\nThe good news is that you can pass an iterator anywhere an iterable is expected, like `sum`, `max`, `list`, or another `for` loop. The trap is that once an iterator is exhausted, it stays exhausted. There's no \"rewind.\"\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\ncursor = iter(cart)\n\nprint(list(cursor))\nprint(list(cursor))\n```\n\n\nThe first `list(cursor)` walked the iterator to the end, draining it. The second call asked for a fresh walk, but the cursor was already at end-of-stream, so it returned nothing. To restart, you need a brand-new iterator from the original iterable.\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\n\nprint(list(iter(cart)))\nprint(list(iter(cart)))\n```\n\n\nEach call to `iter(cart)` produces a fresh cursor at position 0, and each `list()` then drains it independently.\n\nThis is the exact reason a `for` loop over a list works correctly twice in a row but a `for` loop over a generator doesn't. The list is the iterable, and each `for` builds its own iterator. The generator **is** the iterator, and once you've walked it, it's done.\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\ncursor = iter(cart)\n\nfor item in cursor:\n print(f\"first pass: {item}\")\n\nfor item in cursor:\n print(f\"second pass: {item}\")\n```\n\n\nThe first loop drained the cursor. The second loop got nothing because the cursor was already at end-of-stream. Both loops were syntactically identical, but the second one silently produced zero iterations. That's a real bug magnet when you don't see the distinction. Re-running with a list directly works because `for` calls `iter(list)` afresh each time:\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\n\nfor item in cart:\n print(f\"first pass: {item}\")\n\nfor item in cart:\n print(f\"second pass: {item}\")\n```\n\n\nSame loops, different result, because the underlying object is iterable rather than an already-spent iterator. The rule of thumb: **lists, tuples, dicts, sets, strings, ranges, and files are iterables you can iterate many times; the cursor objects returned by `iter()` are one-shot.**\n\n\n> **INFO**\n>\n> **Cost:** Calling `iter()` on a list is O(1); it just allocates a small cursor object. Walking the cursor is O(n) because it touches every element. Drains are cheap; restarts mean a fresh `iter()` call.\n\n\n---\n\n# A Mental Picture of the Two Roles\n\nThe split between iterable and iterator is easier to keep straight with a diagram. The iterable is the source. The iterator is the cursor. Walking the cursor produces values; the cursor stops by raising `StopIteration`.\n\n\n```mermaid\nflowchart LR\n Cart[\"Iterable
cart = list
'mug', 'notebook', 'pen'\"]:::cyan\n Cursor[\"Iterator
list_iterator
position: 0\"]:::orange\n V1[\"'mug'\"]:::green\n V2[\"'notebook'\"]:::green\n V3[\"'pen'\"]:::green\n Stop[\"StopIteration\"]:::red\n\n Cart -->|iter cart| Cursor\n Cursor -->|next| V1\n Cursor -->|next| V2\n Cursor -->|next| V3\n Cursor -->|next| Stop\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef red fill:#ff8787,stroke:#000,color:#000\n```\n\n\nThe arrow labeled `iter cart` runs once. It produces the cursor. The arrows labeled `next` run repeatedly, each one advancing the cursor by one slot. When the cursor walks off the end, the next call raises `StopIteration` instead of returning a value. The `for` loop is exactly this picture, with the `StopIteration` arrow translated into \"exit the loop.\"\n\nThere's one more useful detail to put on the picture: the iterator carries its own state. If you ask the iterable for a second cursor, you get a fresh one at position 0, and the two cursors don't interact.\n\n\n```mermaid\nflowchart LR\n Cart[\"Iterable
cart\"]:::cyan\n A[\"Iterator A
position: 2\"]:::orange\n B[\"Iterator B
position: 0\"]:::teal\n\n Cart -->|iter cart| A\n Cart -->|iter cart| B\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nTwo cursors, two positions, one shared source. That's the model.\n\n---\n\n# A Walk Through a Single Order\n\nA more realistic example pulls these pieces together. Imagine a small order represented as a dict, and we want to walk through its fields manually instead of letting a `for` loop do it.\n\n\n```python\norder = {\n \"order_id\": \"ORD-9001\",\n \"customer\": \"Renée Müller\",\n \"status\": \"shipped\",\n \"total\": 47.97,\n}\n\ncursor = iter(order.items())\n\nkey, value = next(cursor)\nprint(f\"first field: {key} = {value}\")\n\nkey, value = next(cursor)\nprint(f\"second field: {key} = {value}\")\n\nprint(\"remaining fields:\")\nfor key, value in cursor:\n print(f\" {key} = {value}\")\n```\n\n\nWe pulled two items off the cursor by hand with `next()`, then let a `for` loop drain the rest. Mixing manual `next()` calls with a `for` loop on the same cursor is fine because both speak the same protocol. The `for` picks up where `next()` left off because the position lives on the cursor.\n\nThis pattern, peek the first few items by hand, then loop the rest, is exactly how you'd skip a header row in a CSV or grab a \"next page\" cursor from a stream. The shape of the code is the same regardless of where the data comes from.\n\n---\n\n# What's Iterable Today: A Quick Reference\n\n\n| Type | Iterable? | Iterator type returned by `iter()` | Walks over |\n| ---- | --------- | ---------------------------------- | ---------- |\n| `list` | yes | `list_iterator` | elements in order |\n| `tuple` | yes | `tuple_iterator` | elements in order |\n| `str` | yes | `str_iterator` | characters |\n| `dict` | yes | `dict_keyiterator` | keys |\n| `dict.keys()` | yes | `dict_keyiterator` | keys |\n| `dict.values()` | yes | `dict_valueiterator` | values |\n| `dict.items()` | yes | `dict_itemiterator` | `(key, value)` tuples |\n| `set` / `frozenset` | yes | `set_iterator` | elements, order undefined |\n| `range` | yes | `range_iterator` | numbers in the range |\n| open file | yes | the file object itself | lines |\n| `bytes` / `bytearray` | yes | `bytes_iterator` / `bytearray_iterator` | integer byte values |\n| `int`, `float`, `bool`, `None` | no | n/a (raises `TypeError`) | n/a |\n\n\nThis isn't exhaustive, but it covers everything you'll meet in the first half of the course. The pattern carries: most \"container-ish\" types in Python are iterable, and a few non-container ones (open files) are too. The non-iterable types are the scalars: a single number or a `None` doesn't have a sequence of values to walk.\n\n---\n\n# A Small Helper: Reading the First N Values\n\nOnce you can hold an iterator in a variable, you can build small utilities on top of it. Here's a function that returns the first `n` items of an iterable, stopping early if the iterable runs out:\n\n\n```python\ndef first_n(iterable, n):\n cursor = iter(iterable)\n taken = []\n for _ in range(n):\n try:\n taken.append(next(cursor))\n except StopIteration:\n break\n return taken\n\ncart = [\"mug\", \"notebook\", \"pen\", \"lamp\", \"headphones\"]\nprint(first_n(cart, 3))\nprint(first_n(cart, 10))\nprint(first_n([], 3))\n```\n\n\nThe function works on any iterable, not just lists, because all it needs is `iter()` and `next()`. Pass it a dict and you get the first `n` keys. Pass it a file and you get the first `n` lines. Pass it a string and you get the first `n` characters.\n\n\n```python\nstock = {\"mug\": 12, \"notebook\": 5, \"pen\": 100, \"lamp\": 7}\nprint(first_n(stock, 2))\n\nprint(first_n(\"AlgoMaster\", 4))\n```\n\n\nThat's the payoff of writing to the iterator protocol instead of a specific type. The function doesn't care where the values come from, as long as the source can hand out a cursor.\n\nThe standard library's `itertools.islice` does this same job more efficiently. The point of writing `first_n` by hand here is to show that the protocol is small enough to use directly.\n\n---\n\n# Common Mistakes\n\nA few patterns catch beginners often enough to be worth naming.\n\n### Treating an Iterator Like a List\n\nAn iterator doesn't have a length, doesn't support indexing, and can only be walked once. Calling `len(cursor)` or `cursor[0]` raises `TypeError`.\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\ncursor = iter(cart)\nprint(len(cursor))\n```\n\n\nIf you need a length or indexing, materialize the iterator into a list first: `items = list(cursor)`. Just remember that doing so consumes the iterator.\n\n### Walking the Same Iterator Twice\n\nOnce an iterator is exhausted, it's done. A second loop or a second `list()` call gets nothing. This is the most common surprise:\n\n\n```python\ncart = [\"mug\", \"notebook\", \"pen\"]\ncursor = iter(cart)\n\nprint(\"first walk:\", list(cursor))\nprint(\"second walk:\", list(cursor))\n```\n\n\nTo walk twice, get two iterators from the iterable, or hold onto the iterable and re-iterate it directly.\n\n### Forgetting That Dicts Walk Keys\n\n`for item in stock:` walks the dict's keys, not its values. Mixing this up leads to confusing bugs when you expect prices and get product names instead.\n\n\n```python\nstock = {\"mug\": 12, \"notebook\": 5, \"pen\": 100}\n\nfor item in stock:\n print(item)\n```\n\n\nUse `stock.values()` for values, `stock.items()` for both, or just remember that the bare dict gives keys.\n\n### Assuming `range` Is a List\n\nA `range` looks list-like but isn't a list. It's an iterable that produces numbers on demand. You can iterate it many times, but you can't `append` to it, and `iter(range(...))` returns a `range_iterator`, not a list.\n\n\n```python\nids = range(1001, 1004)\nprint(type(ids))\nprint(list(ids))\nprint(list(ids))\n```\n\n\nNotice that `range` is iterable and re-iterable. `list(ids)` works twice. The thing you can't do is treat `range` as a mutable list.\n\n### Catching `StopIteration` Where You Don't Need To\n\n`StopIteration` only matters when you're calling `next()` by hand. Inside a `for` loop or a comprehension, Python handles the exception for you, and writing your own `try/except StopIteration` around a `for` loop is dead code.\n\n**What's wrong with this code?**\n\n\n```python\ndef show_first(cart):\n for item in cart:\n try:\n print(item)\n except StopIteration:\n break\n```\n\n\nThe `try/except StopIteration` does nothing useful. The body of the `for` loop is reached only when an item has already been produced; `StopIteration` is raised by the iterator's `next()`, which Python already catches before handing the value to the body. The exception will never appear inside the `try`.\n\n**Fix:**\n\n\n```python\ndef show_first(cart):\n for item in cart:\n print(item)\n```\n\n\nThe unnecessary `try/except` just clutters the code. Reach for explicit `StopIteration` handling only when you're calling `next()` directly and want to react to exhaustion yourself.","pageType":"python"}

Iterators

Get Premium