Instructor Notes

Overall Lesson Design

This lesson follows a progressive arc from standalone scripts to published packages with compiled extensions. Each episode builds on the previous one, so it is important to teach them in order. The full lesson spans eight episodes with approximately 3 hours of instruction plus 1.5 hours of exercises, suitable for a full-day workshop. A half-day workshop can cover the first five episodes (through Release Engineering), with the remaining three assigned as self-study.

The running example is a small computational chemistry library (chemlib) that evolves from a single script into a full package with Fortran extensions. You do not need domain expertise to teach this lesson; the chemistry content is deliberately minimal and serves only as a realistic motivating example.

Before the Workshop

  • Ensure learners have pixi and uv installed (see the Setup page).
  • Ask learners to create a Test PyPI account before arriving.
  • Have a working internet connection; several episodes download packages.
  • Pre-download the example data files if you expect connectivity issues.

Episode-Specific Notes

Writing Reproducible Python (20 min teaching / 10 min exercises)

  • Start by asking learners how they currently share scripts. This surfaces the pain points that the lesson addresses.
  • The inline script metadata (PEP 723) feature requires uv and may be unfamiliar even to experienced Python users. Emphasize that this is a new standard and not yet widely adopted.
  • The pixi task runner integration is optional but useful for showing how system-level dependencies (like ase) can be pinned alongside Python dependencies.

Modules, Packages, and The Search Path (15 min teaching / 5 min exercises)

  • Learners often confuse “module” (a single .py file) with “package” (a directory with __init__.py). Draw the distinction clearly.
  • The sys.path inspection is the key conceptual moment. Have learners run it interactively and compare outputs.
  • Common misconception: learners may believe import searches the entire filesystem. Clarify that it only searches sys.path entries.

The Project Standard: pyproject.toml (20 min teaching / 10 min exercises)

  • This is the densest episode. Consider a short break before it.
  • The src layout is non-obvious to beginners. Explain that it prevents accidental imports from the working directory instead of the installed package.
  • Walk through the uv init output slowly; there is a lot of generated content.
  • If learners ask about setup.py or setup.cfg, acknowledge them as legacy approaches and redirect to pyproject.toml as the current standard (PEP 621).

Quality Assurance: Testing and Linting (20 min teaching / 10 min exercises)

  • Learners often resist testing because their code “works.” Frame testing as a way to save time when refactoring or onboarding new collaborators.
  • ruff is fast enough to run live. Consider showing a side-by-side of before/after formatting.
  • The --dev flag for development dependencies is a critical concept. Make sure learners understand why linters and test frameworks should not be runtime dependencies.

Release Engineering: Logs and Artifacts (25 min teaching / 15 min exercises)

  • The towncrier fragment workflow may feel heavyweight for small projects. Acknowledge this and explain that it scales well for multi-contributor projects.
  • Publishing to Test PyPI is the highlight of this episode. Have learners actually publish and then install each other’s packages if time permits.
  • Common issue: package name collisions on Test PyPI. Have learners use unique suffixes (e.g., chemlib-<username>).

If It Isn’t Documented, It Doesn’t Exist (25 min teaching / 15 min exercises)

This episode focuses on docstrings and Sphinx. It assumes learners already have a working, tested package with a release pipeline.

  • Start with docstrings, not Sphinx. The “write a NumPy-style docstring” exercise gives learners an immediate, tangible skill even if they never set up Sphinx.
  • Sphinx configuration can feel overwhelming. The episode uses a minimal conf.py with only three extensions: autoapi, viewcode, and intersphinx. Resist the urge to add more.
  • The Shibuya theme is recommended for its clean modern look, but any theme works. If learners prefer Read the Docs, that is fine.
  • The intersphinx challenge is a “wow” moment for many learners. Show how a :class:`numpy.ndarray` reference in a docstring automatically becomes a hyperlink to the NumPy documentation.
  • Common issue: the sys.path.insert line in conf.py must point to the correct relative path for your src directory. If autoapi finds zero modules, this is almost always the cause.
  • The GitHub Pages deployment section introduces GitHub Actions workflow files. Keep it brief; the next episode (CI) covers workflow files in full detail.
  • The PR preview subsection uses a two-workflow pattern (build + comment). If learners ask why, explain the security model: the build runs with the PR author’s limited permissions, while the comment workflow runs with write access only after a successful build. This prevents malicious PRs from exploiting elevated permissions.
  • If time is short, the PR preview can be skipped or shown as a demo. The core value of the episode is docstrings + Sphinx + autoapi.

The Gatekeeper: Continuous Integration (20 min teaching / 10 min exercises)

This episode follows naturally from Quality Assurance (local hooks) and Release Engineering (manual publishing). It closes the loop by automating both. Learners will have already seen a workflow file in the Documentation episode, so the YAML structure should not be entirely new.

  • Many learners will not have used GitHub Actions before. Start by explaining the YAML structure: on (triggers), jobs (what runs), steps (how). The episode includes a “Reading the Workflow” challenge for this purpose.
  • The astral-sh/setup-uv action is the recommended way to install uv in CI. Emphasize the enable-cache: true flag, which dramatically speeds up repeated runs.
  • Build up from a single-OS pipeline to the matrix. This avoids overwhelming learners with the full YAML in one go.
  • The matrix strategy is the key concept. Show the math: 2 Python versions x 3 operating systems = 6 parallel jobs. This is where CI earns its keep.
  • The release job at the end ties back to uvx twine from Release Engineering. Emphasize that needs: check means a broken build is never published.
  • Common issue: Windows path separators. If a learner has hardcoded / in file paths, the Windows job will fail. This loops back to pathlib from the very first episode.
  • If time is short, skip the matrix and just show the basic single-OS pipeline. The matrix can be assigned as homework.

Compiled Extensions: The Shared Object Pipeline (35 min teaching / 15 min exercises)

This is the most advanced episode and serves as the capstone of the lesson. By this point learners have the full toolchain (packaging, testing, docs, CI) and are ready to tackle the binary distribution problem.

  • Gauge the audience and consider making it optional for a shorter workshop.
  • Learners without Fortran experience should not worry; the Fortran code is provided and the focus is on the build pipeline, not the language.
  • The meson-python backend is less common than setuptools. Explain that it exists specifically for compiled code and is used by numpy and scipy.
  • cibuildwheel can take a long time to run in CI. Consider showing pre-recorded output if live demos are not feasible. Learners now understand CI from the previous episode, so the cibuildwheel matrix diagram should feel familiar.
  • The “manual install” challenge (copying .so into site-packages) is deliberately low-level. It demystifies what pip install actually does under the hood and helps learners appreciate why build tools exist.
  • If a learner’s system lacks a Fortran compiler, they can still follow along conceptually; the f2py output is shown in the lesson.

Suggested Workshop Schedules

Half-Day Workshop (3.5 hours, episodes 1-5)

Time Activity
09:00 - 09:30 Reproducible Python (Scripts)
09:30 - 09:50 Modules and the Search Path
09:50 - 10:00 Break
10:00 - 10:30 pyproject.toml with uv
10:30 - 11:00 Quality Assurance
11:00 - 11:10 Break
11:10 - 11:50 Release Engineering
11:50 - 12:30 Q&A / Apply to your own project

This covers the core “script to published package” arc. Documentation, CI, and Compiled Extensions can be assigned as self-study or covered in a follow-up session.

Shorter Session (2 hours, episodes 1-4)

Cover Scripts through Quality Assurance. This gives learners a complete workflow from script to tested package and can be done without internet access (no publishing step).

Full-Day Workshop (all 8 episodes)

Time Activity
09:00 - 09:30 Reproducible Python (Scripts)
09:30 - 09:50 Modules and the Search Path
09:50 - 10:00 Break
10:00 - 10:30 pyproject.toml with uv
10:30 - 11:00 Quality Assurance
11:00 - 11:10 Break
11:10 - 11:50 Release Engineering
11:50 - 12:30 Documentation
12:30 - 13:30 Lunch
13:30 - 14:00 Continuous Integration
14:00 - 14:50 Compiled Extensions
14:50 - 15:00 Break
15:00 - 15:30 Apply to your own project (Q&A)

Timing Guide

Episode Teaching Exercises Total
Reproducible Python 20 min 10 min 30 min
Modules 15 min 5 min 20 min
pyproject.toml & uv 20 min 10 min 30 min
Quality Assurance 20 min 10 min 30 min
Release Engineering 25 min 15 min 40 min
Documentation 25 min 15 min 40 min
Continuous Integration 20 min 10 min 30 min
Compiled Extensions 35 min 15 min 50 min
Total 180 min 90 min 270 min

For a half-day workshop (3.5 hours with breaks), the first five episodes (through Release Engineering) fit comfortably. For a shorter session, stop after Quality Assurance. For a full-day workshop, cover all eight episodes with Documentation and CI in the late morning and Compiled Extensions after lunch.

Common Pitfalls

  • Learners on Windows may have PATH issues with pixi and uv after installation. Have them restart their terminal.
  • Virtual environment confusion: some learners may have conda environments active that interfere with uv. Ask them to deactivate first.
  • The editable install concept (uv pip install -e .) is powerful but can confuse learners who expect changes to require reinstallation. Clarify when editable installs do and do not pick up changes (new files require reinstall).
  • TestPyPI name collisions: package names are global. Have learners append a unique suffix (e.g., chemlib-<username>) to avoid conflicts.
  • Fortran compiler availability: not all systems have gfortran installed. On macOS, learners may need to install it via brew install gcc or use pixi to provide it. On Windows, pixi is the recommended path.
  • The uv run vs python distinction trips up learners who are used to activating virtual environments. Emphasize that uv run is the “batteries included” way to execute code in the project’s environment.
  • If GitHub Actions workflows do not trigger, check that the YAML file is in the default branch and that the file is valid YAML (indentation matters).
  • ruff version pinning: the .pre-commit-config.yaml pins a ruff version. If learners see different lint results locally vs in CI, version mismatch is usually the cause.

Accessibility and Inclusivity

  • All diagrams in the lesson have alt-text descriptions. If projecting slides, read the diagram aloud for visually impaired learners.
  • The lesson uses colour-coded diagrams. Ensure your projector has adequate contrast, and point out the labels rather than relying on colour alone.
  • Terminal font size: increase your terminal font to at least 18pt when live-coding so learners at the back can follow along.
  • Provide the example data files on a USB stick or shared drive if connectivity is unreliable.

Writing Reproducible Python

Modules, Packages, and The Search Path

The Project Standard: pyproject.toml

Quality Assurance: Testing and Linting

The Changelog ProblemBuilding ArtifactsPublishing to TestPyPIAutomating Release (GitHub Actions)

If It Isn't Documented, It Doesn't ExistThe Documentation GapWriting Good DocstringsSetting Up SphinxBuilding the DocumentationDeploying to the Web

The Gatekeeper: Continuous IntegrationThe Limits of Local HooksAnatomy of a Workflow FileThe Test MatrixConnecting CI to Releases

Compiled Extensions: The Shared Object Pipeline