Python extension to run WebAssembly binaries
Project description
Wasmer Python
A complete and mature WebAssembly runtime for Python based on Wasmer.
Features:
- Easy to use: The
wasmer
API mimics the standard WebAssembly API, - Fast:
wasmer
executes the WebAssembly modules as fast as possible, close to native speed, - Safe: All calls to WebAssembly will be fast, but more importantly, completely safe and sandboxed,
- Modular:
wasmer
can compile the WebAssembly modules with different engines or compiler.
Documentation: browse the detailed API documentation full of examples.
Examples as tutorials: browse the examples/
directory,
it's the best place for a complete introduction!
Quick Introduction
The wasmer
package brings the required API to execute WebAssembly
modules. In a nutshell, wasmer
compiles the WebAssembly module into
compiled code, and then executes it. wasmer
is designed to work in
various environments and platforms: From nano single-board computers
to large and powerful servers, including more exotic ones. To address
those requirements, Wasmer provides 2 engines and 3 compilers.
Succinctly, an engine is responsible to drive the compilation and
the execution of a WebAssembly module. By extension, a headless
engine can only execute a WebAssembly module, i.e. a module that has
previously been compiled, or compiled, serialized and deserialized. By
default, the wasmer
package comes with 2 headless engines:
wasmer.engine.JIT
, the compiled machine code lives in memory,wasmer.engine.Native
, the compiled machine code lives in a shared object file (.so
,.dylib
, or.dll
), and is natively executed.
Because wasmer
does not embed compilers in its package, engines are
headless, i.e. they can't compile WebAssembly module; they can only
execute them. Compilers live in their own standalone packages. Let's
briefly introduce them:
We generally recommend wasmer_compiler_cranelift
for development
purposes and wasmer_compiler_llvm
in production.
Learn more by reading the documentation of the wasmer.engine
submodule.
Install
To install the wasmer
Python package, and let's say the
wasmer_compiler_cranelift
compiler, just run those commands in your shell:
$ pip install wasmer==1.0.0b2
$ pip install wasmer_compiler_cranelift==1.0.0b2
And you're ready to get fun!
Example
We highly recommend to read the
examples/
directory, which contains a sequence of examples/tutorials. It's the
best place to learn by reading examples.
But for the most eager of you, and we know you're numerous you
mischievous, there is a quick toy program in
examples/appendices/simple.rs
, written in Rust:
#[no_mangle]
pub extern fn sum(x: i32, y: i32) -> i32 {
x + y
}
After compilation to WebAssembly, the
examples/appendices/simple.wasm
binary file is generated. (Download
it).
Then, we can excecute it in Python:
from wasmer import engine, Store, Module, Instance
from wasmer_compiler_cranelift import Compiler
# Let's define the store, that holds the engine, that holds the compiler.
store = Store(engine.JIT(Compiler))
# Let's compile the module to be able to execute it!
module = Module(store, open('simple.wasm', 'rb').read())
# Now the module is compiled, we can instantiate it.
instance = Instance(module)
# Call the exported `sum` function.
result = instance.exports.sum(5, 37)
print(result) # 42!
And then, finally, enjoy by running:
$ python examples/appendices/simple.py
Development
The Python extension is written in Rust, with pyo3
and
maturin
.
First, you need to install Rust and Python. We will not make you the
affront to explain to you how to install Python (if you really need,
check pyenv
). For Rust though, we
advise to use rustup
, then:
$ rustup install stable
To set up your environment, you'll need just
, and then, install
the prelude of this project:
$ cargo install just
$ just --list # to learn about all the available recipes
$ just prelude
It will install pyo3
and maturin
for Python and for Rust. It will
also install virtualenv
.
Then, simply run:
$ source .env/bin/activate
$ just build api
$ just build compiler-cranelift
$ python examples/appendices/simple.py
Supported platforms
We try to provide wheels for as many platforms and architectures as possible. For the moment, here are the supported platforms and architectures:
Platform | Architecture | Triple | Packages | |
---|---|---|---|---|
Linux | amd64 |
x86_64-unknown-linux-gnu |
wasmer |
✅ |
wasmer_compiler_singlepass |
✅ | |||
wasmer_compiler_cranelift |
✅ | |||
wasmer_compiler_llvm |
✅ | |||
aarch64 |
aarch64-unknown-linux-gnu |
wasmer |
✅ | |
wasmer_compiler_singlepass |
❌ 1 | |||
wasmer_compiler_cranelift |
✅ | |||
wasmer_compiler_llvm |
✅ | |||
Darwin | amd64 |
x86_64-apple-darwin |
wasmer |
✅ |
wasmer_compiler_singlepass |
✅ | |||
wasmer_compiler_cranelift |
✅ | |||
wasmer_compiler_llvm |
✅ | |||
Windows | amd64 |
x86_64-pc-windows-msvc |
wasmer |
✅ |
wasmer_compiler_singlepass |
✅ | |||
wasmer_compiler_cranelift |
✅ | |||
wasmer_compiler_llvm |
❌ 2 |
Notes:
- 1
wasmer_compiler_singlepass
does not supportaarch64
for the moment - 2
wasmer_compiler_llvm
is not packaging properly on Windows for the moment
Wheels are all built for the following Python versions:
- Python 3.6,
- Python 3.7,
- Python 3.8.
- Python 3.9.
Learn about the “fallback” py3-none-any
wheel
py3-none-any.whl
A special wasmer-$(version)-py3-none-any
wheel is built as a
fallback. The wasmer
libray will be installable, but it will raise
an ImportError
exception saying that “Wasmer is not available on
this system”.
This wheel will be installed if none matches before (learn more by reading the PEP 425, Compatibility Tags for Built Distributions).
Testing
Build all the packages and run the tests:
$ just build-all
$ just test
What is WebAssembly?
Quoting the WebAssembly site:
WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine. Wasm is designed as a portable target for compilation of high-level languages like C/C++/Rust, enabling deployment on the web for client and server applications.
About speed:
WebAssembly aims to execute at native speed by taking advantage of common hardware capabilities available on a wide range of platforms.
About safety:
WebAssembly describes a memory-safe, sandboxed execution environment […].
License
The entire project is under the MIT License. Please read the
LICENSE
file.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distributions
Hashes for wasmer-1.0.0_beta2-cp39-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8bba6b14b650ea99b4cca92e54342d4d4772f9016e84986752ddedd24ae4ec1d |
|
MD5 | b2300d97cc14df9c8af5889ed8376227 |
|
BLAKE2b-256 | d500965bc46a916f92f006fe61631535491aeb2e75e9c84c6e6dad8e403e879f |
Hashes for wasmer-1.0.0_beta2-cp39-cp39-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 63aaa52969e2eb5a4008924f13aa6bc628af9726f360c00a23e5baf6d5d14a28 |
|
MD5 | 0dad3692a14a1645ad5fcda2eafe04e0 |
|
BLAKE2b-256 | f01aeddc975f112c32b4ecb388d2e2cfaa7b1cece18fce32e6a835ee4823a890 |
Hashes for wasmer-1.0.0_beta2-cp39-cp39-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 93683f266723efc9f129bb4a2d4ca59128e1db0a3d3d881dfe43af14ec694dc4 |
|
MD5 | 6f835246fd0773d1dd8cd7702a4b45bd |
|
BLAKE2b-256 | 764a8e9f25619cdb13f282c8172604b194355f91833875444043247a5b34fce5 |
Hashes for wasmer-1.0.0_beta2-cp38-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4959ade7b2567aef8454a471d2655a7b78af3556cc857bf89382d55bf0639e93 |
|
MD5 | 53fa5c29177a3a58226b6495ac4d7014 |
|
BLAKE2b-256 | 68770a52244c52d0d1b2908b295272567958959545bf187001652264b0840a2a |
Hashes for wasmer-1.0.0_beta2-cp38-cp38-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0cee6d96eb036f0f0468641268f36bcdd05bc50f746aae6a45f9078912f116c9 |
|
MD5 | 07635c1cbf30ea1f87b7ff340551de06 |
|
BLAKE2b-256 | 8fe58f7eb4f7dc2df2cc8db1b34a73e13396f27e0d8ec94fa3ea898edac20c8e |
Hashes for wasmer-1.0.0_beta2-cp38-cp38-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 01ed3858d5177693c0ded6d76e6ba77d3e40e455895359fcbf9a9f679c35ae20 |
|
MD5 | 7c55b1c52889e6594211500b7a5c3d96 |
|
BLAKE2b-256 | 2f7ac978f9edfab988b15aecbb5018630e360256711a98bda9461161d21ce286 |
Hashes for wasmer-1.0.0_beta2-cp37-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a4aebc88919dc47be676ac891800f02f52c1f32bcc696a2c2673c55619e6448e |
|
MD5 | b7c54e267bc7735dc9fa90bfba83614a |
|
BLAKE2b-256 | 6f8d60e1286e95da666bd48074fb02233f2183fb60800c90888cb6cea7269498 |
Hashes for wasmer-1.0.0_beta2-cp37-cp37m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7aa16cc557a63a89a9aaebeac26ecbb67266f8fc7ed84d99f8d22876f0bf19a1 |
|
MD5 | 4ff7a7793d7dbf5ec8e912081180d5e7 |
|
BLAKE2b-256 | ea164f1ebe6c76fda0de256e2f553f1cd42728808861e2e97fb366c5e1a37062 |
Hashes for wasmer-1.0.0_beta2-cp37-cp37m-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fda9b7a908d62879a55779e681d4dd046fe6481ad6fbe5a043b669a8b0525bf9 |
|
MD5 | a94171e87bc575fae2a3fdc4547dbbd4 |
|
BLAKE2b-256 | a3131264206731d901618f8e5a52ea6a45c8614d95642f207cc472d10c65704f |
Hashes for wasmer-1.0.0_beta2-cp36-none-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 28fbb063df344b2a222f6a2a23c12cb0fef5d089d5e7e518e1bb4c05be9acb8c |
|
MD5 | 7579f75517a02b1e6ec14705c79ddd84 |
|
BLAKE2b-256 | 94dfbe94414a3e33386ede237b22df8c5b79862da659e6fcd1ada00c15d59b15 |
Hashes for wasmer-1.0.0_beta2-cp36-cp36m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 26c10e2d94083739f4a42e424a9cea8efb25cdccf9c9e9e5a7429a931a1fe7b3 |
|
MD5 | 541ef38516139cad015b329ba487b8c1 |
|
BLAKE2b-256 | 910e41a5df293c5f7c77adebb8da65779390b8d267f5425b3c85eb69021e1d63 |
Hashes for wasmer-1.0.0_beta2-cp36-cp36m-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7c2434a717397ba194a81c7698ccdcfc0000cc0bfdacaf9e2deed2a0ba5818ac |
|
MD5 | 0080859a9dda8910922b61906859bbc2 |
|
BLAKE2b-256 | 2994536b463eea014dd3cef575c9b0f7506eafbf6164a0038cdedb9ac416d4c5 |