basthon-turtle

A browser-friendly implementation of Python's turtle module. It supports persistent Jupyter and Marimo widgets, the existing static SVG workflow, and a proof-of-concept live standalone mode for regular CPython sessions.

Jupyter

pip install "basthon-turtle[notebook]"

from turtle import *

forward(100)
left(90)
forward(50)

With the notebook extra alone, the first visible operation opens one persistent inline turtle widget. Commands are buffered while a cell runs, then animated in order after the cell finishes. Later cells update the same SVG instead of replaying it.

To open the canvas in a JupyterLab sidecar instead, explicitly install basthon-turtle[sidecar]. Call jupyter_sidecar(False) before the first turtle operation to force inline rendering when sidecar is installed. See the Jupyter documentation for details and the built-in JupyterLab cloned-output workflow.

Marimo

pip install "basthon-turtle[notebook]"

from turtle import forward, left

forward(100)
left(90)
forward(50)

The first visible operation mounts a persistent AnyWidget in the current cell. Later cells update the same canvas immediately, without done() or mo.Html(svg()). See the notebook documentation for details.

Standalone CPython

pip install "basthon-turtle[standalone]"

from turtle import *

forward(100)  # lazily opens a persistent local browser page
left(90)
forward(50)   # appends only this movement; earlier drawing is not replayed

See the standalone mode documentation for behavior, scope, and architecture. A runnable demonstration is available in examples/standalone_live.py.

Browser-only Pyodide

The live renderer can also run entirely in a browser. A Web Worker hosts Pyodide and sends incremental turtle commands to the persistent SVG renderer on the main thread; no localhost Python server or WebSocket is involved. See the Pyodide documentation and examples/pyodide for the host contract and a complete example.

Development

See the testing guide for the Python matrix, environment jobs, local test commands, and informational coverage reports. See the release guide for tag-driven publishing, the one-time Trusted Publisher setup, and TestPyPI runs.

Run the headless CPython turtle compatibility baseline from this checkout:

python -m tools.compatibility_report
python -m tools.compatibility_report --json

Use CPython 3.14 with Tkinter installed; no display is needed. This measures public API coverage, Vec2D/TNavigator behavior, and selected TPen state operations. The badges report available public symbols and passing behavioral checks separately; they do not measure overall compatibility. Tk/rendering compatibility is not measured, Basthon extensions do not reduce compatibility, and known failures are expected in the initial baseline. See the developer guide for tests and regression checks.

License

This project uses GPL-3.0-or-later because it builds on the GPLv3-licensed Basthon turtle implementation by Romain Casati, itself a port of Brython's turtle module. The original attribution and notices are retained in the source.