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.

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 and backend-independent Vec2D/TNavigator behavior. 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.