Skip to content

README.md

Latest commit

 

History

History
90 lines (64 loc) · 3.36 KB

README.md

File metadata and controls

90 lines (64 loc) · 3.36 KB

Edge Python

A compact bytecode compiler and stack VM for a sandboxed Python subset, written in Rust. See Design for the architecture.

Edge Python is distributed as a WebAssembly module, compiler.wasm, around 170 KB. It runs anywhere WebAssembly runs: browsers, Cloudflare Workers, Fastly Compute, Wasmtime, Wasmer, Spin. Sandboxed by construction.

Repository layout

Cargo workspace; commands work from any directory.

├── compiler
├── demo
├── docs
├── runtime
├── starter-module
├── target
├── wasm-abi
└── wasm-pdk

cargo wasm # release .wasm (the distributed artifact)
cargo build --release # host .rlib + cdylib for Rust embedders
cargo test --release  # full test suite

Native modules ship via three delivery paths (CDN .wasm, host capability, JS host module), see Writing modules.

Quick start

Browser

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <script type="module" src="https://runtime.edgepython.com/js/src/element.js"></script>
</head>
<body>
    <edge-python entry="./app/main.py" packages="./app/packages.json"></edge-python>
</body>
</html>

The runtime spawns a Web Worker that pre-fetches imports, dispatches native calls, and streams print() output back. Build the WASM yourself with cargo wasm (output around 390 KB unstripped; optionally wasm-opt -Oz to shrink).

Consume the release from a Rust host

Declare edge-python as a dependency and compiler_lib.wasm from the matching GitHub Release is fetched into OUT_DIR automatically, no manual download.

# Cargo.toml
[dependencies]
edge-python = { git = "https://github.com/dylan-sutton-chavez/edge-python", tag = "v0.1.0" }
// build.rs
fn main() {
    println!("cargo::rerun-if-changed=build.rs");
    let wasm = std::env::var("DEP_COMPILER_LIB_WASM")
        .expect("`DEP_COMPILER_LIB_WASM` unset, upstream must declare `links = \"compiler_lib\"`");
    std::fs::copy(&wasm, "runtime/compiler_lib.wasm").expect("copy failed");
}

Pin to a tag for reproducible builds; use branch = "main" for unreleased changes. Requires curl on PATH. Gated by the default-on prebuilt feature.

Server / edge runtimes (Wasmtime, Wasmer, Cloudflare Workers, Fastly Compute, Spin)

Edge Python is a cdylib, your host instantiates compiler_lib.wasm and calls its exports. The same .wasm you serve to browsers is the server-side artifact; the host owns I/O, fetching, and output (WASI / runtime APIs instead of fetch / postMessage). No built-in CLI, embed compiler_lib.wasm in around 50 LOC wasmtime shell for local dev.

What it is

Edge Python targets sandboxed edge computing: a dynamic, multi-paradigm Python subset with classes, async/await, structural pattern matching, and compile-time module resolution. There is no bundled stdlib, modules are external artifacts.

Full language reference, scope, and what intentionally isn't supported: What Edge Python is. Architecture details: compiler/README.md.

License

MIT OR Apache-2.0

Sponsors