Python extension to run WebAssembly binaries
Project description
Wasmer is a Python library for executing WebAssembly files.
- Easy to use: wasmer API mimics the standard WebAssembly API.
- Fast: wasmer executes the WebAssembly modules at native speed.
- Safe: all calls to WebAssembly will be fast, but more importantly, completely safe and sandboxed.
Install
For instaling wasmer, just run this command in your shell:
$ pip install wasmer
Note: There is a limited set of wheels published so far. More are coming.
Example
There is a toy program in examples/simple.rs
, written in Rust (or
any other language that compiles to Wasm):
#[no_mangle]
pub extern fn sum(x: i32, y: i32) -> i32 {
x + y
}
After compilation to Wasm, we will have a examples/simple.wasm
binary file.
You can download it here.
Then, we can excecute it in Python:
from wasmer import Instance, Value
wasm_bytes = open('simple.wasm', 'rb').read()
instance = Instance(wasm_bytes)
result = instance.call('sum', [Value.i32(5), Value.i32(37)])
print(result) # 42!
And then, finally, enjoy by running:
$ python examples/simple.py
API of the wasm
extension/module
The Instance
class
Instantiates a WebAssembly module represented by bytes, and calls exported functions on it:
from wasmer import Instance, Value
# Get the Wasm module as bytes.
wasm_bytes = open('my_program.wasm', 'rb').read()
# Instantiates the Wasm module.
instance = Instance(wasm_bytes)
# Call a function on it.
result = instance.call('sum', [Value.i32(1), Value.i32(2)])
print(result) # 3
The Value
class
Builds WebAssembly values with the correct types:
from wasmer import Value
# Integer on 32-bits.
value_i32 = Value.i32(7)
# Integer on 64-bits.
value_i64 = Value.i64(7)
# Float on 32-bits.
value_f32 = Value.f32(7.42)
# Float on 64-bits.
value_f64 = Value.f64(7.42)
The Value.[if](32|64)
static methods must be considered as static
constructors.
The to_string
method allows to get a string representation of a
Value
instance:
print(value_i32) # I32(7)
The MemoryView
class
Represents a view over a memory buffer of an instance:
from wasmer import Instance
# Get the Wasm module as bytes.
wasm_bytes = open('my_program.wasm', 'rb').read()
# Instantiates the Wasm module.
instance = Instance(wasm_bytes)
# Call a function that returns a pointer to a string for instance.
pointer = instance.call('return_string')
# Get the memory view, with the offset set to `pointer` (default is 0).
memory = instance.memory_view(pointer)
# Read the string pointed by the pointer.
nth = 0;
string = ''
while (0 != memory.get(nth)):
string += chr(memory.get(nth))
nth += 1
print(string) # Hello, World!
The validate
function
Checks whether the given bytes represent valid WebAssembly bytes:
from wasmer import validate
wasm_bytes = open('my_program.wasm', 'rb').read()
if not validate(wasm_bytes):
print('The program seems corrupted.')
This function returns a boolean.
Development
The Python extension is written in Rust, with rust-cpython
and
pyo3-pack
.
To set up your environment, run only once:
$ just prelude
It will install pyo3-pack
for Python and for Rust. It will also
install virtualenv
.
Then, simply run:
$ .env/bin/activate
$ just rust
$ just python-run examples/simple.py
If you need to interact with Python, or run a specific file, use the following commands:
$ just python-run
$ just python-run file/to/run.py
Finally, to inspect the extension; run:
$ just inspect
(Yes, you need just
).
Testing
Once the extension is compiled and installed (just run just rust
),
run the following command:
$ 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 BSD-3-Clause 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-0.1.4-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8a4e400fd5be4cfa2029e0aaf0388d37a37e5541cc0ce0544bc6d66bac19e354 |
|
MD5 | ee8c18d392ade933843d0c2d57be9780 |
|
BLAKE2b-256 | 8d09374b2c92fdf0a6dc11c069a862bfcca5f9ecd18952e4e3e14b84fb52dead |
Hashes for wasmer-0.1.4-cp37-cp37m-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 14749cb9835f7964eed03dabb0110c992a31f6f0fcd7f5e6a63d473809254707 |
|
MD5 | c7a87c4f559a1759ff10ace4202db3a9 |
|
BLAKE2b-256 | bab55cd2c835b265fbe47b4e94464dde8c957a269c8ef491aeeb9745b6938c15 |
Hashes for wasmer-0.1.4-cp36-cp36m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 16ccaaf739fad0cf7e62d337962566dfe6dd4c1f751cd2596f33926044872a3b |
|
MD5 | 70f8fa8ec6ae9affbb4fb7526cdd5cad |
|
BLAKE2b-256 | 8c56ed784d21e15b9d15cd3177fc0966bd4e3f86e46a29e09c18c7b7cde2cc77 |
Hashes for wasmer-0.1.4-cp36-cp36m-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fb9f5696584944283e1a8364da4cc3bee638a2d2e3fe70e16a62452d89820235 |
|
MD5 | f926418b36c9f446052560279ac0199d |
|
BLAKE2b-256 | b265b599e66caf7debf079640db8c177c9ed1e3bfdd4772d6722090f97177e5d |
Hashes for wasmer-0.1.4-cp35-cp35m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3c5305fa114a3b7364ed390b15ee5ad6c861a959b0d6e7389970b29cd9c14000 |
|
MD5 | fd69866309bb6e282d7cc3228c88e94a |
|
BLAKE2b-256 | ce8d7f10906e7ca14f64052c10d37a43a16f6fa4a6c86cfb5cb20cbfae034ef3 |
Hashes for wasmer-0.1.4-cp35-cp35m-macosx_10_7_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 68f0f301a1b70f79f4240f178124cd2f69b4ad8da0b81874b9fce3c90b4e7b3c |
|
MD5 | 72bd075a49c3c0910b6f908208770019 |
|
BLAKE2b-256 | 17a52ff54d0b98c14522bde143f0fb60eb7b67fd9a83bc91c5cb494dcc1eafea |