PAScratch

PAScratch is a small Python library for building a local HTTP bridge between MIT Scratch and Python. Scratch can send a command to Python, Python safely runs only the functions you registered, and the server sends a plain text response back.

Why this exists

MIT Scratch is great for visual projects, but sometimes you want Python to do extra work: control hardware, read files, call APIs, process data, or run custom logic. PAScratch gives you a simple local server for that interaction.

Quick start

Install the project locally while developing:

python3 -m pip install -e .

Create a Python file:

from PAScratch import ScratchServer

server = ScratchServer(port=9991)

@server.command()
def hello(name="Scratch"):
    return f"Hello, {name}!"

@server.command("add")
def add_numbers(a, b):
    return a + b

server.run()

Run it:

python3 program.py

Or run the included example:

python3 examples/basic_server.py

The server starts at:

http://localhost:9991

Send commands

PAScratch accepts JSON commands:

curl -X POST http://localhost:9991 \
  -H "Content-Type: application/json" \
  -d '{"command":"hello","args":["Mahdi"]}'

Response:

Hello, Mahdi!

You can also send simple text commands:

hello Mahdi
add 2 3

API

ScratchServer(host="localhost", port=9991)

Creates a local server. By default it listens only on your computer.

server = ScratchServer()

@server.command(name=None)

Registers a Python function that Scratch is allowed to call.

@server.command()
def turn_on_led():
    return "LED on"

@server.command("move")
def move_motor(speed):
    return f"Moving at {speed}"

Only registered functions can run. This is safer than using exec.

server.run()

Starts the server and blocks until you press Ctrl+C.

server.storage

A tiny in-memory place to share values between commands:

@server.command()
def set_score(value):
    server.storage.scratch["score"] = value
    return "saved"

@server.command()
def get_score():
    return server.storage.scratch.get("score", 0)

Request formats

JSON

{
  "command": "add",
  "args": [2, 3],
  "kwargs": {}
}

command is required. args and kwargs are optional.

Text

command arg1 arg2 "argument with spaces"

Text values like true, false, none, integers, and floats are converted to Python values.

Health check

Open this in a browser:

http://localhost:9991/health

It returns the server status and registered command names.

{
  "ok": true,
  "name": "PAScratch",
  "commands": ["add", "hello"]
}

Browser helpers

PAScratch sends CORS headers, so a local helper web page can call it from JavaScript:

const response = await fetch("http://localhost:9991", {
  method: "POST",
  headers: {"Content-Type": "application/json"},
  body: JSON.stringify({command: "hello", args: ["Scratch"]})
});
const text = await response.text();

TurboWarp extension

This repo includes a TurboWarp custom extension:

extensions/pascratch.js

To use it:

1. Start your Python server:

python3 program.py

2. Open TurboWarp.
3. Click Extensions.
4. Choose Custom Extension.
5. Load extensions/pascratch.js.
6. Use the PAScratch blocks.

Useful blocks:

set PAScratch server url [http://localhost:9991]
call Python command [get_score]
call Python command [hello] arg [Scratch]
call Python command [add] args [2] [3]
call Python command [setuser] args [mahdi] [1234] [extra]
call Python command [hello] with args [Scratch]
send raw PAScratch text [hello Scratch]
PAScratch status

Command blocks expect PAScratch to return plain text, so reporter blocks can directly show the Python result. The status block still reads /health as JSON.

For the flexible with args input, you can use comma-separated values:

Mahdi, 10, true

Or a JSON array:

["Mahdi", 10, true]

Notes for Scratch

Scratch cannot directly send arbitrary HTTP requests from normal blocks. Common ways to connect Scratch projects to PAScratch include:

• a Scratch extension or modified Scratch environment
• a browser helper page that talks to both Scratch and PAScratch
• Scratch cloud variables plus a separate Python polling script

PAScratch is the Python-side bridge. The Scratch-side transport can be added depending on how you want your Scratch project to communicate.

Safety

PAScratch does not execute raw code from requests. It only runs functions you registered with @server.command(). Keep the default host as localhost unless you understand the network/security risks of exposing it to other devices.