PyGWalker API 레퍼런스
빠르게 대화형 탐색기를 열려면 pygwalker.walk(df)를 사용하세요. 같은 데이터셋, 차트 상태, 계산 모드를 노트북, Streamlit, 웹서버, HTML 내보내기에서 재사용해야 한다면 pygwalker.Walker(...)를 사용하세요.
import pygwalker as pyg
walker = pyg.Walker(df, spec_path="./gw_config.json", computation="browser")
walker.show()엔트리포인트 선택
| API | 적합한 경우 | 참고 |
|---|---|---|
pygwalker.walk(dataset, ...) | 노트북이나 스크립트에서 빠르게 탐색 | Jupyter에서는 기본적으로 anywidget을 사용하고, 노트북 밖에서는 로컬 웹서버를 사용합니다. |
pygwalker.Walker(dataset, ...) | 하나의 PyGWalker 객체를 여러 어댑터에서 재사용 | spec_path, field_specs, computation 같은 생성 옵션을 Walker에 지정하세요. |
pygwalker.render(dataset, spec=..., ...) | 전체 탐색기 없이 저장된 차트 렌더링 | 로컬 차트 파일에는 spec_path를 사용하세요. |
pygwalker.table(dataset, ...) | 테이블/프로파일링 뷰 열기 | render와 같은 데이터셋 및 계산 옵션을 받습니다. |
pygwalker.to_html(dataset_or_walker, ...) | 정적 HTML 내보내기 | 브라우저 전용입니다. computation="kernel" 및 computation="cloud"를 거부합니다. |
StreamlitRenderer(dataset_or_walker, ...) | Streamlit 앱 | 장기 실행 앱에서는 st.cache_resource로 렌더러를 캐시하세요. |
get_html_on_gradio(dataset, ...) | Gradio 앱 | iframe HTML을 반환하고 PYGWALKER_ROUTE를 마운트하세요. |
pygwalker.component(dataset, ...) | 프로그래밍 방식의 차트 빌더 | mark, encode, layout, export 메서드를 체이닝합니다. |
pygwalker.spec.migrate(spec) | 저장된 차트 상태 업데이트 | 로드된 spec 객체, JSON 문자열, 로컬 파일 경로를 받습니다. |
지원 데이터셋
대부분의 공개 API는 pandas DataFrame, polars DataFrame, pyarrow Table, 데이터베이스 Connector, 그리고 어댑터가 커넥터를 지원하는 경우 connector 스타일 SQL/데이터 소스 문자열을 받습니다. pygwalker.walk, 노트북 anywidget/marimo/웹서버 어댑터, StreamlitRenderer, to_html은 재사용 가능한 pygwalker.Walker 객체도 받을 수 있습니다.
자세한 내용과 예시는 데이터셋 입력을 참고하세요.
공통 옵션
| 옵션 | 타입 | 기본값 | 용도 |
|---|---|---|---|
spec_path | str 또는 None | None | 로드하고 저장할 로컬 차트 상태 파일입니다. 로컬 파일 경로를 spec으로 넘기는 것보다 이 옵션을 권장합니다. |
spec | str | "" | 인라인 JSON, config ID, 원격 spec URL입니다. |
computation | auto, browser, kernel, cloud 또는 None | None | PyGWalker가 데이터 쿼리를 실행할 위치를 선택합니다. 자동 동작에는 생략하거나 "auto"를 사용하세요. |
field_specs | List[FieldSpec] 또는 None | None | 추론된 필드의 semantic type 및 analytic type을 재정의합니다. |
theme_key | vega, g2 또는 streamlit | "g2" | 렌더러 테마 계열을 선택합니다. |
appearance | media, light 또는 dark | "media" | media는 운영체제 색상 모드를 따릅니다. |
default_tab | data 또는 vis | "vis" | 탐색기 뷰의 초기 탭을 선택합니다. |
계산 모드
레거시 계산 불리언 대신 computation을 사용하세요.
| 값 | 동작 | 일반적인 용도 |
|---|---|---|
생략 또는 "auto" | PyGWalker의 자동 모드 선택 유지 | 대부분의 사용자에게 적합한 기본값입니다. |
"browser" | 프론트엔드/브라우저에서 데이터 쿼리 실행 | 정적 HTML 내보내기 및 작은 로컬 데이터입니다. |
"kernel" | 로컬 DuckDB 기반 Python 계산으로 쿼리 실행 | 라이브 노트북, Streamlit, Gradio, 웹서버 세션의 큰 로컬 데이터셋입니다. |
"cloud" | Kanaries 클라우드 계산으로 쿼리 실행 | Kanaries API 키가 있는 클라우드 기반 워크플로입니다. |
kernel_computation, cloud_computation, use_kernel_calc는 레거시 호환성 플래그입니다. 이 옵션들은 deprecated 상태이며 PyGWalker 0.7.0에서 제거될 예정입니다. 활성화된 레거시 플래그와 non-auto computation 값을 함께 사용하지 마세요. PyGWalker가 ValueError를 발생시킵니다.
마이그레이션 예시는 계산 모드를 참고하세요.
Walker 재사용
여러 어댑터가 하나의 설정을 공유해야 한다면 Walker를 만드세요.
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()어댑터가 Walker를 받으면 생성 옵션은 이미 Walker에 있어야 합니다. 예를 들어 pyg.to_html(walker, spec_path="./other.json")는 기존 객체를 충돌하는 상태로 다시 만들려고 하므로 거부됩니다.
정적 HTML 제한
정적 HTML 내보내기에는 라이브 Python 또는 클라우드 백엔드가 없습니다. pyg.to_html(...), walker.to_html(), 컴포넌트 HTML 내보내기를 호출할 때는 computation="browser"를 사용하거나 계산 옵션을 생략하세요. kernel 또는 cloud 계산이 필요하면 노트북 API, Streamlit, Gradio 같은 라이브 어댑터를 사용하세요.