Referência da API do PyGWalker

Use pygwalker.walk(df) para abrir rapidamente um explorador interativo. Use pygwalker.Walker(...) quando o mesmo conjunto de dados, estado de gráficos e modo de computação precisarem ser reutilizados em notebooks, Streamlit, webserver ou exportação HTML.

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

Escolha um ponto de entrada

API	Melhor para	Observações
`pygwalker.walk(dataset, ...)`	Exploração rápida em notebooks ou scripts	Usa anywidget no Jupyter por padrão e um webserver local fora de notebooks.
`pygwalker.Walker(dataset, ...)`	Reutilizar um objeto PyGWalker entre adaptadores	Coloque opções de construção como `spec_path`, `field_specs` e `computation` no `Walker`.
`pygwalker.render(dataset, spec=..., ...)`	Renderizar gráficos salvos sem o explorador completo	Use `spec_path` para arquivos locais de gráficos.
`pygwalker.table(dataset, ...)`	Abrir a visualização de tabela/perfil	Aceita as mesmas opções de dados e computação que `render`.
`pygwalker.to_html(dataset_or_walker, ...)`	Exportação HTML estática	Apenas navegador. Rejeita `computation="kernel"` e `computation="cloud"`.
`StreamlitRenderer(dataset_or_walker, ...)`	Apps Streamlit	Armazene o renderer em cache com `st.cache_resource` para apps duradouros.
`get_html_on_gradio(dataset, ...)`	Apps Gradio	Retorne o HTML do iframe e monte `PYGWALKER_ROUTE`.
`pygwalker.component(dataset, ...)`	Construtores programáticos de gráficos	Encadeie métodos de marca, codificação, layout e exportação.
`pygwalker.spec.migrate(spec)`	Atualizar estado de gráficos salvo	Aceita um objeto spec carregado, string JSON ou caminho de arquivo local.

Dados suportados

A maioria das APIs públicas aceita pandas DataFrame, polars DataFrame, pyarrow Table, Connector de banco de dados e strings SQL/fonte de dados no estilo de conector quando o adaptador oferece suporte a conectores. pygwalker.walk, adaptadores de notebook anywidget/marimo/webserver, StreamlitRenderer e to_html também podem aceitar um objeto reutilizável pygwalker.Walker.

Veja Entradas de Dados para detalhes e exemplos.

Opções comuns

Opção	Tipo	Padrão	Uso
`spec_path`	`str` ou `None`	`None`	Arquivo local de estado de gráfico para carregar e salvar. Prefira isto em vez de passar um caminho local por `spec`.
`spec`	`str`	`""`	JSON inline, ID de configuração ou URL remota de spec.
`computation`	`auto`, `browser`, `kernel`, `cloud` ou `None`	`None`	Escolhe onde o PyGWalker executa consultas de dados. Omita ou use `"auto"` para comportamento automático.
`field_specs`	`List[FieldSpec]` ou `None`	`None`	Sobrescreve tipos semânticos e analíticos inferidos dos campos.
`theme_key`	`vega`, `g2` ou `streamlit`	`"g2"`	Seleciona a família de tema do renderer.
`appearance`	`media`, `light` ou `dark`	`"media"`	`media` acompanha o esquema de cores do sistema operacional.
`default_tab`	`data` ou `vis`	`"vis"`	Escolhe a aba inicial para visualizações de explorador.

Modos de computação

Use computation, não os booleanos de computação legados.

Valor	Comportamento	Uso típico
omitido ou `"auto"`	Mantém a seleção automática de modo do PyGWalker	Padrão para a maioria dos usuários.
`"browser"`	Executa consultas de dados no frontend/navegador	Exportações HTML estáticas e dados locais menores.
`"kernel"`	Executa consultas pela computação Python local baseada em DuckDB	Conjuntos de dados locais maiores em sessões ativas de notebook, Streamlit, Gradio ou webserver.
`"cloud"`	Executa consultas pela computação em nuvem da Kanaries	Fluxos em nuvem com uma chave de API Kanaries.

kernel_computation, cloud_computation e use_kernel_calc são flags legadas de compatibilidade. Elas estão depreciadas e têm remoção programada para o PyGWalker 0.7.0. Não combine flags legadas habilitadas com um valor computation não automático; o PyGWalker gera ValueError.

Veja Modos de Computação para exemplos de migração.

Reutilize um `Walker`

Crie um Walker quando vários adaptadores devem compartilhar uma configuração.

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

Quando um adaptador recebe um Walker, as opções de construção já precisam estar no Walker. Por exemplo, pyg.to_html(walker, spec_path="./other.json") é rejeitado porque tentaria reconstruir o objeto existente com estado conflitante.

Limites do HTML estático

Exportações HTML estáticas não têm backend Python ou de nuvem ativo. Use computation="browser" ou omita a opção de computação ao chamar pyg.to_html(...), walker.to_html() ou exportações HTML de componentes. Use um adaptador ativo como APIs de Notebook, Streamlit ou Gradio para computação em kernel ou nuvem.