jbourassa/wasmtime-py

Python WebAssembly runtime powered by Wasmtime

wasmtime-py

Python embedding of Wasmtime

A Bytecode Alliance project

Installation

To install wasmtime-py, run this command in your terminal:

$ pip install wasmtime

The package currently supports 64-bit builds of Python 3.6+ on x86_64 Windows, macOS, and Linux

Usage

In this example, we compile and instantiate a WebAssembly module and use it from Python:

from wasmtime import Store, Module, Instance, Func, FuncType

store = Store()
module = Module(store.engine, """
  (module
    (func $hello (import "" "hello"))
    (func (export "run") (call $hello))
  )
""")

def say_hello():
    print("Hello from Python!")
hello = Func(store, FuncType([], []), say_hello)

instance = Instance(store, module, [hello])
run = instance.exports(store)["run"]
run(store)

Be sure to check out the examples directory, which has other usage patterns as well as the full API documentation of the wasmtime-py package.

If your WebAssembly module works this way, then you can also import the WebAssembly module directly into Python without explicitly compiling and instantiating it yourself:

# Import the custom loader for `*.wasm` files
import wasmtime.loader

# Assuming `your_wasm_file.wasm` is in the python load path...
import your_wasm_file

# Now you're compiled and instantiated and ready to go!
print(your_wasm_file.run())

Components

The wasmtime package has initial support for running WebAssembly components in Python with high-level bindings. WebAssembly components are defined by the component model and are a flagship feature under development for Wasmtime and its bindings. Components enable communication between the host and WebAssembly guests with richer types than the numerical primitives supported by core WebAssembly. For example with a component Python can pass a string to wasm and back.

Components are represented as *.wasm binaries in the same manner as core WebAssembly modules. With a component binary you can generate Python bindings with:

$ python -m wasmtime.bindgen the-component.wasm --out-dir the-bindings

An example of using this can be done with the wasm-tools repository. For example with this core wasm module at demo.wat:

(module
  (import "python" "print" (func $print (param i32 i32)))
  (memory (export "memory") 1)

  (func (export "run")
    i32.const 100   ;; base pointer of string
    i32.const 13    ;; length of string
    call $print)

  (data (i32.const 100) "Hello, world!")
)

and with this *.wit interface at demo.wit:

world demo {
  import python: interface {
    print: func(s: string)
  }

  default export interface {
    run: func()
  }
}

And this demo.py script

from demo import Demo, DemoImports, imports
from wasmtime import Store

class Host(imports.Python):
    def print(self, s: str):
        print(s)

def main():
    store = Store()
    demo = Demo(store, DemoImports(Host()))
    demo.run(store)

if __name__ == '__main__':
    main()

$ wasm-tools component new demo.wat --wit demo.wit -o demo.wasm
$ python -m wasmtime.bindgen demo.wasm --out-dir demo
$ python demo.py
Hello, world!

The generated package demo has all of the requisite exports/imports into the component bound. The demo package is additionally annotated with types to assist with type-checking and self-documentation as much as possible.

Contributing

See CONTRIBUTING.md.