Add Rust, PyO3, and Maturin chapter (fills the 03_rust stub)

[thewtex]

Summary

Fills the Rust bindings chapter (content/compiled/03_rust.md), which currently
exists only as a stub heading, with a complete Rust, PyO3, and Maturin chapter —
plus a runnable PyO3 example project, a matching Marp slide deck, and a set of
instructor-facing research notes.

Rebased on current main, so the chapter drops straight into the existing Compiled
TOC slot (01_compiled → 02_binding → 03_rust → 04_cibuildwheel); the 03_rust.md
stub is replaced in place and no renumbering is needed.

Why

The Compiled section covers pybind11/nanobind (C++) but leaves Rust as an empty
03_rust.md stub. Rust + PyO3 + maturin is now a mainstream way to ship compiled
Python extensions, so the section needs a self-contained, teachable chapter that
mirrors the book's existing "install-and-lock with pixi" approach and requires no
rustup or system Rust.

What's included

Book chapter — content/compiled/03_rust.md (fills the existing TOC slot). Walks
from motivation through a first extension to shipping wheels: Why Rust → the toolchain
stack → pixi setup → a first extension → build/iterate loop → benchmarking → classes →
native-feeling errors → the GIL and free-threading → shipping wheels → exercises →
where to go next.

Runnable example — examples/2_04_rust_pyo3/, a minimal pixi-managed PyO3
extension. src/lib.rs exposes a GIL-releasing count_primes, a Point #[pyclass],
a sum_as_string function, and a checked_div that raises a Python exception; with a
pytest suite (tests/) and a pure-Python-vs-Rust benchmark (bench.py). Every tool —
the Rust compiler, maturin, Python, pytest — installs from conda-forge via pixi, and
pixi run test / pixi run bench chain a build in front so they never run against a
stale extension.

Slide deck — slides/2_03_rust.md, a Marp deck (theme: simplepy) tracking the
chapter for live presentation.

Instructor notes — instructor-notes/: four research notes (PyO3 current state,
maturin workflows, the pixi/conda-forge Rust toolchain, and the Rust-for-Pythonistas
landscape) plus a synthesis deep-dive with a 30-minute teaching runbook. These carry
Obsidian-style frontmatter and [[wiki-links]] and are deliberately kept out of the
myst.yml TOC, so they are never published into the book. Happy to drop this
directory if it is out of scope for the repo.

Supporting changes

• AGENTS.md — documents the new examples/ and instructor-notes/ directories and
  scopes the "content, not code" note to the book itself (the example is runnable).
• .pre-commit-config.yaml — excludes the pixi-generated pixi.lock from prettier
  (consistent with its linguist-generated marking in .gitattributes).
• .gitignore — ignores agent-local .serena/ tool state (kept alongside the existing
  .venv/ / build/ ignores).

Notes for reviewers

• All prose uses ASCII punctuation (no em/en dashes).
• The example directory keeps the name examples/2_04_rust_pyo3/ because the chapter's
  verbatim captured build transcripts print that path; happy to renumber it to
  2_03_rust_pyo3 if you'd prefer directory numbering to track the chapter, at the cost
  of editing the captured output.
• Instructor-note technical claims were fact-checked against primary sources (PyO3 0.29
  docs, maturin 1.14.1 CLI output, the conda-forge rust feedstock, PEP 803); the
  benchmark timings were captured from a real pixi run bench.
• bun run build-book / build-slides build cleanly and pre-commit/prek passes.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR fills the previously-stubbed Rust bindings chapter with a complete Rust/PyO3/maturin walkthrough, adds a runnable pixi-managed PyO3 example project (with tests + benchmark), introduces a matching Marp slide deck, and adds instructor-facing research/deep-dive notes. It also updates contributor docs and housekeeping (pre-commit + gitignore) to accommodate the new content.

Changes:

• Replace content/compiled/03_rust.md stub with a full Rust/PyO3/maturin chapter aligned to the compiled section flow.
• Add examples/2_04_rust_pyo3/ (pixi toolchain + maturin backend + Rust extension + pytest suite + benchmark).
• Add a slide deck and instructor notes/research to support teaching and deeper reference material.

Reviewed changes

Copilot reviewed 17 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
slides/2_03_rust.md	New Marp deck covering the Rust/PyO3/maturin content for live instruction.
instructor-notes/rust-pyo3-maturin-deep-dive.md	Instructor deep-dive reference + runbook and troubleshooting guidance.
instructor-notes/research/rust-python-landscape.md	Research note motivating Rust in Python ecosystems + positioning of this session.
instructor-notes/research/pyo3-current-state.md	Research note summarizing PyO3 status, APIs, versioning, and support matrix.
instructor-notes/research/pixi-rust-toolchain.md	Research note on conda-forge Rust via pixi, platform/linker realities, and reproducibility.
instructor-notes/research/maturin-workflows.md	Research note on maturin workflows, distribution, and CI scaffolding.
examples/2_04_rust_pyo3/tests/test_pyo3_example.py	Pytest coverage for the example extension’s exposed API.
examples/2_04_rust_pyo3/src/lib.rs	The Rust extension module implementation (functions + Point class + GIL detaching).
examples/2_04_rust_pyo3/README.md	Example usage docs + benchmark output and guidance.
examples/2_04_rust_pyo3/pyproject.toml	PEP 517/660 backend config for maturin + project metadata.
examples/2_04_rust_pyo3/pixi.toml	pixi toolchain + tasks wiring (develop/test/bench) for a reproducible workflow.
examples/2_04_rust_pyo3/pixi.lock	Locked conda-forge toolchain/environment for the runnable example.
examples/2_04_rust_pyo3/Cargo.toml	Rust crate metadata and PyO3 dependency pin.
examples/2_04_rust_pyo3/Cargo.lock	Locked Rust crate dependency graph for the example.
examples/2_04_rust_pyo3/bench.py	Pure-Python benchmark paired against the Rust implementation.
examples/2_04_rust_pyo3/.gitignore	Ignore build artifacts/caches local to the example directory.
content/compiled/03_rust.md	Full Rust/PyO3/maturin chapter replacing the prior stub.
AGENTS.md	Updated repo guidance to include examples/ and instructor-notes/.
.pre-commit-config.yaml	Exclude pixi.lock from prettier (generated file).
.gitignore	Ignore agent-local .serena/ state.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.