Yesterday's post introduced jupyterlab-workshop and showed one page of a workshop. This one writes a whole workshop from an empty directory. It is small enough to fit in a post, but it has everything a real one has: a manifest, four pages, actions that drive the JupyterLab session, checks that run by themselves, a quiz, and the tooling that proves the workshop works before a learner ever sees it.

The subject is pytest. The workshop teaches the loop pytest is built around, which is write a test, watch one fail, fix the code, and it does that in four pages. Because pytest has to be installed, it is a chance to show how a workshop gets a Python environment of its own. It also lets me put the three content lessons from my PyCon talk to work, since a workshop format is only useful if it makes it easier to do those things well.

Plan the steps first

Before writing anything, decide the steps, and for each one decide what proves it was done. That second part is what distinguishes a workshop from a tutorial, and it also happens to be the constraint that keeps the steps small, because a step that ends in something checkable is rarely a big one.

For this workshop there are four. Set things up, which is done when pytest can be run. Write a first test, done when it passes. Add a second test that exposes a bug, done when the learner has predicted what pytest will say and then seen one test fail. Fix the bug, done when both tests pass. The prediction in the third step is the "change one thing and say what you think will happen" pattern from the talk, and the check on every page is the "verify after anything that can silently go wrong" one.

Scaffolding

The jupyter workshop command that comes with the package scaffolds a workshop directory:

jupyter workshop init pytest-first-steps --title "Testing with pytest"

That writes a manifest, two example pages to replace, a README, a .gitignore and an empty files/ directory. I threw the example pages away and made the manifest read:

apiVersion: jupyterlab-workshop/v1alpha1
name: pytest-first-steps
title: Testing with pytest
version: 0.1.0
description: Write a first test with pytest, watch a second one fail, and fix the code it caught.
tags: [python, pytest, testing]
duration: 20m
platforms: [linux, macos]
capabilities:
 - terminal
 - write-files
 - kernel-exec
 - install-packages
environment:
 requirements: requirements.txt
env:
 PYTHONDONTWRITEBYTECODE: "1"
layout: default
gating: soft
pages:
 - pages/01-set-up.md
 - pages/02-first-test.md
 - pages/03-a-failing-test.md
 - pages/04-fix-the-bug.md

The capabilities list is what the learner will be asked to trust when the workshop opens. This one runs commands in a terminal, writes files in the learner's workspace, runs code in a kernel, which the checks need, and installs packages. An action whose capability is not declared never runs, and the linter checks the list against what the pages actually use, in both directions.

The environment field is how the workshop gets pytest. The requirements.txt beside the manifest has one line in it, pytest, and the first page has an action that creates a virtual environment from it. The environment lives inside the workshop directory, so nothing else on the learner's machine changes, and once it exists it is first on the path in the workshop's terminals and in the checks, with no activation step anywhere on a page. A kernel is registered for it too, which a notebook workshop would use. That is far better than walking the learner through python -m venv and pip install, since the workshop is there to teach pytest, not how to create virtual environments.

The env entry guards against a problem that can arise when a file changes in quick succession, which in a workshop happens whenever a learner clicks rapidly through the steps. Python reuses cached bytecode whenever a source file's size and its modification time in whole seconds are unchanged, so an edit that swaps text for text of the same length, made within a second of the previous run, runs the old code. The self-test, which runs actions back to back, hits it even more readily. Turning bytecode caching off makes it go away. The other fields are less interesting. layout: default opens a terminal beneath the main area, and gating: soft means a learner can move past a page whose check has not passed, but is told so, and the page is not marked as done.

The one file the workshop ships to the learner is files/orders.py. Anything in files/ is copied into a work/ directory when the workshop first opens, and that is where the learner works, where the terminals start, and what restarting the workshop empties and refills. The function has a bug in it, on purpose:

"""Order totals for a small shop."""


def total(prices, discount=0):
 """Add up the prices and take off a percentage discount."""

 subtotal = sum(prices)

 return subtotal - discount

Page one: set up

A page is a Markdown file with YAML front matter, and the actions are fenced blocks with the action name in braces. Options are :name: value lines at the top of the block and the rest is the body.

---
title: Set up
requires: [verify:pytest-available]
---

# Set up

pytest is the test runner most Python projects use. In this workshop
you write a test for a small function, add a second test and watch it
fail, then fix the code the test caught.

The function is in `orders.py`, which is already in your workspace.
Open it and read it before going on.

```{file-open}
:path: orders.py
```

pytest is not part of Python, so the workshop needs an environment
with it installed. This creates one inside the workshop directory, so
nothing else on your machine changes.

```{environment-create}
:title: Create the workshop environment
```

Once it exists the workshop terminal picks it up. Confirm pytest is
there.

```{execute}
:id: pytest-version
:wait: prompt
python -m pytest --version
```

```{verify}
:id: pytest-available
:label: pytest is installed
:substrate: shell
:trigger: after:pytest-version
python -m pytest --version
```

The requires line in the front matter says the page is not done until the pytest-available check has passed. The file-open action opens the shipped file in the editor beside the panel, so the learner has read the function before being asked to test it. The environment-create action creates the virtual environment from the requirements file, with the text before it saying why that is needed. The check at the end of the page then confirms that pytest was installed into it, so progress past the page is gated on the environment actually working.

The execute action runs its body in the workshop terminal, and :wait: prompt makes it wait until the shell is back at its prompt before reporting that it is done, rather than the moment the command has been typed. The verify after it is triggered by that completion, so the check runs by itself once the learner has taken the step. The check runs its own command rather than relying on what the terminal did, so here it would pass at any point after the environment exists, but tying it to the step keeps it from running before the learner has got there. The check uses the shell substrate, meaning its body is run as a shell command and exit code zero passes. Its output becomes the message the learner sees with the check, which here is the pytest version.

Page two: the first test

---
title: The first test
requires: [verify:first-test-passes]
---

# The first test

pytest finds tests on its own: any file named `test_*.py`, and in it
any function named `test_*`. A test is a plain function that calls
the code and uses `assert` to say what it expects. This writes one for
`total()` and opens it in the editor.

```{file-write}
:id: write-test
:path: test_orders.py
:open: true
from orders import total


def test_total_adds_the_prices():
 assert total([10, 20]) == 30
```

Run it. The `-q` keeps the output to one character per test and a
summary line.

```{execute}
:id: run-first-test
:wait: prompt
python -m pytest -q
```

A dot is a pass. The check below runs the tests itself, so it passes
whether you clicked the command or typed it.

```{verify}
:id: first-test-passes
:label: The first test passes
:substrate: shell
:trigger: after:run-first-test
out=$(python -m pytest -q --color=no test_orders.py 2>&1) && { printf '%s\n' "$out" | tail -n 1; exit 0; }; printf '%s\n' "$out"; exit 1
```

file-write writes its body to a file in the workspace, and with :open: true shows it in the editor, so the learner sees the test appear rather than being asked to type it. Typing it yourself is more work, and work is where learning happens, but a typo in a file you were told to copy teaches nothing except frustration. Writing the file and opening it in front of them, then having them type the command that runs it, is a reasonable compromise if you want the learner doing some things by hand rather than clicking an action for everything.

The check is worth a closer look, because it is a pattern that repeats through the workshop. A shell check's whole output is its message, so the command shapes it. On success it prints only the last l...

Planet Python

Message History

Delivery option(s)