Python Friendly Error Messages

Todo:

• Set up automated testing and publishing through GitHub Actions
• Accessibility of output HTML

A small, Pyodide and Skulpt-focused, library that explains Python error messages in a friendlier way, inspired by p5.js's Friendly Error System.

It can be used in browser-based editors (like RPF's Code Editor web component) or any environment that executes Python code through Skulpt or Pyodide.

Features

• Parses and normalises errors from Skulpt or Pyodide (via adapters)
• Matches errors against a copydeck (JSON rules and templates)
• Copydeck-based explanations can be localised
• Returns structured explanations as well as ready-made HTML snippets

Usage

import {
  loadCopydeckFor,
  registerAdapter,
  cpythonAdapter,
  friendlyExplain
} from "python-friendly-error-messages";

await loadCopydeckFor(navigator.language); // falls back to "en"

// register runtimes - Skulpt and Pyodide both appear to emit CPython-style tracebacks,
// so the same adapter handles both. The runtime name you register under is
// added onto the resulting trace
registerAdapter("skulpt", cpythonAdapter);
registerAdapter("pyodide", cpythonAdapter);

// later, when you have an error string and some code:
const result = friendlyExplain({
  error: rawTracebackString,
  code: editorCode,
  runtime: "skulpt" // or "pyodide", matching the adapter/runtime that produced the traceback
});

// result.html is a ready-made snippet
// or use result.title, result.summary, result.steps, result.patch, result.trace

// optionally limit which sections appear in result.html:
const result = friendlyExplain({
  error: rawTracebackString,
  code: editorCode,
  runtime: "skulpt",
  sections: ["title", "summary"] // "why", "steps", "patch", "details" also available
});

See the demo for a full set of examples.

Development

See CONTRIBUTING.md for detailed instructions.

In brief:

npm install
npm run build -- --watch
npm test

Copydecks

Copydecks are JSON files that contain rules and templates for matching and explaining errors. They are stored in copydecks/ and can be edited or added to.

New error explanations can (should) be generated by an LLM, for ease (TODO: add system instructions for this). The generated content must be reviewed and edited by an appropriately-qualified human (eg. learning managers) prior to release, to ensure accuracy and clarity.

Copydecks contain prompts and additional context for localisation.

For management of human-reviewed copydeck content, scripts (in ./scripts) are provided to extract and update copydeck content in a Google Sheet (and re-import it after review).

Building

Create a clean build for distribution:

npm run build:all && npm run build:browser

Output files will be in dist/.

You can now import, and use it, elsewhere (see Usage notes).

The package is published to: https://www.npmjs.com/package/@raspberrypifoundation/python-friendly-error-messages

Publishing

npm login
npm publish