Skip to content

PyGWalker Notebook API

在 notebook 中，请从 pygwalker.walk(df) 开始，或创建可复用的 pygwalker.Walker。当前默认的 Jupyter 渲染路径是 anywidget，因此新代码应省略 env，或使用 env="JupyterAnywidget"。

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

快速决策表

需求使用原因
只探索一次 DataFramepyg.walk(df)最小的 notebook 调用。
复用同一份配置pyg.Walker(df, ...).show()一个对象可以在 notebook、Streamlit、webserver 和 HTML 中渲染。
只渲染已保存图表pyg.render(df, spec_path=...)打开 renderer 视图，而不是完整探索器。
显示表格/数据概览视图pyg.table(df)从 data/table 模式启动。
将图表状态保存到本地文件spec_path="./gw_config.json"本地图表状态有专用参数。

pygwalker.walk

walk 会打开完整的 Graphic Walker 探索器。

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

签名：

pyg.walk(
    dataset,
    gid=None,
    *,
    env="JupyterAnywidget",
    field_specs=None,
    theme_key="g2",
    appearance="media",
    spec="",
    spec_path=None,
    computation=None,
    use_kernel_calc=None,
    kernel_computation=None,
    cloud_computation=False,
    show_cloud_tool=True,
    kanaries_api_key="",
    default_tab="vis",
    **kwargs,
)

dataset 可以是 pandas DataFrame、polars DataFrame、pyarrow Table、数据库 Connector、连接器式字符串，或可复用的 pygwalker.Walker。

Anywidget 是 notebook 默认路径

新 notebook 代码应使用 anywidget 路径：

pyg.walk(df)
pyg.walk(df, env="JupyterAnywidget")
pyg.Walker(df).show()
pyg.Walker(df).show(env="jupyter-anywidget")

旧 Jupyter transport 别名仍会解析到 anywidget，并发出弃用警告：

旧值当前行为状态
env="Jupyter"按 JupyterAnywidget 处理已弃用，计划在 PyGWalker 0.7.0 中移除。
env="JupyterWidget"按 JupyterAnywidget 处理已弃用，计划在 PyGWalker 0.7.0 中移除。
Walker.show("jupyter-inline")按 jupyter-anywidget 处理已弃用，计划在 PyGWalker 0.7.0 中移除。
Walker.show("jupyter-widget")按 jupyter-anywidget 处理已弃用，计划在 PyGWalker 0.7.0 中移除。

Walker.show(env="auto") 会检测当前环境。在 notebook 中它会解析为 jupyter-anywidget；在 notebook 之外则启动 webserver 适配器。

复用 pygwalker.Walker

当图表状态和计算模式应只定义一次时，请使用 Walker。

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

构造函数：

pyg.Walker(
    dataset,
    gid=None,
    *,
    field_specs=None,
    theme_key="g2",
    appearance="media",
    spec="",
    spec_path=None,
    spec_io_mode="rw",
    computation=None,
    use_kernel_calc=None,
    kernel_computation=None,
    cloud_computation=False,
    show_cloud_tool=True,
    kanaries_api_key="",
    default_tab="vis",
    **kwargs,
)

常用方法：

方法返回用途
walker.corePygWalker访问旧 API 使用的兼容对象。
walker.show(env="auto", ...)Walker以 notebook 或 webserver 模式显示。
walker.to_html()str导出静态 iframe HTML。仅支持浏览器计算。
walker.to_html_without_iframe()str导出不含 iframe wrapper 的静态 HTML。仅支持浏览器计算。
walker.to_streamlit(**kwargs)StreamlitRenderer在 Streamlit 中复用构造选项。

将 Walker 传给其他适配器时，不要再次传入构造选项。下面的调用会被拒绝：

walker = pyg.Walker(df, spec_path="./gw_config.json", computation="browser")
 
# Raises ValueError: spec_path belongs on the original Walker.
pyg.walk(walker, spec_path="./other.json")

Notebook 中的计算

新代码请使用 computation。

pyg.walk(df, computation="browser")
pyg.walk(df, computation="kernel")
pyg.walk(df, computation="cloud", kanaries_api_key="...")

kernel_computation、cloud_computation 和 use_kernel_calc 是旧参数，并计划在 PyGWalker 0.7.0 中移除。如果 computation 设置为 "browser"、"kernel" 或 "cloud"，不要同时设置已启用的旧参数。

Notebook convert/静态 HTML 输出不支持 live kernel 或 cloud 计算。输出必须是静态内容时，请使用 computation="browser"；否则请在 live 后端中运行 PyGWalker。

pygwalker.render

render 会显示已保存图表，而不打开完整的拖放探索器。

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

签名：

pyg.render(
    dataset,
    spec="",
    *,
    theme_key="g2",
    appearance="media",
    spec_path=None,
    computation=None,
    kernel_computation=None,
    kanaries_api_key="",
    **kwargs,
)

pygwalker.table

table 会打开 PyGWalker 的数据表/数据概览模式。

import pygwalker as pyg
 
pyg.table(df, spec_path="./gw_config.json")

签名：

pyg.table(
    dataset,
    *,
    theme_key="g2",
    appearance="media",
    spec_path=None,
    computation=None,
    kernel_computation=None,
    kanaries_api_key="",
    **kwargs,
)

相关指南