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