A teaching-oriented Python interpreter that requires complete type annotations and progressively unlocks language features through six teaching levels.
spython is built on RustPython for execution and ty (from ruff) for type checking. A similar project for Gleam is sgleam.
- Type checking before execution — all code is type-checked before it runs
- Doctest support — doctests are type-checked and executed
- Teaching levels — progressively unlock Python constructs (functions → selection → types → repetition → classes → full)
- Annotation enforcement — every function parameter, return type, and class variable must be annotated
- Image library — built-in SVG-based graphics library for teaching, inspired by HtDP image teachpacks
- Interactive REPL — syntax highlighting, auto-indent, tab completion, and
built-in commands (
:type,:time,:level,:theme) - WASM support — runs in the browser via a WASM build
Requires Rust (stable). Dependencies are fetched automatically.
cargo build # debug build
cargo build --release # optimized build# Run a script (type-checked)
spython run file.py
# Run with a specific teaching level (0-5)
spython run --level 3 file.py
# Type-check and run doctests (no main execution)
spython check file.py
# Format Python files (powered by ruff)
spython format file.py
# Start the REPL
spython| Level | Name | Allows |
|---|---|---|
| 0 | Functions | def, return, scalars, string indexing |
| 1 | Selection | if/elif/else |
| 2 | User types | class (Enum / @dataclass), match |
| 3 | Repetition | list literals, for, while, += |
| 4 | Classes | full class with methods, dict/set, comprehensions, lambda |
| 5 | Full | unrestricted (only annotations still required) |
Levels 0 through 3 also apply extra restrictions aimed at common beginner
mistakes (all lifted at level 4): conditions must be boolean, bool is
not allowed in arithmetic, chained comparisons are rejected, expression
statements whose result is discarded are rejected, and function parameters
cannot have default values.
spython ships with a minimal subset of the Python standard library. The goal is for students to focus on fundamentals — algorithms, types, and problem-solving — without relying on ready-made solutions from large libraries.
Available modules: dataclasses, enum, typing and math.
The built-in spython.image and spython.world modules are also available
(see below).
Most other standard library modules (os, re, json, random, etc.) are
not available: importing them will produce an error.
spython includes a built-in image library for teaching graphics programming, inspired by the HtDP image teachpacks. Images are rendered as SVG.
Everything is imported from spython.image (colors, styles, shapes, and
functions) and spython.world (animations):
from spython.image import circle, overlay, rectangle, fill, stroke, to_svg, red, blue
image = overlay(circle(30, stroke(red)), rectangle(80, 50, fill(blue)))The library provides:
- Shapes — rectangles, circles, ellipses, triangles (7 constructors), polygons, stars, lines, wedges, bezier curves
- Transformations — rotate, scale, flip, crop
- Composition — overlay, underlay, beside, above (with alignment options)
- Scenes — place images at coordinates, draw lines/polygons/curves
- Text and fonts — text rendering with customizable fonts
- Styles — fill and stroke with color, opacity, width, dash patterns
- Colors — 140+ CSS named colors,
rgb(),rgba() - Animation —
Worldclass for interactive programs,animatefor frame-based animation
The workspace has three crates:
engine— shared library (checker, completion, FFI)cli— CLI binary with REPLwasm— WASM target for browser use
make check # clippy + fmt + ruff format
cargo test --workspace # all tests
make wasm # build WASM binaryMIT — see LICENSE.