PyGWalker Spec 文件

PyGWalker spec 用于保存图表状态。本地文件如果需要由 PyGWalker 加载或保存，请使用 spec_path；内联 JSON、配置 ID 或远程 spec 请使用 spec。

import pygwalker as pyg
 
walker = pyg.walk(
    df,
    spec_path="./gw_config.json",
    computation="browser",
)

`spec_path` vs `spec`

选项	用途	示例
`spec_path`	本地图表状态文件	`spec_path="./gw_config.json"`
`spec`	内联 JSON、配置 ID 或远程 spec URL	`spec='[{"name":"Chart 1", ...}]'`

新的本地文件示例请优先使用 spec_path。它能明确表达文件持久化，并避免与内联 JSON 或远程 spec 混淆。

保存和复用图表状态

当适配器暴露保存能力时，使用读写 spec 模式。

import pygwalker as pyg
 
walker = pyg.Walker(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    computation="kernel",
)
 
walker.show()

Streamlit 和 Gradio 也支持 spec_io_mode：

from pygwalker.api.streamlit import StreamlitRenderer
 
renderer = StreamlitRenderer(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    computation="kernel",
)
renderer.explorer()

渲染已保存图表

当你只需要已保存图表而不需要完整探索器时，请使用 render。

import pygwalker as pyg
 
pyg.render(df, spec_path="./gw_config.json", computation="browser")

静态 renderer 导出请使用 to_render_html。

from pygwalker.api.html import to_render_html
 
html = to_render_html(df, spec_path="./gw_config.json", computation="browser")

迁移旧 spec

pygwalker.spec.migrate 会将已保存的 PyGWalker 或 Graphic Walker spec 更新为当前 schema 形状。

import json
import pygwalker as pyg
 
migrated = pyg.spec.migrate("./old_gw_config.json")
 
with open("./gw_config.json", "w", encoding="utf-8") as f:
    json.dump(migrated, f, ensure_ascii=False, indent=2)

签名：

pygwalker.spec.migrate(spec, *, version=None) -> dict

spec 可以是：

输入	是否接受
已加载的 Python 对象	`dict` or `list`
JSON 字符串	Yes
已存在的本地文件路径	Yes

如果字符串看起来不是有效 JSON，或文件路径不存在，migrate 会抛出 ValueError。

常见陷阱

陷阱	修复方式
在新代码中通过 `spec` 传入本地文件	使用 `spec_path`。
期望静态 HTML 将编辑保存回 `spec_path`	使用支持保存的 live notebook/app 后端。
对已经接收 `Walker` 的适配器再传入 `spec_path`	将 spec path 放在原始 `Walker` 上。
用 `spec.migrate` 迁移远程 spec URL	先加载 spec 对象，再传入对象或 JSON 字符串。