wasmhost

WebAssembly from CPython, PyPy and Pythonista, with the JavaScript WebAssembly API. It runs on whichever backend is available: JavaScriptCore's JSContext in Pythonista on iOS, WebKitGTK's JavaScriptCore on Linux, Node, or, when installed, wasmtime or wasm3. Plain Python, no dependencies, no C extension of its own.

import wasmhost

module = wasmhost.Module(open("lib.wasm", "rb").read())  # WebAssembly.Module
instance = wasmhost.Instance(module)  # WebAssembly.Instance
print(instance.exports.add(2, 3))  # i32/i64 -> int, f32/f64 -> float
instance.exports.memory.write(ptr, b"data")  # WebAssembly.Memory
print(instance.exports.counter.value)  # WebAssembly.Global

See examples/basic.py, and for something bigger, both in a bare JavaScript engine:

• examples/pyodide.py: a Python REPL that runs in Pyodide (CPython built to WebAssembly), with a memory snapshot per backend, fetch served by Python and packages kept between sessions. It started as a gist for a Pythonista JSContext.
• examples/jslinux.py: a Linux virtual machine (JSLinux, riscv64 or x86_64 Alpine), with its console on your terminal.

Both keep their downloads in $WASMHOST_CACHE, else ~/.cache/wasmhost, else ./.cache where there is no usable home directory (PythonIDE).

• Types. The JavaScript API can't tell a function's signature, and it matters (an i64 argument must reach JavaScript as a BigInt), so the binary's type, import, function, global and export sections are read in Python. Module.exports(module) and Module.imports(module) describe a module with them.
• Errors are the API's: CompileError, LinkError and Trap (WebAssembly.RuntimeError, which is also a RuntimeError); an out-of-bounds memory access is an IndexError.
• Memory is copied, not shared: memory.read(offset, n), memory.write(offset, data), memory[a:b], memory.grow(pages).

Installation

uv

uv add wasmhost

# With wasmtime, the in-process JIT (otherwise Node or WebKitGTK JavaScriptCore is used)
uv add wasmhost[wasmtime]

pip

pip install wasmhost

# With wasmtime, the in-process JIT (otherwise Node or WebKitGTK JavaScriptCore is used)
pip install wasmhost[wasmtime]

The wasm3 backend has no extra: pywasm3's PyPI release is years behind the API used here, so install it from git (CPython 3.11+, needs a C compiler): pip install "pywasm3 @ git+https://github.com/wasm3/pywasm3".

Pythonista and PythonIDE (iOS)

The ordinary wheel: it is pure Python (py3-none-any). In StaSh (Pythonista) or PythonIDE's pip, pip install wasmhost, then run the self-test (see Try it on a device).

Batches

On a JavaScript engine every call into it has a fixed cost (a pipe to node, a bridged Objective-C call in Pythonista). A batch does several steps in one trip (on wasmtime and wasm3, in Python), and a step can use the results of the earlier ones:

batch = instance.batch()
ptr = batch.call(instance.exports.alloc, len(data))  # a Ref
batch.write(instance.exports.memory, ptr, data)
status = batch.call(instance.exports.run, ptr)
batch.stop_if_nonzero(status)  # leave the rest out on an error status
out = batch.read(instance.exports.memory, ptr, 16)
batch.run()
out.value  # bytes (`.done` says whether the step ran)

A failing step (a trap, an out-of-bounds access) raises from run(), after the earlier steps' results are set. Only i32 results can be used in arithmetic (ptr * 8, ptr + 4).

Bytes in and out of a JavaScript engine

A program with JavaScript of its own (Pyodide, an emulator) needs to hand the engine files and read results back. JSBackend.put_bytes(target, data) assigns a Uint8Array to a JavaScript expression (__files["a"]), and JSBackend.get_bytes(expr) returns the bytes of one. Through hex everywhere; on JSContext through JavaScriptCore's C API instead (ctypes under objc_util), which fills the array in place, with hex as the fallback if that ever fails. The self-test reports which was used (N bytes via C API or via hex).

Backends

With nothing configured, the first backend that starts wins, in the order shown. Each backend's constructor is its own probe: it fails when its runtime is missing. Choose one with WASMHOST_BACKEND=<name>, wasmhost.set_backend("<name>") or Module(..., backend="<name>"); wasmhost.get_backend().name says which is in use. wasmhost.close() closes the backends it started. (In WebAssembly's words the host is the embedder, the Python side that provides imports; what runs the module is the backend.)

Not every backend can do everything (backend.supports("memory.grow") and supports("table.length") say): wasm3 can't Memory.grow from Python (NotImplementedError; a module's own memory.grow works) and has no tables API.

Try it on a device

The package carries a self-test, since nothing else can be run in Pythonista to see whether this works there:

import wasmhost

wasmhost.selftest()  # or, from a shell: python -m wasmhost [--backend NAME] [--all]

It prints one line per check (the Objective-C bridge in use, WebAssembly and BigInt in the engine, calls, i64, memory, globals, traps, batches, the cost of a call), then N/M passed. If something fails, send the whole output. On a computer, python -m wasmhost --all runs it on every backend that starts.

Where it has been run

The times are one run of the self-test each, so read them as an order of magnitude. Not run on a device: the rubicon-objc bridge (both iOS apps above have objc_util, so it wasn't needed), and imports (see below).

A note on wasmtime and faulthandler

wasmtime installs process-wide signal handlers when its first engine is created, and uses them to catch a trap. Python's faulthandler (on with python -X faulthandler, and in pytest) replaces the handlers when it is enabled after that, and the first trap then ends the process (Fatal Python error: Illegal instruction). Enable it first (or not at all), or start the backend later: this repo's tests/conftest.py does that.

Not yet

• Imports. A module that imports host functions, memories, tables or globals can't be instantiated (NotImplementedError). Python callbacks need a synchronous bridge: native for wasmtime and wasm3, a JavaScript function made from Python for gi-jsc, an Objective-C block for jscontext, and for node a blocking read of the pipe.
• Tables beyond their length, v128 and reference types, multi-value results in a batch.

Test

uv run pytest                            # every backend that starts here
uv run pytest --wasm-backend node        # one backend: it must start, or the run stops with an error
uv run pytest --wasm-backend wasmtime    # or wasm3
uv run pytest --wasm-backend gi-jsc      # needs PyGObject: run it with a system-site-packages venv (see the CI job)
uv run pyright && uv run ruff check