binmod 0.2.1

A Python runtime for Binmod WebAssembly modules

Binmod Runtime for Python

Python runtime for loading and executing Binmod WebAssembly modules in your applications.

Overview

The Binmod Python Runtime allows you to embed WebAssembly-based plugins into your Python applications. Load modules written in any language with a Binmod MDK (Rust, Python, and more coming soon).

Installation

pip install binmod

Load a Module

from binmod import Module, ModuleEnv

mod = Module.from_file(
    "my_calculator.wasm",
    name="my_calculator",
    environment=ModuleEnv.inherit(),
    namespace="calculator",
    host_fns={
        "log": lambda msg: print(f"[Module] {msg}"),
        "get_pi": lambda: 3.14159,
    }
)
mod.instantiate()

Key points:

• name: Identifier for your module
• namespace: Groups related host functions together
• host_fns: Dictionary mapping function names to Python callables that the module can invoke
• All host function parameters and return values must be JSON-serializable

Call Module Functions

Synchronous API:

area = mod.api.circle_area(5.0)
print(f"Circle area: {area}")

sum_result = mod.api.add(10, 20)
print(f"Sum: {sum_result}")

# Alternatively, using the call method
area = mod.call("circle_area", (5.0,))
sum_result = mod.call("add", (10, 20))

Asynchronous API:

area = await mod.api_async.circle_area(5.0)
print(f"Circle area: {area}")

sum_result = await mod.api_async.add(10, 20)
print(f"Sum: {sum_result}")

# Alternatively, using the async call method
area = await mod.call_async("circle_area", (5.0,))
sum_result = await mod.call_async("add", (10, 20))

Complete Example

from binmod import Module, ModuleEnv

# Define host functions that the module can call
def log_message(msg):
    print(f"[Module] {msg}")

def get_pi():
    return 3.14159

# Load the module
mod = Module.from_file(
    "my_calculator.wasm",
    name="my_calculator",
    environment=ModuleEnv.inherit(),
    namespace="calculator",
    host_fns={
        "log": log_message,
        "get_pi": get_pi,
    }
)

# Instantiate the module
mod.instantiate()

# Call module functions
area = mod.api.circle_area(5.0)
# Or alternatively using the call method
# area = mod.call("circle_area", (5.0,))
print(f"Circle area: {area}")

sum_result = mod.api.add(10, 20)
# Or alternatively using the call method
# sum_result = mod.call("add", (10, 20))
print(f"10 + 20 = {sum_result}")

Error Handling

from binmod import FnError

try:
    result = mod.api.circle_area(5.0)
except FnError as e:
    print(f"Module execution error: {e.message}")

Module Compatibility

WebAssembly modules must be compiled with the WASI Preview 1 target. Modules created with any Binmod MDK are compatible with this runtime.

Backwards Compatibility

This runtime is currently in an early stage. Future versions may introduce breaking changes until the API is stabilized. The API is considered stable starting from version 1.0.0.

License

MIT License

Support

If you encounter issues or have questions, please open an issue on GitHub.