perspective-python API

perspective.table contains Table and View, the data primitives of Perspective.

For usage, see the Python User Guide.

Table

View

perspective.core contains modules that implements perspective-python in various environments, most notably PerspectiveWidget and PerspectiveTornadoHandler.

Additionally, perspective.core defines several enums that provide easy access to aggregate options, different plugins, sort directions etc.

For usage of PerspectiveWidget and PerspectiveTornadoHandler, see the User Guide in the sidebar.

PerspectiveWidget

PerspectiveWidget is a Perspective integration into JupyterLab.

class perspective.widget.widget.PerspectiveWidget(**kwargs)

Bases: ipywidgets.widgets.domwidget.DOMWidget, perspective.viewer.viewer.PerspectiveViewer

:class`~perspective.PerspectiveWidget` allows for Perspective to be used in the form of a JupyterLab IPython widget.

Using perspective.Table, you can create a widget that extends the full functionality of perspective-viewer. Changes on the viewer can be programatically set on the :class`~perspective.PerspectiveWidget` instance, and state is maintained across page refreshes.

Examples
>>> from perspective import Table, PerspectiveWidget
>>> data = {
...     "a": [1, 2, 3],
...     "b": [
...         "2019/07/11 7:30PM",
...         "2019/07/11 8:30PM",
...         "2019/07/11 9:30PM"
...     ]
... }
>>> tbl = Table(data, index="a")
>>> widget = PerspectiveWidget(
...     tbl,
...     group_by=["a"],
...     sort=[["b", "desc"]],
...     filter=[["a", ">", 1]]
... )
>>> widget.sort
[["b", "desc"]]
>>> widget.sort.append(["a", "asc"])
>>> widget.sort
[["b", "desc"], ["a", "asc"]]
>>> widget.update({"a": [4, 5]}) # Browser UI updates

_init_(data, index=None, limit=None, server=False, client=True, **kwargs)

Initialize an instance of :class`~perspective.PerspectiveWidget`

with the given table/data and viewer configuration.

If a pivoted DataFrame or MultiIndex table is passed in, the widget
preserves pivots and applies them.  See PerspectiveViewer.__init__ for
arguments that transform the view shown in the widget.

Args:

    data (`Table\`|:obj:\`View\`|:obj:\`dict\`|:obj:\`list\`|:obj:\`pandas.DataFrame\`|:obj:\`bytes\`|:obj:\`str`): a

        perspective.Table instance, a perspective.View instance, or
        a dataset to be loaded in the widget.

Keyword Arguments:

    index (`str`): A column name to be used as the primary key.

        Ignored if server is True.

    limit (`int`): A upper limit on the number of rows in the Table.

        Cannot be set at the same time as index, ignored if server
        is True.

    server (`bool`): Whether to run Perspective in “server-only”

        mode, where the front-end client does not have its own Table,
        and instead reads all data and operations from Python.

    client (`bool`):  If True, convert the dataset into an Apache Arrow

        binary and create the Table in Javascript using a copy of the
        data. Defaults to False.

    kwargs (`dict`): configuration options for the PerspectiveViewer,

        and Table constructor if data is a dataset.

Examples:

    ```python
    >>> widget = PerspectiveWidget(
    ...     {"a": [1, 2, 3]},
    ...     aggregates={"a": "avg"},
    ...     group_by=["a"],
    ...     sort=[["b", "desc"]],
    ...     filter=[["a", ">", 1]],
    ...     expressions=["// new column
    ```

“Sales” + “Profit””])

load(data, **options)

Load the widget with data. If running in client mode, this method serializes the data and calls the browser viewer’s load method. Otherwise, it calls Viewer.load() using super().

update(data)

Update the widget with new data. If running in client mode, this method serializes the data and calls the browser viewer’s update method. Otherwise, it calls Viewer.update() using super().

clear()

Clears the widget’s underlying Table.

In client mode, clears the _data attribute of the widget.

replace(data)

Replaces the widget’s Table with new data conforming to the same schema. Does not clear user-set state. If in client mode, serializes the data and sends it to the browser.

delete(delete_table=True)

Delete the Widget’s data and clears its internal state. If running in client mode, sends the delete() command to the browser. Otherwise calls delete on the underlying viewer.

  • Parameters

    delete_table (bool) – whether the underlying Table will be deleted. Defaults to True.

class perspective.viewer.viewer.PerspectiveViewer(**kwargs)

Bases: perspective.viewer.viewer_traitlets.PerspectiveTraitlets, object

PerspectiveViewer wraps the perspective.Table API and exposes an API around creating views, loading data, and updating data.

_init_(plugin='Datagrid', columns=None, group_by=None, split_by=None, aggregates=None, sort=None, filter=None, expressions=None, plugin_config=None, settings=True, theme=None, editable=False)

Initialize an instance of PerspectiveViewer with the given viewer

configuration.  Do not pass a Table or data into the constructor -
use the `load()` method to provide the viewer with data.

Keyword Arguments:

    columns (`list` of `str`): A list of column names to be

        visible to the user.

    group_by (`list` of `str`): A list of column names to

        use as group by.

    split_by (`list` of `str`): A list of column names

        to use as split by.

    aggregates (`dict` of `str` to `str`):  A dictionary

        of column names to aggregate types, which specify aggregates
        for individual columns.

    sort (`list` of `list` of `str`): A list of lists,

        each list containing a column name and a sort direction
        (`asc`, `desc`, `asc abs`, `desc abs`, `col asc`,
        `col desc`, `col asc abs`, `col desc abs`).

    filter (`list` of `list` of `str`): A list of lists,

        each list containing a column name, a filter comparator, and a
        value to filter by.

    expressions (`list` of `str`): A list of string

        expressions which are applied to the view.

    plugin (`str`/`perspective.Plugin`): Which plugin to

        select by default.

    plugin_config (`dict`): A configuration for the plugin, i.e.

        the datagrid plugin or a chart plugin.

    settings(`bool`): Whether the perspective query settings

        panel should be open.

    theme (`str`): The color theme to use.
    editable (`bool`): Whether to allow editability using the grid.

Examples:

    ```python
    >>> viewer = PerspectiveViewer(
    ...     aggregates={"a": "avg"},
    ...     group_by=["a"],
    ...     sort=[["b", "desc"]],
    ...     filter=[["a", ">", 1]],
    ...     expressions=["// new column
    ```

“Sales” + “Profit””]

… )

property table()

Returns the perspective.Table under management by the viewer.

load(data, **options)

Given a perspective.Table, a perspective.View, or data that can be handled by perspective.Table, pass it to the viewer. Like init, load accepts a perspective.Table, a dataset, or a schema. If running in client mode, load defers to the browser’s Perspective engine. This means that loading Python-only datasets, especially ones that cannot be serialized into JSON, may cause some issues.

load() resets the state of the viewer :

  • If a perspective.Table has already been loaded, \*\*options is ignored as the options already set on the Table take precedence.
  • If a perspective.View is loaded, the options on the perspective.Table linked to the view take precedence.

If data is passed in, a perspective.Table is automatically created by this method, and the options passed to \*\*config are extended to the new Table. If the widget already has a dataset, and the new data has different columns to the old one, then the widget state (pivots, sort, etc.) is cleared to prevent applying settings on columns that don’t exist.

  • Parameters

    data (Table\|:obj:`View`|:obj:`dict`|:obj:`list`|:obj:`pandas.DataFrame`|:obj:`bytes`|:obj:`str`) – a perspective.Table instance, a perspective.View instance, or a dataset to be loaded in the viewer.

  • Keyword Arguments

    • name (str) – An optional name to reference the table by so it can be accessed from the front-end. If not provided, a name will be generated.

    • index (str) – A column name to be used as the primary key. Ignored if a Table or View is supplied.

    • limit (int) – A upper limit on the number of rows in the Table. Cannot be set at the same time as index. Ignored if a Table or View is supplied.

Examples
>>> from perspective import Table, PerspectiveViewer
>>> data = {"a": [1, 2, 3]}
>>> tbl = Table(data)
>>> viewer = PerspectiveViewer()
>>> viewer.load(tbl)
>>> viewer.load(data, index="a") # viewer state is reset
>>> viewer2 = PerspectiveViewer()
>>> viewer2.load(tbl.view())

update(data)

Update the table under management by the viewer with new data. This function follows the semantics of Table.update(), and will be affected by whether an index is set on the underlying table.

  • Parameters

    • data (dict\|:obj:`list`|:obj:`pandas.DataFrame`) – the

    • data for the table. (update) –

clear()

Clears the rows of this viewer’s Table.

replace(data)

Replaces the rows of this viewer’s Table with new data.

  • Parameters

    • data (dict\|:obj:`list`|:obj:`pandas.DataFrame`) – new data

    • set into the table - must conform to the table's schema. (to) –

save()

Get the viewer’s attribute as a dictionary, symmetric with restore so that a viewer’s configuration can be reproduced.

restore(**kwargs)

Restore a given set of attributes, passed as kwargs (e.g. dictionary). Symmetric with save so that a given viewer’s configuration can be reproduced.

reset()

Resets the viewer’s attributes and state, but does not delete or modify the underlying Table.

Examples

widget = PerspectiveWidget(data, group_by=[“date”], plugin=Plugin.XBAR) widget.reset() widget.plugin #

delete(delete_table=True)

Delete the Viewer’s data and clears its internal state. If delete_table is True, the underlying perspective.Table and the internal View object will be deleted.

  • Parameters

    delete_table (bool) – whether the underlying Table will be deleted. Defaults to True.

PerspectiveTornadoHandler

PerspectiveTornadoHandler is a ready-made Perspective server that interfaces seamlessly with @finos/perspective-viewer in Javascript.

PerspectiveManager

PerspectiveManager implements a communication protocol between Perspective runtimes in different languages. Through its process() method, it allows runtimes to communicate instructions and interoperate.

← perspective-viewer API