Pyodide 314.0 发布：Python 包现可发布 WebAssembly Wheel 至 PyPI

背景

Pyodide 作为在浏览器中运行 Python 的核心项目，长期以来面临着生态扩展的瓶颈。在过去，Pyodide 维护者需要手动维护、构建和托管超过 300 个 Python 包。这种集中式的维护模式不仅给核心团队带来了巨大负担，也成为社区发展的主要阻碍，因为每一个新包的引入都需要经过繁琐的人工审查。

随着 PEP 783（Emscripten packaging）的正式接受，Python 在浏览器中的生态系统迎来了历史性的转折点。Pyodide 维护者（特别是 @hoodmane）经过长期努力，终于实现了这一目标，使得 Python 包能够像为 Linux、macOS 或 Windows 构建原生 Wheel 一样，直接构建并发布针对 Pyodide 的 WebAssembly Wheel。

核心内容

PEP 783 的落地与标准化

PEP 783 的接受标志着 Python 在浏览器生态中标准化进程的重大里程碑。其核心变化在于：

1. 直接发布至 PyPI：开发者现在可以将为 Pyodide（或任何兼容 PEP 783 定义的 PyEmscripten 平台的 Python 运行时）构建的 Python 包直接发布到 PyPI，并在运行时安装。
2. 工具链支持：cibuildwheel v4.0 已经支持为 PyEmscripten 2025 和 2026 ABI 构建 Wheel。其中，2026 ABI 目前仅用于预发布构建，需通过 pyodide-prerelease 选项启用。官方计划在 v4.1.0 版本中更新 cibuildwheel 并使 314.0 稳定版可用。
3. 平台标签变更：平台标签现在使用 pyemscripten_* 前缀。例如，Python 3.13 (Pyodide 0.29.x) 对应 pyemscripten_2025_0，Python 3.14 (Pyodide 314.x) 对应 pyemscripten_2026_0。构建者需相应更新构建配置和 pyodide-build 版本。

版本号体系的重大调整

Pyodide 的版本号从之前的 0.29 跃升至 314.0，这一变化旨在与新的打包标准对齐：

• 基于 Python 版本的命名：Pyodide 现在采用基于 Python 主要版本的命名方案。例如，Pyodide 314.x 直接对应 Python 3.14。
• 稳定性承诺：二进制不兼容的变化将严格与上游 Python 更新同步（通常每年一次）。这意味着用户可以在多个 Pyodide 版本间安全地使用为同一 Python 版本构建的现有包。
• 发布节奏：官方计划每年发布一个新的 Pyodide 主版本，与 Python 更新保持同步。
• 当前版本细节：314.0 版本内置了 Python 3.14.2 和 Emscripten 5.0.3。

标准库的变更与取舍

为了优化用户体验，Pyodide 对标准库进行了重大调整：

• 恢复部分标准库：此前为了减小体积而“解绑”（unvendored）的 ssl、sqlite3 和 lzma 等库现在被恢复为标准库的一部分。虽然这增加了初始下载大小，但用户无需再手动安装这些包，体验更加无缝。
• 移除与废弃：pydecimal 和 test 包已从发行版中移除。loadPyodide() 中的 fullstdlib 选项已被弃用且无效。
• SSL 模块的重大变化：
  • Pyodide 决定不再将 OpenSSL 纳入标准库，以避免显著增加体积。
  • ssl 模块不再依赖 OpenSSL，而是实现了一个自定义的 SSL 实现，提供与标准库 ssl 模块兼容的基本功能，但不支持实际的 SSL/TLS 支持。
  • 值得注意的是，在此之前，由于浏览器不支持 socket 操作，ssl 模块的大部分功能实际上也无法使用。
  • hashlib 模块不再支持此前通过 OpenSSL 提供的部分加密哈希函数。
• 新增支持：得益于 Python 3.14，Pyodide 现在原生支持 compression.zstd 模块，提供 zstd 压缩和解压缩支持。

Pyodide 成为原生 ES 模块

• 文件重命名：pyodide.asm.js 已重命名为 pyodide.asm.mjs，以正确反映其作为 ES 模块的身份。
• 兼容性影响：
  • 大多数用户无需更改，因为 loadPyodide() 内部处理了这一变化。
  • 经典（非模块）Worker 不再支持，必须使用模块 Worker (type: "module")。
  • 静态导入 pyodide.asm.js 的服务 Worker 现在必须从 pyodide.asm.mjs 导入 createPyodideModule，并将其作为参数传递给 loadPyodide。
  • 打包工具配置中引用 pyodide.asm.js 的部分需更新为 pyodide.asm.mjs。

Node.js 中的实验性 Socket 支持

Pyodide 现在在 Node.js 环境中提供了实验性的 socket 操作支持：

• 功能：允许在 Pyodide 中使用 socket 模块，支持 TCP socket 的创建和通信（如连接远程数据库服务器）。涵盖带 TLS 的 TCP socket、WebLoop 的异步 socket 函数以及非阻塞模式。
• 测试驱动：已测试通过 pymysql (MySQL)、pg8000 (PostgreSQL) 和 redis-py 等数据库驱动。
• 启用方式：运行 await pyodide.useNodeSockFS()。
• 注意事项：在 Node.js <= v24 版本中，还需要传递 --experimental-wasm-stack-switching 标志以启用 JSPI。

JavaScript 互操作性改进

• JsBigInt 支持：引入了 pyodide.ffi.JsBigInt，这是一个 int 的子类型，解决了 JavaScript bigint 类型在 Python 中往返转换时的精度丢失问题。此前，大于 $2^{53}$ 的值在转换回 JavaScript 时会变成 number 类型从而丢失精度。现在，Python 和 JavaScript 侧的大整数都会生成 JsBigInt，确保精度无损。
• 资源管理：Pyodide 现在支持 JavaScript/ECMAScript 显式资源管理提案（using 声明）。
  • 在 JS 侧，PyProxy 和 PyBufferView 实现了 [Symbol.dispose]，可以使用 using 确保 Python 对象在作用域结束时自动清理。
  • 在 Python 侧，如果 JS 对象具有 [Symbol.dispose]() 方法，其 JsProxy 可以作为上下文管理器使用 with 语句。异步上下文管理器同样支持 [Symbol.asyncDispose]()。
• JsProxy 数组支持：增强了对类数组对象的支持（原文此处截断，但意指改进 Array.is 相关的判断逻辑）。

关键要点

• 生态开放：PEP 783 的接受使得 Python 包维护者可以直接向 PyPI 发布 Pyodide Wheel，极大地减轻了核心维护者的负担，加速了第三方包的可用性。
• 版本对齐：Pyodide 版本号现在直接对应 Python 主版本号（如 314.x 对应 Python 3.14），确保了二进制兼容性的长期稳定，减少了因 Pyodide 小版本更新导致的包破坏风险。
• 体积与功能的权衡：为了提供更无缝的体验，ssl、sqlite3 等库被重新纳入标准库，导致初始下载