文档 / 概览

项目概览

以 JavaScript 实现 Python 3.15 语言运行时与标准库，核心目标是可验证的行为兼容。

这个项目是什么

node-for-python 是一个在 JavaScript 环境中运行 Python 语义的实现。它把 Python 源码读入 tokenizer、parser 和 interpreter，再把标准库模块接到同一个运行时上。项目面向需要在浏览器、Node.js 或 Worker 中执行 Python 代码的场景，强调源码可读、测试可重复以及每个兼容性结论都有可观察的证据。运行时使用原生 ESM，模块之间通过明确的导入关系协作，不要求调用系统 Python 才能执行已经打包的代码。

项目的目标版本是 CPython 3.15。这里的“兼容”按层次理解：词法层关注 token，语法层关注 AST 和错误，解释器关注输出与异常，标准库关注公开 API 的结果和边界行为。因此，某个模块已经出现在清单中，不等于它的所有边界都已经覆盖；详细状态请查看模块清单。

能做什么

在 Node.js 中加载 tokenizer、parser 和解释器，执行受支持的 Python 代码。
在浏览器游乐场中通过 Web Worker 执行程序，把输出和 GUI 画布与主页面隔离。
按模块导入 JavaScript 版标准库，并使用 Python 风格的名称、返回值和异常类型。
用固定向量比较 CPython 与本项目在语法、解释器和标准库层的可观察结果。
通过模块清单搜索实现状态、摘要和测试覆盖入口，判断某个 API 是否适合当前用途。

不能做什么

边界	含义
不是完整 CPython	目标是逐步覆盖 Python 3.15 的语言与标准库行为，未覆盖 API 不能假定存在。
不是任意 Python 扩展宿主	依赖 CPython C 扩展、操作系统动态库或原生 ABI 的代码不属于纯 JavaScript 运行时能力。
不是安全沙箱保证	Worker 能隔离页面线程，但应用仍需自行限制网络、文件和消息权限。
不是性能等价替代	解释器和跨层对象转换有成本；需要大量数值计算时应评估专用运行时。
不是自动完成全部兼容性	模块状态和测试结果会随仓库数据变化，使用前应查看当前快照与对应测试。

四层架构概览

Tokenizer 将字符变成带位置的 token；Parser 将 token 变成 AST；Interpreter 在作用域和异常规则下执行 AST；libstd 为导入器提供 Python 标准库模块。每层都可以单独测试，也可以通过下一层组合成完整程序路径。数据流从源码向下传递，错误在产生它的层被归类，调用方因此能区分语法错误、运行时异常和模块缺失。

模块进度的统计口径

模块页的总数来自仓库内置的模块表，构建器逐项读取模块目录、说明和测试文件，并根据状态函数归类为已实现、正在实现或未实现。统计不读取手写进度说明中的旧数字，也不会把目录数量直接当作完成数量。测试文件数量则按仓库实际存在的 *.test.mjs 文件统计；它表示测试入口的数量，不等于断言数量。快照时间标记数据生成时刻，HTTP 桥接开启后页面可以重新获取实时状态。

下载与上手

源码包可从下载入口获取，入口会选择可用节点并提供校验信息。下载后使用 Node.js 22 或更新版本，在仓库根目录运行测试命令；如果只想体验语义，可以直接打开在线游乐场。推荐先读快速开始，再读架构了解导入和执行边界。遇到结果差异时，按照差分测试的层次定位，不要只根据最终输出猜测问题来源。

继续阅读

快速开始说明本地命令和下载方式；架构说明运行时分层、标准库接线与浏览器宿主；差分测试说明如何建立固定对照和判断失败。文档目录可以直接跳转到各篇页面及其章节。