ToolJet RunPy 进阶：使用 Pyodide to_py() 将 JavaScript 对象转换为 Python 数据结构

ToolJet RunPy 进阶：使用 Pyodide to_py() 将 JavaScript 对象转换为 Python 数据结构

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet

在 ToolJet 的Run Python Code（RunPy）查询中，to_py()是 Pyodide 库提供的用于将 JavaScript 对象转换为对应 Python 结构的关键函数。本文将以 ToolJet v2.50.0-LTS 文档体系为基础，完整讲解to_py()的工作原理、在 RunPy 查询编辑器中的实战用法，并结合前端源码与数据源文档，深入剖析为什么 JSON 与 Raw 预览标签页会出现显示差异，以及如何借助to_js()/to_py()这对互操作函数让 JavaScript 与 Python 数据在统一环境中无缝流转。读完本文，你将掌握在 ToolJet RunPy 查询中安全、一致地交换 JavaScript 与 Python 数据的完整方案。

to_py() 函数是什么

to_py()函数来自Pyodide库（ToolJet RunPy 的底层运行时），它是to_js()函数的对应物。其职责是将 JavaScript 对象转换为等价的 Python 结构——当你在 Pyodide 环境中拿到一个 JavaScript 对象，并希望用 Python 代码操作它时，这种转换是必不可少的。

与to_js()一样，to_py()承担着 JavaScript 与 Python 之间数据类型映射与转换的任务：它能将 JavaScript 对象（Object）、数组（Array）以及其他数据结构，高效地转换为 Python 侧的字典（dict）、列表（list）等对应类型。

关于 RunPy 的完整能力（触发组件动作、运行查询、获取查询数据、操作变量、数据转换等），可参阅仓库中的 Run Python Code 数据源文档 获取更深入的理解。

在 RunPy 中使用 to_py()：逐步实操

要验证to_py()的实际效果，请按以下步骤在 ToolJet 中操作：

1. 从 ToolJet 仪表盘点击Create an app按钮，创建一个新应用；
2. 应用创建完成后，导航到Query Panel（查询面板），点击+ Add按钮，在数据源列表中选择Run Python Code；
3. 在runpy查询的代码编辑器中输入以下代码：

import pyodide # Import the Pyodide library def to_py(js_object): # Define a function to convert JavaScript objects to Python dictionaries return dict(js_object) # Convert the JavaScript object to a Python dictionary my_js_object = {"name": "John", "age": 25, "country": "USA"} # Create a JavaScript object my_py_dict = to_py(my_js_object) # Convert the JavaScript object to a Python dictionary my_py_dict # Return the Python dictionary

在该示例中，my_js_object以字典字面量形式创建（文档中对应描述为Object.fromEntries()生成的类字典结构），随后调用to_py()将其转换为 Python 字典my_py_dict。

运行后输出为：

{'name': 'John', 'age': 25, 'country': 'USA'}

借助to_py()，JavaScript 对象可以无缝过渡为 Python 表示形式，从而可以在 Pyodide 环境中用纯 Python 代码对数据进行后续操作。而to_js()与to_py()这对函数，共同为 Python 与 JavaScript 之间的数据交换提供了便捷通道，让你能够在一个统一环境中同时发挥两种语言的优势。

RunPy 查询编辑器背后的实现

从源码层面看，RunPy 查询编辑器由 Runpy.jsx 实现。该组件使用 ToolJet 的 CodeHinter 多行代码编辑器，并将语言设置为lang="python"、高度设为 400px，用户在编辑器中输入的代码会通过changeOption(this, 'code', value)实时写回查询选项中的code字段：

<CodeHinter type="multiline" initialValue={this.props.options.code} lang="python" height={400} onChange={(value) => changeOption(this, 'code', value)} componentName="Runpy" />

这说明 RunPy 查询的核心输入就是一个 Python 代码字符串，而查询执行时由 Pyodide 在浏览器内解释运行——这也是to_py()/to_js()这类浏览器内互操作函数能够直接可用的前提。RunPy 查询在查询管理器中同样遵循 ToolJet 的统一查询生命周期，你可以在 QueryManager.jsx 中看到其与其他查询类型一致的调度方式。

为什么必须使用 to_py()：JSON 与 Raw 预览的差异

在 RunPy 查询中预览结果时，JSON与Raw两个标签页之间可能出现显示差异，根源在于Pyodide的转换与展示机制：

• 默认情况下，Python 字典在 Pyodide 中会被转换为JavaScript 的 Map 对象，以保证两种语言之间的兼容性。
• 因此，JSON标签页以 JavaScript 对象的形式展示数据（原文档中描述为()符号形态，即 Map 的呈现），而Raw标签页则展示原始表示，即[{}, {}, ...]形态——这是 Python 字典的原始形式（{}符号）。

需要强调的是：两种表示都是正确的。JSON 标签页展示的是已转换、与 JavaScript 兼容的数据；Raw 标签页展示的是原始的 Python 字典。选择哪一种，取决于你的使用场景——你需要在JavaScript 上下文还是Python 上下文中处理这批数据。

为了保持 JSON 与 Raw 表示的一致性，可以显式调用 Pyodide 提供的to_js()函数，将 Python 字典转换为 JavaScript 对象。这样既能保证两个标签页的展示对齐，也能确保数据处于你期望的格式。

结合 Python 侧转换保持一致的完整模式

综合上述原理，一个实用的模式是：在 RunPy 查询中显式控制数据的最终形态。例如，当你的 Python 代码最终返回字典结构时，可以直接交给 Pyodide 默认机制转换为 JS Map（对应 JSON 标签页展示），也可以通过to_js()显式转换为 JavaScript 对象；反之，当需要把查询结果中来自 JavaScript 侧的数据（如tj_globals、查询返回的数据）交给 Python 逻辑处理时，则用to_py()转换。

RunPy 查询可以访问 ToolJet 上下文数据，例如tj_globals.currentUser.firstName这样的全局对象，也可以触发组件动作（components.text1.setText(...)）与运行其他查询（actions.runQuery('getSalesData')、queries.getSalesData.run()），还可以用actions.setVariable/actions.getVariable读写变量——这些交互中传递的数据往往以 JavaScript 对象形式存在，正是to_py()发挥作用的最佳场景。详细用法可参考 Run Python Code 数据源文档 中的组件动作、查询触发与数据读取示例。

注意事项与边界

• RunPy 目前仅支持Python 标准库（可查阅 runpy 限制文档 了解urlopen无法访问外部 URL 等限制，以及使用 JavaScriptfetch与 Pyodide 互操作能力的替代方案）。
• to_py()的转换语义遵循 Pyodide 的 JS→Python 类型映射：JavaScript 对象映射为 Python 字典、数组映射为列表、字符串/数字/布尔等基础类型直接对应。
• 在 JSON 与 Raw 标签页看到的差异并非数据错误，而是 Pyodide 默认转换机制的正常表现；是否显式调用to_js()/to_py()，取决于你希望数据以 JavaScript 上下文还是 Python 上下文呈现。

小结

to_py()是 ToolJet RunPy 查询中打通 JavaScript 与 Python 数据边界的核心工具：一方面它将 JavaScript 对象安全转换为 Python 字典以便 Python 代码操作，另一方面它与to_js()配合，解决了查询预览中 JSON 与 Raw 标签页的展示差异问题。结合 Runpy.jsx 的源码实现与 run-py.md 的完整功能说明，你可以精准控制查询结果的呈现格式，让数据在 JavaScript 与 Python 两种语境下都处于正确形态。

【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 🚀项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet