Add iterator stream examples

Author: adewale

CHANGELOG.md

@@ -22,10 +22,12 @@ The format is inspired by [Keep a Changelog](https://keepachangelog.com/en/1.1.0
 - Markdown-backed example sources with `:::program` and `:::cell` blocks.
 - Example source verifier, formatter, embedded-source build step, and golden parity check.
 - GitHub Actions verification workflow.
+- `iterators` and `generator-expressions` examples to make the Iteration arc explicit.
 
 ### Changed
 
 - Example walkthroughs now pair prose, source fragments, and output evidence.
+- Iteration examples now frame Python iteration as a value-stream protocol: producers, consumers, eager containers, lazy streams, and one-pass iterators.
 - Read-only code highlighting is handled by Shiki; editable code highlighting is handled by CodeMirror.
 - Prototype routes under `/layout-options/*` bypass the Worker Cache API and return `Cache-Control: no-store`.
 - Static assets use immutable cache headers only on fingerprinted filenames.

README.md

@@ -6,7 +6,7 @@ Production: <https://www.pythonbyexample.dev> (`workers.dev` remains enabled as
 
 ## Features
 
-- 50 curated Python 3.13 examples in learning order
+- 52 curated Python 3.13 examples in learning order
 - Literate source/output cells for each example walkthrough
 - Editable complete examples powered by CodeMirror
 - Read-only syntax highlighting powered by Shiki

docs/example-quality-rubric.md

@@ -22,6 +22,7 @@ Release gates outside the score:
 - page layout remains restrained and readable
 - examples verify under the configured Python version
 - generated embedded source and asset manifests are up to date
+- iteration examples identify what produces values, what consumes values, whether values are stored or streamed, and whether the stream is reusable or one-pass
 
 Quality bands:
 
@@ -44,6 +45,8 @@ Flag these during review even when the code is correct:
 - Data is purely toy-shaped when realistic small data would clarify the purpose.
 - Notes repeat the prose instead of adding practical guidance.
 - The program shows valid syntax but not when or why to use it.
+- An iteration example uses a lazy object but does not show when values are consumed.
+- An iteration example blurs eager containers with one-pass streams.
 
 ## Strengthening checklist
 
@@ -55,3 +58,4 @@ Before publishing or substantially editing an example, ask:
 4. Does the example use small realistic data?
 5. Is there a contrast readers commonly need to avoid misuse?
 6. Would an explicit loop, named function, or mutation-vs-copy contrast make the idiom clearer?
+7. For iteration examples, what produces values, what consumes them, and are they stored eagerly or streamed lazily?

src/asset_manifest.py

@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
 ASSET_PATHS = {'SITE_CSS': '/site.06e133dcde6a.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = '36c5175ef57c'
+HTML_CACHE_VERSION = '559146e23c49'

src/example_sources/comprehensions.md

@@ -6,11 +6,11 @@ summary = "Comprehensions build collections by mapping and filtering iterables."
 doc_path = "/tutorial/datastructures.html#list-comprehensions"
 +++
 
-Comprehensions are expression forms for building collections from iterables. Read them from left to right: produce this value, for each item, optionally only when a condition is true.
+Comprehensions are expression forms for building concrete collections from iterables. Read them from left to right: produce this value, for each item, optionally only when a condition is true.
 
 They are best for direct transformations where the expression is still easy to scan. When the work needs several statements or names, an explicit loop is usually clearer.
 
-Comprehensions can build lists, dictionaries, and sets. Prefer them when the output shape is obvious from the expression.
+List, dictionary, and set comprehensions are eager: they build collections immediately. Generator expressions use similar syntax to stream values later and are covered in the Iteration section.
 
 :::program
 ```python
@@ -71,5 +71,6 @@ print(unique_scores)
 :::note
 - The left side says what to produce; the `for` clause says where values come from.
 - Use an `if` clause for simple filters.
+- List, dict, and set comprehensions build concrete collections immediately.
 - Switch to a loop when the transformation needs multiple steps or explanations.
 :::

src/example_sources/generator-expressions.md

@@ -0,0 +1,77 @@
++++
+slug = "generator-expressions"
+title = "Generator Expressions"
+section = "Iteration"
+summary = "Generator expressions use comprehension-like syntax to stream values lazily."
+doc_path = "/tutorial/classes.html#generator-expressions"
++++
+
+Generator expressions look like list comprehensions with parentheses, but they produce an iterator instead of building a concrete collection immediately.
+
+Use them when a consumer such as `sum()`, `any()`, or a `for` loop can use values one at a time. This keeps the transformation close to the consumer and avoids storing intermediate lists.
+
+Like other iterators, a generator expression is consumed as values are requested. Create a new generator expression when you need another pass.
+
+:::program
+```python
+numbers = [1, 2, 3, 4]
+list_squares = [number * number for number in numbers]
+print(list_squares)
+
+stream_squares = (number * number for number in numbers)
+print(next(stream_squares))
+print(next(stream_squares))
+print(list(stream_squares))
+
+print(sum(number * number for number in numbers))
+```
+:::
+
+:::cell
+A list comprehension is eager: it builds a list immediately. That is useful when you need to store or reuse the results.
+
+```python
+numbers = [1, 2, 3, 4]
+list_squares = [number * number for number in numbers]
+print(list_squares)
+```
+
+```output
+[1, 4, 9, 16]
+```
+:::
+
+:::cell
+A generator expression is lazy: it creates an iterator that produces values as they are consumed. After two `next()` calls, only the remaining squares are left.
+
+```python
+stream_squares = (number * number for number in numbers)
+print(next(stream_squares))
+print(next(stream_squares))
+print(list(stream_squares))
+```
+
+```output
+1
+4
+[9, 16]
+```
+:::
+
+:::cell
+Generator expressions are common inside reducing functions. When a generator expression is the only argument, the extra parentheses can be omitted.
+
+```python
+print(sum(number * number for number in numbers))
+```
+
+```output
+30
+```
+:::
+
+:::note
+- List, dict, and set comprehensions build concrete collections.
+- Generator expressions produce one-pass iterators.
+- Use generator expressions when the consumer can process values one at a time.
+:::

src/example_sources/generators.md

@@ -2,11 +2,11 @@
 slug = "generators"
 title = "Generators"
 section = "Iteration"
-summary = "yield produces a lazy sequence of values."
+summary = "yield creates an iterator that produces values on demand."
 doc_path = "/tutorial/classes.html#generators"
 +++
 
-A generator function uses `yield` to produce values lazily. Calling the function returns an iterator; the body runs only as values are requested.
+A generator function is a convenient way to write your own iterator. `yield` produces one value, pauses the function, and resumes when the next value is requested.
 
 Generators are useful for pipelines, large inputs, and infinite sequences because they avoid building an entire collection in memory.
 
@@ -64,7 +64,7 @@ for value in countdown(3):
 :::
 
 :::note
-- Generator functions return iterators.
+- Generator functions are a concise way to create custom iterators.
 - Values are produced on demand.
 - A generator is consumed as you iterate over it.
 :::

src/example_sources/iterating-over-iterables.md

@@ -2,45 +2,40 @@
 slug = "iterating-over-iterables"
 title = "Iterating over Iterables"
 section = "Iteration"
-summary = "for loops work with any iterable, not just numeric ranges."
+summary = "for loops consume values from any iterable object."
 doc_path = "/tutorial/controlflow.html#for-statements"
 +++
 
-The for statement works with any iterable object: lists, strings, dictionaries, generators, files, and many standard-library helpers. This makes iteration a central Python protocol rather than a special case for arrays.
+Python's `for` statement consumes values from any iterable object: lists, strings, dictionaries, ranges, generators, files, and many standard-library helpers.
 
-Use enumerate() when you need positions and values together, and dict.items() when you need keys and values. These helpers express intent better than manual indexing.
+This makes iteration a value-stream protocol rather than a special case for arrays. The producer decides how values are made, and the loop consumes them one at a time.
 
-Python's for statement consumes iterables through the iterator protocol. Prefer enumerate() over range(len(...)) when you need an index.
+Use `enumerate()` when you need positions and values together, and `dict.items()` when you need keys and values. These helpers express intent better than manual indexing.
 
 :::program
 ```python
 names = ["Ada", "Grace", "Guido"]
 
-# Iterate over values directly.
 for name in names:
     print(name)
 
-# enumerate adds a counter without manual indexing.
 for index, name in enumerate(names):
     print(index, name)
 
 scores = {"Ada": 10, "Grace": 9}
-
-# items yields key/value pairs from a dictionary.
 for name, score in scores.items():
     print(name, score)
 ```
 :::
 
 :::cell
-Start with an ordinary list. A list is iterable, so a for loop can ask it for one value at a time.
+Start with an ordinary list. A list stores values, and a `for` loop asks it for one value at a time.
 
 When you only need the values, iterate over the collection directly. There is no index variable because the loop body does not need one.
 
 ```python
 names = ["Ada", "Grace", "Guido"]
 
-# Iterate over values directly.
 for name in names:
     print(name)
 ```
@@ -53,10 +48,9 @@ Guido
 :::
 
 :::cell
-When you need both a position and a value, use enumerate(). It keeps the counter tied to iteration without manual indexing.
+When you need both a position and a value, use `enumerate()`. It produces index/value pairs without manual indexing.
 
 ```python
-# enumerate adds a counter without manual indexing.
 for index, name in enumerate(names):
     print(index, name)
 ```
@@ -69,12 +63,10 @@ for index, name in enumerate(names):
 :::
 
 :::cell
-Dictionaries are iterable too, but dict.items() is the clearest way to say that the loop needs keys and values together.
+Dictionaries are iterable too, but `dict.items()` is the clearest way to say that the loop needs keys and values together.
 
 ```python
 scores = {"Ada": 10, "Grace": 9}
-
-# items yields key/value pairs from a dictionary.
 for name, score in scores.items():
     print(name, score)
 ```
@@ -86,6 +78,7 @@ Grace 9
 :::
 
 :::note
-- Python's for statement consumes iterables through the iterator protocol.
-- Prefer enumerate() over range(len(...)) when you need an index.
+- A `for` loop consumes values from an iterable.
+- Different producers can feed the same loop protocol.
+- Prefer `enumerate()` over `range(len(...))` when you need an index.
 :::

src/example_sources/iterators.md

@@ -0,0 +1,76 @@
++++
+slug = "iterators"
+title = "Iterators"
+section = "Iteration"
+summary = "iter and next expose the protocol behind for loops."
+doc_path = "/library/stdtypes.html#iterator-types"
++++
+
+An iterable is an object that can produce values for a loop. An iterator is the object that remembers where that production currently is.
+
+`iter()` asks an iterable for an iterator, and `next()` consumes one value from that iterator. A `for` loop performs those steps for you until the iterator is exhausted.
+
+This is the core value-stream protocol in Python: one object produces values, another piece of code consumes them, and many streams are one-pass.
+
+:::program
+```python
+names = ["Ada", "Grace", "Guido"]
+iterator = iter(names)
+print(next(iterator))
+print(next(iterator))
+
+for name in iterator:
+    print(name)
+
+again = iter(names)
+print(next(again))
+```
+:::
+
+:::cell
+`iter()` asks an iterable for an iterator. `next()` consumes one value and advances the iterator's position.
+
+```python
+names = ["Ada", "Grace", "Guido"]
+iterator = iter(names)
+print(next(iterator))
+print(next(iterator))
+```
+
+```output
+Ada
+Grace
+```
+:::
+
+:::cell
+A `for` loop consumes the same iterator protocol. Because two values were already consumed, the loop sees only the remaining value.
+
+```python
+for name in iterator:
+    print(name)
+```
+
+```output
+Guido
+```
+:::
+
+:::cell
+The list itself is reusable. Asking it for a fresh iterator starts a new pass over the same stored values.
+
+```python
+again = iter(names)
+print(next(again))
+```
+
+```output
+Ada
+```
+:::
+
+:::note
+- Iterables produce iterators; iterators produce values.
+- `next()` consumes one value from an iterator.
+- Many iterators are one-pass even when the original collection is reusable.
+:::

src/example_sources/itertools.md

@@ -2,15 +2,15 @@
 slug = "itertools"
 title = "Itertools"
 section = "Iteration"
-summary = "itertools provides lazy iterator building blocks."
+summary = "itertools composes lazy iterator streams."
 doc_path = "/library/itertools.html"
 +++
 
-The `itertools` module contains iterator building blocks for combining, slicing, grouping, and repeating streams of values. These tools pair naturally with `for` loops and generators.
+The `itertools` module contains tools for composing iterator streams: combining, slicing, grouping, and repeating values without changing the consumer protocol.
 
 Many `itertools` functions are lazy. They describe work to do later instead of building a list immediately, so helpers such as `islice()` are useful when taking a finite window.
 
-Iterator pipelines let each step stay small. Convert to `list()` only at the edge when you need to display, store, or reuse the results.
+Iterator pipelines let each step stay small: one object produces values, another transforms them, and a final consumer such as `list()` or a loop pulls values through the pipeline.
 
 :::program
 ```python
@@ -71,6 +71,7 @@ print(list(high_scores))
 :::
 
 :::note
+- `itertools` composes producer and transformer streams.
 - Iterator pipelines avoid building intermediate lists.
 - Use `islice()` to take a finite piece from an infinite iterator.
 - Convert to a list only when you need concrete results.