puzzle-widget

A Jupyter widget where students drag scrambled code lines into the correct order, built on anywidget.

Tag a cell %%puzzle <result>; every line below it becomes a draggable row, shuffled so the student starts from a scrambled order. Drag (or focus a row and press the arrow keys) to reorder them -- the widget re-runs the current order after every move and shows a checkmark once it produces <result>.

import puzzle_widget  # registers the %%puzzle cell magic

%%puzzle 15
a = 10
b = 5
a + b

Write the lines in whatever order reads best -- the correct one included: the widget shuffles them before showing them, and never starts from an order that already produces <result>. Dragging them back into a working order produces 15 and the widget shows "✓ Correct!".

The shuffle is seeded, so a given puzzle always starts in the same scrambled order -- every student sees the same starting point, and a puzzle you tested looks the same when you teach it. Pass seed= to PuzzleWidget for a different one.

Installation

# pixi
pixi workspace channel add munch-group
pixi add puzzle-widget

# conda
conda install -c munch-group puzzle-widget

# pip
pip install puzzle-widget

Writing a puzzle

• <result> is a Python literal (a number, string, list, ...), parsed with ast.literal_eval -- not an arbitrary expression, since the puzzle runs in its own isolated namespace, not the notebook's.
• Every line must be a complete, independent, non-indented statement. A puzzle can't contain multi-line blocks (if/for/def/...) that need to stay attached to each other, since any permutation of the lines has to at least parse -- only the values it produces should depend on the order.
• The result is the value of the last line, which must be a bare expression (a + b, or a variable's name on its own) -- exactly like a notebook cell only shows output for a trailing expression, not for an assignment. If the puzzle's final step is total = a + b, add a total line after it so there's a value to check.

You can also build a widget directly from a list of lines:

from puzzle_widget import PuzzleWidget

PuzzleWidget(["a = 10", "b = 5", "a + b"], expected=15)

Documentation

Full docs live at munch-group.org/puzzle-widget.

Development

This repo is managed with pixi:

pixi run install-dev   # editable install into the pixi environment
pixi run test          # run the pytest suite
pixi run docs          # execute the documentation notebooks
pixi run api           # build the quartodoc API reference

License

MIT