Audit examples against rationale rubric

Author: adewale

src/asset_manifest.py

@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
 ASSET_PATHS = {'SITE_CSS': '/site.dc51488c4ed9.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = '5cd6e8013a84'
+HTML_CACHE_VERSION = '4f2e027de304'

src/example_sources/async-await.md

@@ -12,6 +12,8 @@ doc_path = "/library/asyncio-task.html"
 
 Cloudflare Workers handlers are asynchronous, so understanding `await` is practical for fetch calls, bindings, and service interactions even when a small example uses `asyncio.sleep(0)` as a stand-in.
 
+The alternative is ordinary `def` for work that completes immediately. Use async code for I/O-shaped waiting, not as a faster replacement for CPU-bound Python.
+
 :::program
 ```python
 import asyncio
@@ -86,4 +88,5 @@ asyncio.run(main())
 - Calling an async function creates a coroutine object.
 - `await` yields control until an awaitable completes.
 - Workers request handlers are async, so this pattern appears around fetches and bindings.
+- Prefer ordinary functions when there is no awaitable work to coordinate.
 :::

src/example_sources/async-iteration-and-context.md

@@ -15,6 +15,8 @@ see_also = [
 
 These forms appear around network streams, database cursors, locks, and service clients where both iteration and cleanup may wait on I/O.
 
+Use ordinary `for` and `with` when producing the next value or cleaning up does not need to await anything.
+
 The syntax mirrors `for` and `with`, but the protocol methods are asynchronous.
 
 :::program

src/example_sources/booleans.md

@@ -63,4 +63,5 @@ True
 :::note
 - Boolean constants are `True` and `False`, with capital letters.
 - `and` and `or` short-circuit: Python does not evaluate the right side if the left side already determines the result.
+- Prefer truthiness for containers and explicit comparisons when the exact boolean condition matters.
 :::

src/example_sources/break-and-continue.md

@@ -11,36 +11,36 @@ see_also = [
 ]
 +++
 
-`break` and `continue` control the nearest enclosing loop. They are useful when the loop body discovers a reason to stop early or skip one item.
+`break` and `continue` control the nearest enclosing loop. They exist for loops whose body discovers an early stop rule or an item-level skip rule.
 
-Use `continue` for a skip rule: the current item should not run the rest of the body. Use `break` for a stop rule: no later item should be processed.
+Use `continue` when the current item should not run the rest of the body. Use `break` when no later item should be processed.
 
-Keep both rules close to the top of the loop when possible. That makes the normal path easier to read.
+The alternative is ordinary `if`/`else` nesting. Prefer `break` and `continue` when they keep the normal path flatter and easier to read.
 
 :::program
 ```python
-names = ["Ada", "", "Grace", "stop", "Guido"]
-
+names = ["Ada", "", "Grace"]
 for name in names:
     if not name:
         continue
-    if name == "stop":
-        break
     print(name)
+
+commands = ["load", "save", "stop", "delete"]
+for command in commands:
+    if command == "stop":
+        break
+    print(command)
 ```
 :::
 
 :::cell
 `continue` skips the rest of the current iteration. The empty name is ignored, and the loop moves on to the next value.
 
 ```python
-names = ["Ada", "", "Grace", "stop", "Guido"]
-
+names = ["Ada", "", "Grace"]
 for name in names:
     if not name:
         continue
-    if name == "stop":
-        break
     print(name)
 ```
 
@@ -50,6 +50,23 @@ Grace
 ```
 :::
 
+:::cell
+`break` exits the loop immediately. The value after `stop` is never processed because the loop has already ended.
+
+```python
+commands = ["load", "save", "stop", "delete"]
+for command in commands:
+    if command == "stop":
+        break
+    print(command)
+```
+
+```output
+load
+save
+```
+:::
+
 :::note
 - `continue` skips to the next loop iteration.
 - `break` exits the nearest enclosing loop immediately.

src/example_sources/classes.md

@@ -2,15 +2,15 @@
 slug = "classes"
 title = "Classes"
 section = "Classes"
-summary = "Classes bundle data and behavior."
+summary = "Classes bundle data and behavior into new object types."
 doc_path = "/tutorial/classes.html"
 +++
 
-Classes define new object types by bundling data with behavior. They are useful when several values and operations belong together.
+Classes define new object types by bundling data with behavior. They are useful when several values and operations belong together and should travel as one object.
 
-`__init__` initializes each instance, and methods receive the instance as `self`. Assigning `self.value` stores state on that particular object.
+The alternative is often a dictionary plus separate functions. That is fine for loose data, but a class gives the data a stable API and keeps behavior next to the state it changes.
 
-Separate instances keep separate state. Mutating one `Counter` does not change another because each object has its own attributes.
+`__init__` initializes each instance, and methods receive the instance as `self`. Separate instances keep separate state because each object has its own attributes.
 
 :::program
 ```python
@@ -25,6 +25,8 @@ class Counter:
 first = Counter()
 second = Counter(10)
 
+print(first.value)
+print(second.value)
 print(first.increment())
 print(second.increment(5))
 ```
@@ -77,5 +79,6 @@ print(second.increment(5))
 :::note
 - `self` is the instance the method is operating on.
 - `__init__` initializes each new object.
+- Use classes when behavior belongs with state; use dictionaries for looser structured data.
 - Instance attributes belong to one object, not to the class as a whole.
 :::

src/example_sources/enums.md

@@ -67,4 +67,5 @@ False
 - Enums make states and choices explicit.
 - Members have names and values.
 - Comparing enum members avoids string typo bugs.
+- Prefer raw strings for open-ended text; prefer enums for a closed set of named choices.
 :::

src/example_sources/exception-groups.md

@@ -11,19 +11,22 @@ see_also = [
 ]
 +++
 
-`ExceptionGroup` represents several unrelated exceptions raised together. `except*` handles the matching members of the group and lets other members continue separately.
+`ExceptionGroup` represents several unrelated exceptions raised together. `except*` exists for code that may receive multiple failures at once, especially concurrent work.
 
-This syntax is most useful with concurrent code, where several tasks can fail before the caller regains control.
+Use ordinary `except` for one exception. Use `except*` only when the value being handled is an exception group and each matching subgroup needs its own handling.
 
-Use ordinary `except` for one exception. Use `except*` only when the value being handled is an exception group.
+Each `except*` clause receives a smaller exception group containing the matching exceptions.
 
 :::program
 ```python
+errors = ExceptionGroup(
+    "batch failed",
+    [ValueError("bad port"), TypeError("bad mode")],
+)
+print(len(errors.exceptions))
+
 try:
-    raise ExceptionGroup(
-        "batch failed",
-        [ValueError("bad port"), TypeError("bad mode")],
-    )
+    raise errors
 except* ValueError as group:
     print(type(group).__name__)
     print(group.exceptions[0])
@@ -33,14 +36,27 @@ except* TypeError as group:
 :::
 
 :::cell
-`ExceptionGroup` bundles several exception objects. `except* ValueError` receives a group containing only the matching `ValueError` members.
+An exception group bundles several exception objects. This is different from an ordinary exception because more than one failure is present.
+
+```python
+errors = ExceptionGroup(
+    "batch failed",
+    [ValueError("bad port"), TypeError("bad mode")],
+)
+print(len(errors.exceptions))
+```
+
+```output
+2
+```
+:::
+
+:::cell
+`except*` handles matching members of the group. The `ValueError` handler sees the value error, and the `TypeError` handler sees the type error.
 
 ```python
 try:
-    raise ExceptionGroup(
-        "batch failed",
-        [ValueError("bad port"), TypeError("bad mode")],
-    )
+    raise errors
 except* ValueError as group:
     print(type(group).__name__)
     print(group.exceptions[0])

src/example_sources/exceptions.md

@@ -10,6 +10,8 @@ Exceptions represent errors or unusual conditions that interrupt normal control
 
 Keep the successful path separate from the recovery path. `else` runs only when no exception was raised, while `finally` runs either way for cleanup or bookkeeping.
 
+Use exceptions when an operation cannot produce a valid result. Prefer ordinary conditionals for expected branches that are not errors.
+
 Catch specific exceptions whenever possible. A broad catch can hide programming mistakes, while a targeted `ValueError` handler documents exactly what failure is expected.
 
 :::program

src/example_sources/generators.md

@@ -67,4 +67,5 @@ for value in countdown(3):
 - Generator functions are a concise way to create custom iterators.
 - Values are produced on demand.
 - A generator is consumed as you iterate over it.
+- Prefer a list when you need to reuse stored results; prefer a generator when values can be streamed once.
 :::