Metadata-Version: 2.4
Name: basthon-turtle
Version: 0.4.0
Summary: A Python turtle implementation with live SVG rendering across Jupyter, Marimo, Pyodide, and standalone CPython.
Author: Maciej Olko
Author-email: Maciej Olko <maciej.olko@gmail.com>
License-Expression: GPL-3.0-or-later
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Interpreters
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Dist: anywidget>=0.9 ; extra == 'notebook'
Requires-Dist: anywidget>=0.9 ; extra == 'sidecar'
Requires-Dist: sidecar>=0.8 ; extra == 'sidecar'
Requires-Dist: websockets>=14 ; extra == 'standalone'
Requires-Python: >=3.4
Project-URL: Homepage, https://github.com/m-aciek/basthon-turtle
Project-URL: Changelog, https://github.com/m-aciek/basthon-turtle/blob/main/CHANGELOG.md
Provides-Extra: notebook
Provides-Extra: sidecar
Provides-Extra: standalone
Description-Content-Type: text/x-rst

Basthon Turtle is a browser-friendly implementation of Python's
``turtle`` module. It keeps the familiar turtle API while replacing the Tk
canvas with SVG, so turtle programs can run in notebooks and browser-based
Python environments.

The package supports four display environments:

* CPython with an optional standalone browser window;
* Jupyter with a persistent inline SVG widget or optional JupyterLab sidecar;
* Marimo with a persistent AnyWidget canvas; and
* Pyodide, where a Web Worker sends incremental drawing updates to an SVG
  page without a Python server or WebSocket.

The rendering backends share turtle state and drawing operations, while each
environment supplies its own transport and display. The traditional
``done()`` workflow remains available, and ``svg()`` returns the current SVG
scene.

Installation
------------

.. code:: bash

    pip install basthon-turtle

For a live, persistent browser window in a regular CPython session, install
the standalone extra:

.. code:: bash

    pip install "basthon-turtle[standalone]"

or

.. code:: python

    import micropip
    await micropip.install('basthon-turtle')

Usage
-----

When reusing a Python process, call ``turtle.restart()`` to reset the screen
and turtle state.

Standalone CPython
==================

The browser starts lazily on the first visible turtle operation. It remains
alive between commands and receives incremental drawing updates:

.. code:: python

    from turtle import *

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

Jupyter
=======

Install the portable persistent Jupyter renderer with:

.. code:: bash

    pip install "basthon-turtle[notebook]"

Turtle commands are buffered during each cell and animated in one persistent
inline SVG widget after the cell finishes:

.. code:: python

    from turtle import forward, left

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

For a JupyterLab-specific panel, install ``basthon-turtle[sidecar]`` instead.
Call ``jupyter_sidecar(False)`` before drawing to force the portable inline
widget when ``sidecar`` is otherwise available.

Marimo
======

Install the native persistent Marimo renderer with:

.. code:: bash

    pip install "basthon-turtle[notebook]"

.. code:: python

    from turtle import forward, left

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

The first visible operation mounts a persistent AnyWidget in the current cell.
Later turtle calls update the same canvas automatically; no explicit done()
call is required.

Browser-only Pyodide
====================

Plain Pyodide can host the live mode entirely in one browser tab. The example
runs Python in a Web Worker and forwards incremental turtle operations to a
persistent SVG renderer with ``postMessage``. This keeps animation responsive
without a localhost server or WebSocket; see ``docs/pyodide.md`` for a
complete example.


Credits
-------
- bearney74
- André Roberge
- Romain Casati
