ContextQMD
Back to Perspective

`PerspectiveWidget` for notebooks

docs/md/how_to/python/jupyterlab.md

5.2.02.8 KB
Original Source

PerspectiveWidget for notebooks

Building on top of the API provided by perspective.Table, the PerspectiveWidget offers the entire functionality of Perspective within a notebook environment. It supports the same API semantics of <perspective-viewer>, along with the additional data types supported by perspective.Table.

Installation

PerspectiveWidget is an AnyWidget, shipped as a prebuilt bundle inside the perspective-python wheel. There is no separate labextension to install or version-match — install the jupyter extra, which adds the anywidget dependency:

bash
pip install "perspective-python[jupyter]"

The same wheel works in JupyterLab, classic Jupyter Notebook, VSCode notebooks, Google Colab and Marimo.

<div class="warning">The <code>@perspective-dev/jupyterlab</code> package is now <em>optional</em> and no longer ships the widget. It provides only the "Open With &rarr; Perspective" file renderers for <code>csv</code>, <code>json</code> and <code>arrow</code> files in JupyterLab.</div>

Usage

PerspectiveWidget takes keyword arguments for the managed View:

python
from perspective.widget import PerspectiveWidget
w = perspective.PerspectiveWidget(
    data,
    plugin="X Bar",
    aggregates={"datetime": "any"},
    sort=[["date", "desc"]]
)

Creating a widget

A widget is created through the PerspectiveWidget constructor, which takes as its first, required parameter a perspective.Table, a dataset, a schema, or None, which serves as a special value that tells the Widget to defer loading any data until later. In maintaining consistency with the Javascript API, Widgets cannot be created with empty dictionaries or lists — None should be used if the intention is to await data for loading later on. A widget can be constructed from a dataset:

python
from perspective.widget import PerspectiveWidget
PerspectiveWidget(data, group_by=["date"])

.. or a schema:

python
PerspectiveWidget({"a": int, "b": str})

.. or an instance of a perspective.Table:

python
table = perspective.table(data)
PerspectiveWidget(table)

Updating a widget

PerspectiveWidget shares a similar API to the <perspective-viewer> Custom Element, and has similar save() and restore() methods that serialize/deserialize UI state for the widget.

PerspectiveRenderer

The optional @perspective-dev/jupyterlab package exposes a JS-only mimerender-extension. This lets you view csv, json, and arrow files directly from the JupyterLab file browser — right-click one of these files and choose Open With → Perspective.

bash
jupyter labextension install @perspective-dev/jupyterlab

This package is independent of PerspectiveWidget; install it only if you want the file renderers.