0
# Wasmtime
1

2
A comprehensive Python library providing high-performance WebAssembly execution through the Wasmtime runtime. This package offers complete Python bindings for WebAssembly module compilation, instantiation, and execution, along with full WASI support, component model integration, and advanced runtime features for serverless computing, plugin systems, and cross-language interoperability.
3

4
## Package Information
5

6
- **Package Name**: wasmtime
7
- **Language**: Python  
8
- **Installation**: `pip install wasmtime`
9
- **Minimum Python**: 3.9+
10

11
## Core Imports
12

13
```python
14
import wasmtime
15
```
16

17
Import individual components:
18

19
```python
20
from wasmtime import Engine, Store, Module, Instance
21
from wasmtime import wat2wasm, WasiConfig, Linker
22
```
23

24
## Basic Usage
25

26
```python
27
import wasmtime
28

29
# Create a WebAssembly engine and store
30
engine = wasmtime.Engine()
31
store = wasmtime.Store(engine)
32

33
# Compile WebAssembly from WAT (WebAssembly Text format)
34
wasm_bytes = wasmtime.wat2wasm('''
35
  (module
36
    (func (export "add") (param i32 i32) (result i32)
37
      local.get 0
38
      local.get 1
39
      i32.add)
40
  )
41
''')
42

43
# Compile the module
44
module = wasmtime.Module(engine, wasm_bytes)
45

46
# Instantiate the module
47
instance = wasmtime.Instance(store, module, [])
48

49
# Call the exported function
50
add_func = instance.exports(store)["add"]
51
result = add_func(store, 5, 3)
52
print(f"5 + 3 = {result}")  # Output: 5 + 3 = 8
53

54
# Using WASI for system interface
55
wasi_config = wasmtime.WasiConfig()
56
wasi_config.inherit_argv()
57
wasi_config.inherit_env()
58
wasi_config.inherit_stdin()
59
wasi_config.inherit_stdout()
60
wasi_config.inherit_stderr()
61

62
# Create linker with WASI support
63
linker = wasmtime.Linker(engine)
64
linker.define_wasi(store, wasi_config)
65
```
66

67
## Architecture
68

69
Wasmtime's Python API follows a hierarchical structure reflecting WebAssembly's runtime model:
70

71
- **Engine**: Top-level compilation engine managing WebAssembly compilation settings and optimizations
72
- **Store**: Runtime state container holding instances, memories, globals, and execution context
73
- **Module**: Compiled WebAssembly module containing validated and optimized code
74
- **Instance**: Live instantiation of a module with allocated memory, globals, and callable functions
75
- **Linker**: Module linking system for resolving imports and connecting multiple modules
76

77
This design enables efficient WebAssembly execution while providing fine-grained control over compilation, memory management, security boundaries, and system interface integration through WASI.
78

79
## Capabilities
80

81
### Core Runtime
82

83
WebAssembly engine configuration, module compilation, and execution environment management. Provides the foundation for all WebAssembly operations including compilation strategies, debugging support, and performance optimizations.
84

85
```python { .api }
86
class Engine:
87
    def __init__(self, config: Config = None): ...
88
    def increment_epoch(self) -> None: ...
89
    def is_pulley(self) -> bool: ...
90

91
class Store:
92
    def __init__(self, engine: Engine = None, data: Any = None): ...
93
    def add_fuel(self, fuel: int) -> None: ...
94
    def fuel_consumed(self) -> int: ...
95
    def set_epoch_deadline(self, ticks: int) -> None: ...
96

97
class Module:
98
    def __init__(self, engine: Engine, wasm: bytes, validate: bool = True): ...
99
    @classmethod
100
    def from_file(cls, engine: Engine, path: str, validate: bool = True) -> 'Module': ...
101
    @staticmethod  
102
    def validate(engine: Engine, wasm: bytes) -> None: ...
103
    def serialize(self) -> bytes: ...
104
    @classmethod
105
    def deserialize(cls, engine: Engine, encoded: bytes) -> 'Module': ...
106
```
107

108
[Core Runtime](./core-runtime.md)
109

110
### WebAssembly Types
111

112
Complete type system mapping WebAssembly value types, function signatures, memory layouts, and table definitions to Python. Includes comprehensive type validation and conversion utilities.
113

114
```python { .api }
115
class ValType:
116
    I32: 'ValType'
117
    I64: 'ValType' 
118
    F32: 'ValType'
119
    F64: 'ValType'
120
    V128: 'ValType'
121
    FUNCREF: 'ValType'
122
    EXTERNREF: 'ValType'
123

124
class FuncType:
125
    def __init__(self, params: List[ValType], results: List[ValType]): ...
126
    @property
127
    def params(self) -> List[ValType]: ...
128
    @property
129
    def results(self) -> List[ValType]: ...
130

131
class Val:
132
    @staticmethod
133
    def i32(val: int) -> 'Val': ...
134
    @staticmethod
135
    def i64(val: int) -> 'Val': ...
136
    @staticmethod
137
    def f32(val: float) -> 'Val': ...
138
    @staticmethod
139
    def f64(val: float) -> 'Val': ...
140
```
141

142
[WebAssembly Types](./types.md)
143

144
### Function Invocation
145

146
Function calling interface supporting both Python-defined and WebAssembly-exported functions. Includes parameter marshalling, result handling, and caller context access for host function implementations.
147

148
```python { .api }
149
class Func:
150
    def __init__(self, store: Store, ty: FuncType, func: Callable, access_caller: bool = False): ...
151
    def type(self, store: Store) -> FuncType: ...
152
    def param_arity(self) -> int: ...
153
    def result_arity(self) -> int: ...
154
    def call(self, store: Store, *args) -> Union[Val, List[Val], None]: ...
155

156
class Caller:
157
    def get_export(self, name: str): ...
158
    
159
class Instance:
160
    def __init__(self, store: Store, module: Module, imports: List): ...
161
    def exports(self, store: Store): ...
162
    def get_export(self, store: Store, name: str): ...
163
```
164

165
[Function Invocation](./functions.md)
166

167
### Memory Management
168

169
Linear memory allocation, access, and manipulation supporting both regular and shared memory models. Includes memory growth, data transfer, and multi-threading coordination.
170

171
```python { .api }
172
class Memory:
173
    def __init__(self, store: Store, ty: MemoryType): ...
174
    def type(self, store: Store) -> MemoryType: ...
175
    def grow(self, store: Store, delta: int) -> int: ...
176
    def size(self, store: Store) -> int: ...
177
    def data_len(self, store: Store) -> int: ...
178
    def data_ptr(self, store: Store) -> int: ...
179
    def read(self, store: Store, start: int, stop: int) -> bytes: ...
180
    def write(self, store: Store, data: bytes, start: int = 0) -> None: ...
181

182
class SharedMemory:
183
    def __init__(self, engine: Engine, ty: MemoryType): ...
184
    def type(self) -> MemoryType: ...
185
    def as_memory(self, store: Store) -> Memory: ...
186
```
187

188
[Memory Management](./memory.md)
189

190
### WASI Integration
191

192
Complete WebAssembly System Interface implementation providing filesystem access, environment variables, command-line arguments, and I/O redirection with comprehensive permission controls.
193

194
```python { .api }
195
class WasiConfig:
196
    def __init__(self): ...
197
    def argv(self, argv: List[str]) -> None: ...
198
    def inherit_argv(self) -> None: ...
199
    def env(self, env: List[Tuple[str, str]]) -> None: ...
200
    def inherit_env(self) -> None: ...
201
    def stdin_file(self, path: str) -> None: ...
202
    def stdout_file(self, path: str) -> None: ...
203
    def stderr_file(self, path: str) -> None: ...
204
    def inherit_stdin(self) -> None: ...
205
    def inherit_stdout(self) -> None: ...
206
    def inherit_stderr(self) -> None: ...
207
    def preopen_dir(self, path: str, guest_path: str, perms: DirPerms) -> None: ...
208

209
class DirPerms:
210
    READ_ONLY: 'DirPerms'
211
    WRITE_ONLY: 'DirPerms' 
212
    READ_WRITE: 'DirPerms'
213

214
class FilePerms:
215
    READ_ONLY: 'FilePerms'
216
    WRITE_ONLY: 'FilePerms'
217
    READ_WRITE: 'FilePerms'
218
```
219

220
[WASI Integration](./wasi.md)
221

222
### Module Linking
223

224
Advanced module linking system for resolving imports, connecting multiple WebAssembly modules, and creating complex WebAssembly applications with shared functionality.
225

226
```python { .api }
227
class Linker:
228
    def __init__(self, engine: Engine): ...
229
    def allow_shadowing(self, enable: bool) -> None: ...
230
    def define(self, store: Store, module: str, name: str, item) -> None: ...
231
    def define_func(self, module: str, name: str, ty: FuncType, func: Callable) -> None: ...
232
    def define_wasi(self, store: Store, wasi_config: WasiConfig) -> None: ...
233
    def define_instance(self, store: Store, name: str, instance: Instance) -> None: ...
234
    def instantiate(self, store: Store, module: Module) -> Instance: ...
235
    def get_default(self, store: Store, name: str): ...
236
```
237

238
[Module Linking](./linking.md)
239

240
### Error Handling
241

242
Comprehensive error handling system including WebAssembly traps, stack traces, runtime errors, and WASI exit codes with detailed debugging information.
243

244
```python { .api }
245
class WasmtimeError(Exception): ...
246

247
class Trap(Exception):
248
    def __init__(self, message: str): ...
249
    @property
250
    def message(self) -> str: ...
251
    @property  
252
    def frames(self) -> List[Frame]: ...
253
    @property
254
    def trace(self) -> List[str]: ...
255

256
class Frame:
257
    @property
258
    def func_name(self) -> Optional[str]: ...
259
    @property
260
    def module_name(self) -> Optional[str]: ...
261
    @property
262
    def func_index(self) -> int: ...
263
    @property
264
    def module_offset(self) -> int: ...
265

266
class ExitTrap(Exception):
267
    def __init__(self, code: int): ...
268
    @property
269
    def code(self) -> int: ...
270
```
271

272
[Error Handling](./errors.md)
273

274
### Component Model
275

276
WebAssembly component model integration through bindgen tooling, enabling rich type communication between Python and WebAssembly components with automatic binding generation.
277

278
```python { .api }
279
import wasmtime.bindgen
280

281
def generate(name: str, component: bytes) -> Dict[str, bytes]: ...
282
```
283

284
[Component Model](./components.md)
285

286
### Utilities
287

288
Helper functions and utilities including WebAssembly text format conversion, table management, global variable handling, and development aids.
289

290
```python { .api }
291
def wat2wasm(wat: str) -> bytes: ...
292

293
class Table:
294
    def __init__(self, store: Store, ty: TableType, init): ...
295
    def type(self, store: Store) -> TableType: ...
296
    def size(self, store: Store) -> int: ...
297
    def grow(self, store: Store, delta: int, init) -> int: ...
298
    def get(self, store: Store, idx: int): ...
299
    def set(self, store: Store, idx: int, val) -> None: ...
300

301
class Global:
302
    def __init__(self, store: Store, ty: GlobalType, val: Val): ...
303
    def type(self, store: Store) -> GlobalType: ...
304
    def value(self, store: Store) -> Val: ...
305
    def set_value(self, store: Store, val: Val) -> None: ...
306
```
307

308
[Utilities](./utilities.md)