From 88a98a3fe8c8a910c6de17d79e8811e51ba3040d Mon Sep 17 00:00:00 2001 From: hartsock Date: Fri, 5 Jun 2026 19:28:29 -0400 Subject: [PATCH] docs: declare Python<->Rust interop focus and course roadmap WHAT: README gains a domain statement (Python <-> Rust interop is the course's specific domain and the Gilamonster Foundation's contribution focus) and a Course Roadmap section: ch5 CLI tools, ch6 FFI & PyO3, ch7 PyO3 house style, ch8 escaping the GIL with Rust threads, ch9 using Rust's type system to harden Python, ch10 real-crate speedup case study (lands when the Hermes-Thoon crates are published). Shipped chapters (1-4) split from planned ones. WHY: the course needed its destination written down so chapters land toward it instead of accreting. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7d0291e..1d982ac 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,14 @@ data provenance (knowing where your data came from and that it hasn't been tampered with), and CLI tools that carry their own context instead of demanding the user carry it for them. +**Where this is headed: Python ↔ Rust interop.** That is this course's +specific domain — and the Gilamonster Foundation's contribution focus. The +destination is not "rewrite it in Rust"; it is knowing how to reach for Rust +*from* Python: binding Rust crates into Python packages, escaping the GIL +with real threads, and borrowing Rust's type system to harden Python APIs — +so the part of your codebase that needs to be fast or correct can be, without +giving up everything that makes Python productive. + ## Prerequisites - Comfortable reading and writing Python @@ -26,8 +34,25 @@ demanding the user carry it for them. | 2 | **Error Handling** | `try/except`, `None`, `LBYL vs EAFP` | `Result`, `Option`, `?` operator | | 3 | **Traits & Generics** | ABCs, Protocols, duck typing | Traits, generics, trait bounds | | 4 | **Content-Addressable Data** | `hashlib`, `json.dumps(sort_keys=True)` | BLAKE3, serde, CIDs, deterministic serialization | + +## Course Roadmap + +The arc from here bends toward the interop boundary — each planned chapter +takes one thing Python developers wish they had and shows how Rust provides +it *to* Python, not instead of it: + +| # | Title | Python Concept | Rust Concept | +|---|-------|---------------|--------------| | 5 | **CLI Tools** | `argparse`, `click` | `clap`, structured output, self-documenting tools | -| 6 | **FFI & PyO3** | `ctypes`, C extensions | PyO3, calling Rust from Python | +| 6 | **FFI & PyO3** | `ctypes`, C extensions, wheels | PyO3 bindings, `maturin`, packaging Rust as a Python module | +| 7 | **PyO3 House Style** | "how should this feel from Python?" | feature-gated bindings, error mapping to exceptions, zero-copy data exchange | +| 8 | **Escaping the GIL** | `threading` vs `multiprocessing`, the GIL | `Send`/`Sync`, `rayon`, releasing the GIL across FFI calls | +| 9 | **Types That Travel** | type hints, `mypy`, runtime validation | newtypes, exhaustive enums, type-safe IDs surfacing as Python types | +| 10 | **Case Study: Speed Where It Counts** | profiling a real hot path | swapping it for a published Rust crate and measuring the win | + +Chapter 10 lands when the Foundation's own crates (the Hermes-Thoon line) +are published — the case study will use real, released code rather than a +toy benchmark. ## How to Use This Course