# Waspy
A Python to WebAssembly compiler written in Rust.
[
](https://crates.io/crates/waspy) [](https://crates.io/crates/waspy) [](https://crates.io/crates/waspy) [](https://github.com/anistark/waspy) [](https://github.com/anistark/waspy/graphs/contributors) 
## Overview
Waspy translates Python functions into WebAssembly. The implementation supports basic arithmetic operations, control flow, and multiple functions with enhanced type support.
### Compilation Pipeline
## Overview
```sh
[Python Source Code]
↓
Parse & Analyze
↓
[Intermediate Representation]
↓
Generate & Optimize
↓
[WebAssembly Binary]
```
## Current Features
- Compiles Python functions to WebAssembly
- Supports multiple functions in a single WebAssembly module
- Compiles multiple files into a single module
- Handles control flow with if/else and while loops
- Processes variable declarations and assignments
- Supports type annotations for function parameters and return values
- Enables function calls between compiled functions
- Includes an expanded type system: integers, floats, booleans, strings
- Complete string operations support (slicing, concatenation, 20+ methods, formatting)
- Supports arithmetic operations (`+`, `-`, `*`, `/`, `%`, `//`, `**`)
- Processes comparison operators (`==`, `!=`, `<`, `<=`, `>`, `>=`)
- Handles boolean operators (`and`, `or`)
- Provides improved error handling with detailed error messages
- Performs automatic WebAssembly optimization using Binaryen
- Detects and handles project structure and dependencies
- Supports module-level variables and basic class definitions
## Limitations
- Limited standard library support
- Only basic memory management
- No complex data structures yet (limited support for lists, dicts)
- No closures or higher-order functions
- No exception handling
## Installation
```sh
cargo add waspy
```
# Or add to your Cargo.toml
[dependencies]
waspy = "0.5.0"
## Quick Start
### Using the Library
```rust
use waspy::compile_python_to_wasm;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let python_code = r#"
def add(a: int, b: int) -> int:
return a + b
def fibonacci(n: int) -> int:
if n <= 1:
return n
a = 0
b = 1
i = 2
while i <= n:
temp = a + b
a = b
b = temp
i = i + 1
return b
"#;
let wasm = compile_python_to_wasm(python_code)?;
// Write to file or use the WebAssembly binary
std::fs::write("output.wasm", &wasm)?;
Ok(())
}
```
With Compiler Options:
```rust
use waspy::{compile_python_to_wasm_with_options, CompilerOptions, Verbosity};
let options = CompilerOptions {
optimize: true,
debug_info: true,
generate_html: true,
verbosity: Verbosity::Verbose, // or Verbosity::Debug
..CompilerOptions::default()
};
let wasm = compile_python_to_wasm_with_options(python_code, &options)?;
```
### Verbosity Levels
Waspy supports different verbosity levels for logging output:
- **`Verbosity::Quiet`** - Minimal output (errors only)
- **`Verbosity::Normal`** - Standard output (default)
- **`Verbosity::Verbose`** - Detailed output
- **`Verbosity::Debug`** - Detail for debugging
If your project has `--verbose` or `--debug` flags, use the `from_flags` helper:
```rust
use waspy::{CompilerOptions, Verbosity};
// Map CLI flags to verbosity level
let options = CompilerOptions {
verbosity: Verbosity::from_flags(verbose_flag, debug_flag),
..CompilerOptions::default()
};
```
For multiple files compilation:
```rust
use waspy::compile_multiple_python_files;
let sources = vec![
("math.py", "def add(a: int, b: int) -> int:\n return a + b"),
("main.py", "def compute(x: int) -> int:\n return add(x, 10)")
];
let wasm = compile_multiple_python_files(&sources, true)?;
```
For unoptimized WebAssembly (useful for debugging or further processing):
```rust
use waspy::compile_python_to_wasm_with_options;
let wasm = compile_python_to_wasm_with_options(python_code, false)?;
```
Compiling Projects:
```rust
use waspy::compile_python_project;
let wasm = compile_python_project("./my_python_project", true)?;
```
### Example Python Code
```python
def factorial(n: int) -> int:
result = 1
i = 1
while i <= n:
result = result * i
i = i + 1
return result
def max_num(a: float, b: float) -> float:
if a > b:
return a
else:
return b
```
### Using the Generated WebAssembly
The compiled WebAssembly can be used in various environments:
```js
// Browser or Node.js
WebAssembly.instantiate(wasmBuffer).then(result => {
const instance = result.instance;
console.log(instance.exports.factorial(5)); // 120
console.log(instance.exports.max_num(42, 17)); // 42
});
```
## Implementation Details
### Multiple Functions
Waspy supports multiple function definitions:
- Each function is compiled to a separate WebAssembly function
- All functions are exported with their original names
- Functions can call other functions within the same module
- Functions from multiple files can be compiled into a single module
### Type System
The type system now includes:
- **Type Annotations**: Support for Python's type hints on function params and return values
- **Integers**: Mapped to WebAssembly's `i32` type
- **Floats**: Supported as `f64` with conversion to `i32` when necessary
- **Booleans**: Represented as `i32` (`0` for `false`, `1` for `true`)
- **Strings**: Support for string operations with compile-time optimization
- **Type Coercion**: Automatic conversion between compatible types when needed
### Control Flow
The compiler supports basic control flow constructs:
- **If/Else Statements**: Conditional execution using WebAssembly's block and branch instructions
- **While Loops**: Implemented using WebAssembly's loop and branch instructions
- **Comparison Operators**: All standard Python comparison operators
- **Boolean Operators**: Support for `and` and `or` with short-circuit evaluation
### Variable Support
Waspy handles variables through WebAssembly locals:
- Local variables are allocated in the function's local variable space
- Assignment statements modify these locals
- Variables can be statically typed with annotations
- Type inference for variables based on usage
### Error Handling
Enhanced error reporting system:
- Detailed error messages with source location information
- Specific error types for different issues (parsing, type errors, etc.)
- Warnings for potential problems that don't prevent compilation
## Examples
Waspy includes several examples to demonstrate its functionality:
```sh
# Basic compiler example
cargo run --example simple_compiler
# Advanced compiler with options
cargo run --example advanced_compiler examples/typed_demo.py --metadata --html
# Multi-file compilation
cargo run --example multi_file_compiler examples/output/combined.wasm examples/basic_operations.py examples/calculator.py
# Project compilation
cargo run --example project_compiler examples/calculator_project examples/output/project.wasm
# Type system demonstration
cargo run --example typed_demo
```
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to get started.
## Roadmap
- Complete support for all Python data types (lists, dicts, sets, etc.)
- Classes and object-oriented programming features
- Exception handling
- More comprehensive standard library support
- Memory management improvements
- Modules and imports
- Optimization improvements specific to Python patterns
- Enhanced type inference
## License
[MIT](./LICENSE)