Fill journey gap examples

Author: adewale

README.md

@@ -6,7 +6,7 @@ Production: <https://www.pythonbyexample.dev> (`workers.dev` remains enabled as
 
 ## Features
 
-- 70 curated Python 3.13 examples in learning order
+- 104 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

@@ -13,12 +13,17 @@ Score each example on a 10 point scale:
 7. **Source/result pairing (0-1.0)** — each important source fragment has nearby output that proves the semantic point, not merely that the code ran.
 8. **Concept decomposition (0-1.0)** — the example breaks the concept into meaningful parts instead of presenting one compressed trick.
 9. **Progressive walkthrough (0-0.75)** — each cell introduces one new idea, and the sequence builds toward the complete concept. Single-cell examples are acceptable only for intentionally atomic concepts.
-10. **Representative coverage (0-0.75)** — the code covers the forms promised by the title, summary, and prose, and the catalog has an explicit home for every common Python syntax form. Do not claim lists, dictionaries, and sets while showing only two of them; do not let syntax such as `break`, `continue`, `assert`, `nonlocal`, `yield from`, or `async for` exist only as untested assumptions.
+10. **Representative coverage (0-0.75)** — the code covers the forms promised by the title, summary, and prose, and the catalog has an explicit home for every common Python syntax form. Do not claim lists, dictionaries, and sets while showing only two of them; do not let syntax such as `break`, `continue`, `assert`, `nonlocal`, `yield from`, `async for`, or `:=` exist only as untested assumptions.
 11. **Practical usefulness (0-1.0)** — names, data, and outputs resemble simplified real code rather than toy placeholders; the example gives the feature a reason to exist.
+12. **Editorial progression (0-1.0)** — broad examples move through a deliberate sequence: motivation, smallest concrete form, model/protocol, common operations, boundary or edge case, and neighboring concepts. The page should feel like a guided exposition rather than a sample tray.
 
 Topic-specific gates:
 
 - **Text and strings** — examples must distinguish text from bytes, explain Unicode/code-point behavior when relevant, and show the boundary where encoding such as UTF-8 appears. A string page that only demonstrates ASCII operations is incomplete. When using non-English text to show that code points and bytes differ, include an English/ASCII baseline with the same kind of phrase so the contrast is visible rather than implied.
+- **Broad surface tours** — if a title names a broad surface area (`Testing`, `Packages`, `Regular Expressions`, `Type Hints`, `Async Await`, `Special Methods`, `Operators`, `Literals`), the page must either cover the reader's reasonable expectations or clearly frame itself as a first pass and link to focused neighbors. A broad title with one narrow demonstration is a scope bug, not just a content gap.
+- **Reduce without distorting** — small examples are good only when the necessary boundary, contrast, or edge case remains visible. If compression removes the part that makes the concept understandable, split the example or add another cell.
+- **Map-or-split rule** — broad pages must either be surface maps with explicit categories and `See also` links, or be split into narrower pages. Do not ship a broad page that merely samples unrelated forms.
+- **Runtime-boundary examples** — when standard Python code cannot run in Dynamic Workers, teach the standard form first, state the runtime constraint once, and avoid repeated apology or caveat-heavy prose.
 
 Release gates outside the score:
 
@@ -58,6 +63,13 @@ Flag these during review even when the code is correct:
 - The page does not connect the feature to a nearby alternative, such as `while` vs `for`, slice vs index, tuple vs list, text `str` vs binary `bytes`, or f-string expression vs display formatting.
 - 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.
+- A broad title hides a narrow example: the page sounds like a tour of a surface area but demonstrates only one isolated technique.
+- A syntax form has a focused example but is missing from a natural umbrella page where learners would expect to see it.
+- The journey order follows implementation/catalog history instead of prerequisites: conditionals before booleans, closures before scope, networking before bytes, or process boundaries before environment boundaries.
+- Runtime constraints are repeated in the intro, code block, notes, and runner area until the limitation overwhelms the Python lesson.
+- The page has no editorial progression: examples are technically related but ordered like a checklist rather than a learning path.
+- The page reduces so aggressively that a necessary edge case or contrast disappears.
+- `See also` links behave like tags instead of prerequisite, neighbor, or next-depth graph edges.
 
 ## Strengthening checklist
 
@@ -74,3 +86,11 @@ Before publishing or substantially editing an example, ask:
 9. Does the data shape explain why this feature exists?
 10. What syntax form would disappear from the catalog if this page were removed, and is that covered somewhere else?
 11. For text examples, does the page make Unicode and encoding boundaries visible instead of assuming ASCII-only strings? If non-English text is used, is it compared with an English/ASCII baseline?
+12. If the title names a broad surface area, what would a learner reasonably expect to see, and is that expectation met or explicitly scoped down?
+13. Is any important syntax form covered only in a focused page even though an umbrella page should point to it?
+14. Does the journey sequence respect prerequisites rather than merely mirroring catalog order?
+15. If the page mentions a runtime limitation, is the constraint stated once without becoming the main story?
+16. Does the page reduce the concept without distorting it, or did compression remove an essential boundary?
+17. For broad pages, is this a map with categories and links, or should it be split?
+18. Do edge cases appear close enough to the main idea that readers understand the boundary?
+19. Do `See also` links express prerequisite, neighbor, or next-depth relationships rather than tags?

docs/lessons-learned.md

@@ -37,6 +37,22 @@ This document records project lessons that should guide future changes to Python
 - When storing examples as Markdown, keep the full editable program in `:::program` and teaching fragments in separate `:::cell` blocks. Do not concatenate cells to recreate the editor source.
 - Fine-grained cells can restate definitions to stay executable. This is better than collapsing class, property, recursion, match, or type-hint examples into one large cell.
 - Preserve a frozen golden catalog while migrating source formats. Full stdout parity is not enough; rendered teaching-cell structure must also match.
+- Beware broad-surface titles that quietly teach only one narrow slice. Pages named `Testing`, `Packages`, `Regular Expressions`, `Type Hints`, `Async Await`, or `Special Methods` must either cover the forms a reader reasonably expects or explicitly frame themselves as a first pass and link to focused neighbors.
+- Do not let an important syntax form live only in a separate page if another page title strongly implies it. An umbrella `Operators` page should at least point to and lightly show `:=`, even though `Assignment Expressions` remains the focused lesson.
+- Journey order should follow prerequisite thinking, not catalog order. Put booleans before truthiness and conditionals, scope before closures, bytes before networking, and environment boundaries before subprocess/thread boundaries.
+- Runtime-boundary caveats should not become the hero. For Dynamic Worker limitations, teach normal Python first and state the constraint once in the marked boundary cell.
+- Algebrica's useful editorial principle is “reduce without distorting.” Python examples should be compact, but not so compressed that the concept loses its necessary contrast, edge case, or progression.
+- Broad examples need a visible learning arc. If a page reads like a tray of samples, either add a map-like progression or split it into narrower examples.
+- Keep teaching artifacts inspectable. Markdown sources, editable programs, teaching cells, expected output, and diagrams/screenshots should be clean enough to serve as public educational material, not just implementation input.
+
+### Broad-surface audit notes
+
+- `Operators and Literals`: fixed by splitting it into `Operators` and `Literals`, then adding `:=` surface coverage and a `See also` link to `Assignment Expressions` from `Operators`.
+- `Special Methods`: fixed by keeping the entry page small and adding focused data-model pages for truth/size, containers, callables, operators, and attribute access.
+- `Testing`: fixed by replacing boilerplate with arrange/assert/run structure and explicit scoping to the smallest `unittest` loop.
+- `Packages`: fixed by splitting package-as-module, dotted imports, and dynamic import into separate cells.
+- `Regular Expressions`: fixed by separating repeated extraction, first-match groups, and the string-method alternative.
+- `Async Await` and `Type Hints`: acceptable for now because both state their boundaries and are supported by focused neighboring examples/journeys.
 
 ## Layout and mobile
 

docs/research-algebrica.md

@@ -0,0 +1,198 @@
+# Research note: Algebrica
+
+Sources:
+
+- <https://github.com/antoniolupetti/algebrica>
+- <https://algebrica.org>
+
+Algebrica is a free, ad-free mathematics knowledge base whose repository publishes source Markdown and editable SVG diagrams. Its README describes an editorial goal that is directly relevant to Python By Example: **reduce without distorting**. Pages are written from multiple university-level sources, reconciled into a coherent exposition, and revised as adjacent pages expose gaps or inconsistencies.
+
+## What we can learn
+
+### 1. Strong pages have a deliberate progression
+
+Algebrica pages do not read like disconnected fact lists. A page such as `definite-integrals` moves through a clear learning arc:
+
+```text
+geometric intuition
+→ approximation
+→ formal definition
+→ computation rule
+→ properties
+→ worked examples
+→ edge cases
+→ links to deeper pages
+```
+
+For Python By Example, broad examples should have a comparable editorial progression:
+
+```text
+why this exists
+→ smallest concrete form
+→ runtime/protocol model
+→ common operations
+→ boundary or edge case
+→ worked output
+→ neighboring concepts
+```
+
+The former `Operators and Literals` page failed this test: it sampled useful syntax but did not provide a coherent map. Splitting it into `Operators` and `Literals` improved the title-to-content contract.
+
+### 2. Reduce without distorting
+
+Small examples are valuable only when they preserve the concept. If an example compresses too much into one cell, it can become technically correct but educationally shallow.
+
+Example risk:
+
+```text
+Bytes and Bytearray: encode, length contrast, decode, and mutation all in one cell.
+```
+
+Better progression:
+
+```text
+text → UTF-8 bytes
+bytes → text
+bytes indexing / immutability
+bytearray mutation
+```
+
+### 3. Broad concepts need maps, not sample trays
+
+Algebrica handles broad topics by organizing subtopics. It does not merely sample a few facts and hope the title carries the rest.
+
+For us, broad pages should either:
+
+1. be scoped explicitly as a first pass / surface map, with links to focused neighbors; or
+2. be split into narrower examples.
+
+Examples that need this discipline include `Testing`, `Modules`, `Packages`, `Type Hints`, `Operators`, `Literals`, `Bytes and Bytearray`, and the type-system cluster.
+
+### 4. Teaching artifacts should be inspectable
+
+Algebrica releases source Markdown and editable SVGs. The lesson is not that Python By Example needs more diagrams; it is that core teaching artifacts should be inspectable, reusable, and versioned.
+
+For Python By Example, the inspectable artifacts are:
+
+- Markdown examples
+- `:::program` complete runner source
+- `:::cell` teaching fragments
+- expected output
+- official docs links
+- generated embedded source
+- tests and golden parity fixtures
+- rubric and lessons learned docs
+
+### 5. Cross-links should express prerequisites and next depth
+
+Algebrica links to prerequisite concepts and deeper topics as part of the explanation, not as decorative tags.
+
+For us, `See also` links should keep behaving like a conceptual graph:
+
+```text
+operators → assignment-expressions, operator-overloading
+literals → strings, bytes-and-bytearray, dicts
+bytes-and-bytearray → strings, networking
+ type-aliases → type-hints, newtype
+```
+
+### 6. Edge cases belong near the main idea
+
+The definite-integrals page introduces positive/negative area and improper integrals after the main computation story. Edge cases are part of the concept, not trivia hidden at the end.
+
+For Python examples, this suggests adding visible boundary cells for common misunderstandings:
+
+- `json`: non-JSON Python objects or decode errors
+- `testing`: failing-test output or what the result object records
+- `bytes-and-bytearray`: indexing bytes yields integers; `bytes` is immutable
+- `type-hints`: hints inform tools but do not enforce runtime behavior
+- `operators`: precedence and parentheses
+
+### 7. Process transparency builds trust
+
+Algebrica documents editorial process, source reuse, licensing, and revision. Python By Example should continue to surface its own trust signals:
+
+- official Python docs links
+- deterministic expected output
+- verification scripts
+- CI
+- cache/versioning checks
+- public Markdown source
+- quality rubric
+- lessons learned
+
+## Rubric changes implied
+
+Add or strengthen these rubric checks:
+
+1. **Editorial progression** — broad examples need a visible sequence, not a grab bag.
+2. **Scope contract** — title, summary, and first paragraphs must match the breadth of the code.
+3. **Reduction without distortion** — examples may be small, but not at the cost of removing a necessary boundary, contrast, or edge case.
+4. **Map-or-split rule** — broad pages must either become surface maps with links to focused neighbors or be split into narrower pages.
+5. **Edge case placement** — common edge cases should appear in cells or concrete notes near the main idea.
+6. **Inspectable artifact quality** — Markdown source should remain clean enough to serve as public educational material, not merely runtime input.
+7. **Conceptual links as graph edges** — `See also` should mark prerequisite/neighbor/next-depth relationships.
+
+## Known improvement queue
+
+### Improve existing examples
+
+High priority:
+
+- `bytes-and-bytearray` — split one compressed cell into encode/decode/immutability-mutation cells.
+- `type-aliases` — replace generic prose; contrast `type` aliases, assignment-style aliases, and `NewType`.
+- `operators` — monitor for sample-tray drift; add precedence/parentheses if readers need it.
+- `literals` — keep as source-syntax map; ensure it does not pretend to teach every value type deeply.
+
+Type-system cluster:
+
+- `runtime-type-checks`
+- `union-and-optional-types`
+- `typed-dicts`
+- `callable-types`
+- `generics-and-typevar`
+- `casts-and-any`
+- `newtype`
+
+Each should gain at least one contrast cell showing static-tool meaning versus runtime behavior or misuse boundary.
+
+Medium priority:
+
+- `numbers` — link complex literal syntax to `literals`; consider future `decimal-and-fractions`.
+- `modules` — scope as imports/namespaces; consider entry-point/import-system follow-ups.
+- `packages` — optionally add an illustrative package tree as `:::unsupported` or prose.
+- `regular-expressions` — keep scoped as first pass; consider flags/substitution only as focused follow-ups.
+- `testing` — consider failing-test output or fixtures if deterministic output stays readable.
+- `json` — consider indentation, decode errors, or non-JSON objects as a boundary cell.
+- `decorators` — consider `functools.wraps` metadata preservation.
+- `context-managers` — consider a small `__enter__` / `__exit__` protocol cell or stronger link to data model examples.
+- `exceptions` — consider `else` / `finally` cleanup if reliability coverage needs it.
+
+### Create new examples
+
+Potential focused pages:
+
+- `decimal-and-fractions`
+- `module-entry-points`
+- `import-system`
+- `regex-substitution`
+- `regex-flags`
+- `test-fixtures`
+- `pytest-style-tests`
+- `json-errors`
+- `operator-precedence`
+- `exception-cleanup`
+
+### Journey changes to consider
+
+- **Runtime** — ensure `Literals` and `Operators` remain placed by prerequisite logic, not catalog convenience.
+- **Control Flow** — keep `Operators` before `Conditionals` only while the page covers comparisons and boolean expressions.
+- **Types** — add contrast cells before adding more type pages; avoid a long list of shallow type examples.
+- **Reliability** — consider whether `Testing`, `Logging`, `Exceptions`, and cleanup examples form a stronger progression if `exception-cleanup` or `test-fixtures` is added.
+- **Interfaces** — keep the data-model sequence coherent: `Special Methods` → focused protocol pages → `Descriptors` → `Metaclasses`.
+
+### Remove or avoid
+
+- Avoid restoring a combined `Operators and Literals` page.
+- Avoid broad catch-all pages that merely list syntax without a learning progression.
+- Avoid adding new examples to journeys unless they strengthen the story rather than lengthen the index.