peterhuene/componentize-py

componentize-py

A Bytecode Alliance project

This is a tool to convert a Python application to a WebAssembly component. It takes the following as input:

• a WIT file or directory
• the name of a WIT world defined in the above file or directory
• the name of a Python module which targets said world
• a list of directories in which to find the Python module and its dependencies

The output is a component which may be run using e.g. wasmtime.

Getting Started

First, install Python 3.10 or later and pip if you don't already have them. Then, install componentize-py:

pip install componentize-py

Next, create or download the WIT world you'd like to target, e.g.:

cat >hello.wit <<EOF
package example:hello
world hello {
  export hello: func() -> string
}
EOF

If you're using an IDE or just want to examine the bindings produced for the WIT world, you can generate them using the bindings subcommand:

componentize-py -d hello.wit -w hello bindings .

Then, use the hello module produced by the command above to write your app:

cat >app.py <<EOF
import hello
class Hello(hello.Hello):
    def hello(self) -> str:
        return "Hello, World!"
EOF

And finally generate the component:

componentize-py -d hello.wit -w hello componentize app -o app.wasm

See the examples directories for more examples, including various ways to run the components you've created.

For an example of running a sandboxed Python guest within a Python host, see component-sandbox-demo.

Known Limitations

This project does not yet support interface versions, but it's coming soon.

Currently, the application can only import dependencies during build time, which means any imports used at runtime must be resolved at the top level of the application module. For example, if x is a module with a submodule named y the following may not work:

import x

class Hello(hello.Hello):
    def hello(self) -> str:
        return x.y.foo()

That's because importing x does not necessarily resolve y. This can be addressed by modifying the code to import y at the top level of the file:

from x import y

class Hello(hello.Hello):
    def hello(self) -> str:
        return y.foo()

This limitation is being tracked as issue #23.

See the issue tracker for other known issues.

Contributing

See CONTRIBUTING.md for details on how to contribute to the project and build it from source.