API Streamlit do PyGWalker

Use StreamlitRenderer para incorporar o PyGWalker em um app Streamlit. Armazene o renderer em cache quando o dataset e o estado dos gráficos forem reutilizados entre reruns.

import pandas as pd
import streamlit as st
from pygwalker.api.streamlit import StreamlitRenderer
 
st.set_page_config(page_title="PyGWalker", layout="wide")
 
@st.cache_resource
def get_renderer():
    df = pd.read_csv("data.csv")
    return StreamlitRenderer(
        df,
        spec_path="./gw_config.json",
        spec_io_mode="rw",
        computation="kernel",
    )
 
renderer = get_renderer()
renderer.explorer()

Construtor

StreamlitRenderer(
    dataset,
    gid=None,
    *,
    field_specs=None,
    theme_key="g2",
    appearance="media",
    spec="",
    spec_path=None,
    spec_io_mode="r",
    computation=None,
    kernel_computation=None,
    use_kernel_calc=None,
    show_cloud_tool=None,
    kanaries_api_key="",
    default_tab="vis",
    **kwargs,
)

dataset pode ser um pandas DataFrame, polars DataFrame, pyarrow Table, Connector de banco de dados ou pygwalker.Walker reutilizável.

Opções principais

Opção	Padrão	Observações
`spec_path`	`None`	Arquivo local de estado de gráfico. Prefira isto para arquivos locais.
`spec_io_mode`	`"r"`	Use `"rw"` quando a UI do Streamlit deve salvar edições de gráficos de volta no arquivo spec.
`computation`	`None`	Use `"browser"`, `"kernel"` ou `"cloud"` para forçar um modo. O comportamento automático no Streamlit usa computação no lado do kernel por padrão.
`show_cloud_tool`	`None`	Controla a visibilidade da UI de nuvem quando disponível.
`default_tab`	`"vis"`	Aba inicial do explorador.

kernel_computation e use_kernel_calc são opções legadas de compatibilidade. Prefira computation; as flags legadas têm remoção programada para o PyGWalker 0.7.0.

Métodos principais

Método	Uso
`renderer.explorer(key="explorer", default_tab="vis")`	Explorador completo de arrastar e soltar.
`renderer.viewer(key="viewer")`	UI somente visualização/filter-renderer.
`renderer.chart(index, key="chart", size=None, pre_filters=None)`	Renderiza um gráfico salvo pelo índice baseado em zero.
`renderer.table(key="table")`	Renderiza a visualização de tabela.
`renderer.set_global_pre_filters(pre_filters)`	Aplica filtros em todos os gráficos, a menos que uma chamada de gráfico os sobrescreva.

Renderize um gráfico salvo

Depois de salvar gráficos em spec_path, renderize um gráfico por índice.

renderer.chart(0, size=(720, 420))

Use PreFilter para aplicar filtros no nível do gráfico.

from pygwalker.api.streamlit import PreFilter
 
renderer.chart(
    0,
    pre_filters=[
        PreFilter(field="category", op="one of", value=["A", "B"]),
        PreFilter(field="revenue", op="range", value=[0, 100000]),
    ],
)

PreFilter aceita:

PreFilter(
    field: str,
    op: "range" | "temporal range" | "one of",
    value: list[int | float | str],
)

Para op="temporal range", os valores podem ser timestamps em milissegundos ou strings de data parseáveis.

Reutilize um `Walker`

Se o mesmo dataset e as mesmas opções devem ser compartilhados com outros adaptadores, construa primeiro um Walker.

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

Ao passar um Walker, coloque as opções de construção em pyg.Walker(...). StreamlitRenderer(walker, spec_path="./other.json") é rejeitado porque entraria em conflito com o objeto existente.

`get_streamlit_html`

get_streamlit_html retorna a string HTML usada pelo componente Streamlit.

from pygwalker.api.streamlit import get_streamlit_html
 
html = get_streamlit_html(
    df,
    spec_path="./gw_config.json",
    spec_io_mode="rw",
    mode="explore",
    computation="kernel",
)

Os modos suportados são "explore", "filter_renderer" e "table".

Armadilhas comuns

Armadilha	Correção
Recriar `StreamlitRenderer` em todo rerun	Envolva a construção em `@st.cache_resource`.
Usar `spec="./gw_config.json"` para arquivos locais	Use `spec_path="./gw_config.json"`.
Passar opções de construção depois de fornecer um `Walker`	Mova essas opções para `pyg.Walker(...)`.
Começar código novo com `kernel_computation=True`	Use `computation="kernel"`.

Guias Relacionados

Modos de Computação Gradio