在浏览器中运行 Python：RustPython 的 WebAssembly 编译与交互式 Demo 构建指南

在浏览器中运行 PythonRustPython 的 WebAssembly 编译与交互式 Demo 构建指南【免费下载链接】RustPythonA Python Interpreter written in Rust项目地址: https://gitcode.com/GitHub_Trending/ru/RustPythonRustPython 是用 Rust 编写、可编译为 WebAssemblyWASM的 Python 3 解释器本指南以其 wasm/README.md 为核心完整讲解从环境搭建、wasm-packnpm构建到启动交互式浏览器 Demo、调用rp.pyEval等 JavaScript API 的完整流程。读完本文你将掌握如何在本仓库中编译 WASM 版本、在浏览器里运行 Python 代码以及如何把rustpython_wasm作为库集成进自己的 JS 应用。一、项目现状初步但可运行的 WASM 支持按照 wasm/README.md 的说明RustPython 对 WebAssembly 的支持目前仍处于初步preliminary阶段官方将本指南定位为面向开发者或希望运行玩具级示例toy example的人群。crates/wasm/README.md 更是明确标注项目处于 pre-alpha 状态不推荐在生产环境使用使用前需充分了解风险。这一点决定了本文所有构建与集成操作都适合本地开发与体验而非生产部署。从仓库目录结构看WASM 相关代码被组织为两部分核心库 crate位于 crates/wasmcrate 名为rustpython_wasm见 crates/wasm/Cargo.toml负责 Python ↔ Rust ↔ JS 之间的互操作绑定前端应用位于 wasm 目录包含三类消费方wasm/demo官方交互式 Demo 网站的前端源码wasm/example展示如何在自己的 JS 应用中把rustpython_wasm当作库使用的示例wasm/notebook浏览器内 Python 笔记本类应用含独立说明 wasm/notebook/README.md。提示原文档提到库位于wasm/lib当前仓库中实际路径已调整为crates/wasm构建配置如 wasm/demo/webpack.config.js也相应地通过../../crates/wasm/pkg引用编译产物。二、环境准备安装 wasm-pack 与 npm开始构建前需要准备两个工具wasm-packRust 生态中面向 WASM 的构建与打包工具负责把rustpython_wasmcrate 编译成 npm 可用的pkg产物npmNode.js 包管理器用于驱动 webpack 前端构建。其中 wasm-bindgen 通常会由 wasm-pack 自动携带安装无需单独处理若未安装则需自行补齐。可依次执行wasm-pack --version与npm --version验证两个工具已就绪。三、构建与运行官方 Demonpm run devDemo 是观察 WASM 库改动效果的最佳入口因为在网页上rustpython_wasm模块被挂载为全局 JS 变量rp这一挂载逻辑见 wasm/demo/src/index.js 的window.rp rustpython你可以在浏览器控制台里直接操作它。3.1 进入 wasm 目录并启动开发服务器cd wasm cd demo npm run devnpm run dev实际执行的是webpack serve见 wasm/demo/package.json 的 scripts 定义它会依次完成两件事编译 Rust crate借助wasm-tool/wasm-pack-pluginwasm/demo/webpack.config.js 中crateDirectory指向../../crates/wasm将rustpython_wasm编译为 WASM 包打包前端应用webpack 再对 Demo 页面进行打包。由于解释器本体体积庞大整个编译过程耗时较长——README 特别提醒wasm-pack 阶段和 webpack 阶段都会很慢看到 Your crate has been correctly compiled 字样后仍需耐心等待 webpack 继续处理。编译完成后打开http://localhost:8080即可使用 Demo在 CodeMirror 编辑器中编写 Python 代码或在页面内置的 xterm 终端里交互式输入。Demo 页面还内置了多个示例片段wasm/demo/snippets包括fibonacci.py、fizzbuzz.py、mandelbrot.py、fetch.py、import_pypi.py、asyncbrowser.py默认加载斐波那契示例见 webpack 配置中的defaultSnippetName: fibonacci。3.2 在控制台直接执行 Python打开浏览器 DevTools 控制台即可通过全局rp对象执行 Python。原文档给出了官方示例rp.pyEval( print(js_vars[a] * 9) , { vars: { a: 9, }, }, );这段代码演示了两个核心点rp.pyEval(code, options)执行 Python 表达式并返回结果options.vars中的对象会注入 Python 作用域通过变量名js_vars访问因此js_vars[a]取到 JS 传入的9输出81。3.3 其他构建模式除了开发服务器README 还提供了两种一次性构建方式命令说明npm run build执行webpack构建一次应用不监听文件变化不 watchnpm run dist执行webpack --mode production以 release 模式构建 crate 与 webpack 产物适合产出可分发文件四、rp 核心 API 深度解析pyEval / pyExec / pyExecSingleDemo 中暴露的rp对象实际由rustpython_wasmcrate 的 wasm-bindgen 导出构成其公开 API 统一收口在 crates/wasm/src/lib.rs 的exports模块中。核心入口是三个执行函数底层共享同一个run_py实现仅通过rustpython_vm::compiler::Mode区分执行模式JS API对应 Rust 函数Mode行为pyEval(code, options?)eval_pyMode::Eval以表达式求值模式执行返回 Python 表达式的结果JS 值pyExec(code, options?)exec_pyMode::Exec以语句执行模式运行不返回结果Result(), JsValuepyExecSingle(code, options?)exec_single_pyMode::Single以交互式单条语句模式执行可返回语句结果供 REPL/终端逐行运行使用三种模式的行为差异在 wasm/tests/test_exec_mode.py 中有自动化测试印证pyEval(11)返回2pyExec(11)返回null而pyExecSingle(11)返回2pyExecSingle(11\n22)的 stdout 输出为2\n4\n说明 Single 模式会逐条执行并打印每条语句的结果。4.1 options 配置项详解options对象支持三个字段均来自 crates/wasm/src/lib.rs 的文档注释由run_py通过Reflect::get读取vars?{ [key: string]: any }传递给 VM 的 JS 变量Python 侧通过js_vars访问。值为函数时同样可用函数会以 Python 传入的 kwargs 作为this参数被调用。若传入非对象值如undefined之外的原始值run_py会抛出TypeError: vars must be an object见 crates/wasm/src/lib.rs。stdout?console | ((out: string) void) | null替换 Python 的print输出。传undefined或console时走console.log传null时静默丢弃dumb function。stderr?console | ((out: string) void) | null替换sys.stderr。传undefined或console时走console.error。测试文件 wasm/tests/test_exec_mode.py 给出了stderr回调的实测执行import sys; print(err, filesys.stderr)并传入收集回调后输出为err\n。4.2 顶层导出VMStore 与 WASMVirtualMachine除三个执行函数外exports还导出了VMStore与WASMVirtualMachine定义于 crates/wasm/src/vm_class.rs用于管理多个独立的解释器虚拟机实例。Demo 前端正是用它们实现终端 REPL 的rp.vmStore.init(term_vm)创建专用 VM再通过setStdout/setStderr把 Python 输出转发到 xterm 终端wasm/demo/src/index.js。五、把 rustpython_wasm 集成进自己的 JS 应用如果你不想用官方 Demo而是想在自己的项目里嵌入 Python 解释器可以参考 wasm/example 这个最小示例。其依赖声明为 npm 包rustpython_wasmwasm/example/package.json入口代码极其精简import * as rp from rustpython_wasm; import pyCode from raw-loader!./main.py; const vm rp.vmStore.get(main); vm.exec(pyCode);完整代码见 wasm/example/src/main.js从源码结构看vmStore.get(main)获取必要时创建名为main的虚拟机实例vm.exec(pyCode)以 exec 模式执行 Python 源码字符串。示例通过 webpack 的raw-loader把 wasm/example/src/main.py 作为字符串引入再由解释器执行。这与rp.pyExec的底层机制一致只是改用了实例化 VM 的面向对象方式便于在多个 VM 之间隔离状态。构建示例同样使用 webpacknpm run build或npm run dist生产模式。与 Demo 不同example 不依赖 wasm-pack 插件直接使用发布到 npm 的预编译包构建速度会快很多。六、WASM 构建背后的工程细节6.1 关键 feature 与编译约束crates/wasm/Cargo.toml 揭示了 WASM 构建的几个关键设计crate 类型为cdylibrlib可被 JS 动态加载也可被 Rust 复用默认启用freeze-stdlibfeature把标准库直接冻结进 WASM 产物避免运行时动态加载 Python 模块依赖rustpython-vm时显式启用wasmbindfeature且注释强调make sure no threading! otherwise wasm build will fail——WASM 目标不支持线程VM 必须关闭相关线程特性通过web-sys访问浏览器 APIconsole、Document、Window、Headers、Request、Response等这是 Python 侧实现fetch、browser等浏览器模块的基础见 crates/wasm/src/browser_module.rs 与 crates/wasm/Lib/browser.pyrelease 配置中关闭了wasm-opt优化wasm-opt false这是构建速度与体积之间的取舍。6.2 浏览器侧 WebAssembly 加载方式wasm/demo/webpack.config.js 中启用了 webpack 5 的experiments.asyncWebAssembly.wasm文件以webassembly/async类型异步加载。因此 Demo 前端采用动态import(rustpython)wasm/demo/src/index.js并在加载失败时把window.__RUSTPYTHON_ERROR、__RUSTPYTHON_ERROR_STACK等调试信息展示到页面上——这些全局错误信息正是由 crates/wasm/src/lib.rs 的panic_hook在 Rust panic 时写入window的。6.3 自动化测试验证wasm/tests 目录提供了基于 Selenium WebDriver 的端到端测试wasm/tests/conftest.py 提供wdriverfixture验证 Demo 页面加载完成后页面会注入#rp_loaded标记元素三个执行模式与 stdout/stderr 回调行为正如 4.1 节所述。运行方式是先npm run dist构建产物再执行 pytest。七、如何更新线上 Demo如果你希望把本地改动同步到 WebAssembly 在线 Demo 页面README 给出的流程是向仓库提交 Pull Request将main分支合并到release分支该合并会触发 CITravis构建构建完成后自动更新线上 Demo 页面。需要说明的是这一流程针对的是托管在 GitHub 的官方站点维护流程对本仓库的本地开发并无影响日常改动只需执行第 3 节的npm run dev即可在本地预览全部效果。八、总结与注意事项回顾本指南你可以掌握 RustPython WASM 版本的完整工作流环境wasm-pack npm构建cd wasm/demo npm run dev开发/npm run build单次/npm run distrelease调用全局rp对象上的pyEval/pyExec/pyExecSingle配合vars/stdout/stderr选项与 JS 双向互操作集成通过 npm 包rustpython_wasm或直接引用 crates/wasm 编译产物配合VMStore管理多实例测试参考 wasm/tests/test_exec_mode.py 编写浏览器端自动化验证。最后再次强调当前 WASM 支持仍是 pre-alpha 阶段且构建链路长、产物体积大编译时需要耐心本文所有操作均以当前仓库代码为准适用于本地开发与功能验证场景。【免费下载链接】RustPythonA Python Interpreter written in Rust项目地址: https://gitcode.com/GitHub_Trending/ru/RustPython创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考