Skip to main content

perspective-python API

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

For usage, see the Python User Guide.

Table​

class perspective.table.Table(data, limit=None, index=None)​

Bases: object

__init__(data, limit=None, index=None)​

Construct a Table using the provided data or schema and optional configuration dictionary.

Table instances are immutable - column names and data types cannot be changed after creation. If a schema is provided, the Table will be empty. Subsequent updates MUST conform to the column names and data types provided in the schema.

  • Parameters

    data (dict/list/pandas.DataFrame) – Data or schema which initializes the Table.

  • Keyword Arguments

    • index (str) – A string column name to use as the Table primary key.

    • limit (int) – The maximum number of rows the Table should have. Cannot be set at the same time as index. Updates past the limit will begin writing at row 0.

make_port()​

Create a new input port on the underlying gnode, and return an int containing the ID of the new input port.

remove_port(port_id)​

Remove the specified port from the underlying gnode.

get_index()​

Returns the Table’s index column, or None if an index is not specified by the user.

get_limit()​

Returns the Table’s limit, or None if an index is not specified by the user.

clear()​

Removes all the rows in the Table, but preserves everything else including the schema and any callbacks or registered View.

replace(data)​

Replaces all rows in the Table with the new data that conforms to the Table schema.

  • Parameters

    data (dict/list/pandas.DataFrame) – New data that will be filled into the Table.

size()​

Returns the row count of the Table.

num_rows()​

Returns the row count of the Table.

num_columns()​

Returns the column count of the Table.

schema(as_string=False)​

Returns the schema of this Table, a dict mapping of string column names to python data types.

  • Keyword Arguments

    as_string (bool) – returns the data types as string representations, if True

  • Returns

    A key-value mapping of column names to data types.

  • Return type

    dict

validate_expressions(expressions, as_string=False)​

Returns an dict with two keys: “expression_schema”, which is a schema containing the column names and data types for each valid expression in expressions, and “errors”, which is a dict of expressions to error objects that contain additional metadata: error_message, line, and column.

  • Parameters

    expressions (list) – A list of string expressions to validate and create a schema from.

  • Keyword Arguments

    as_string (bool) – If True, returns the data types as string representations so they can be serialized.

columns()​

Returns the column names of this Table.

  • Returns

    a list of string column names

  • Return type

    list

is_valid_filter(filter)​

Tests whether a given filter expression string is valid, e.g. that the filter term is not None or an unparsable date/datetime. null/ not null operators don’t need a comparison value.

  • Parameters

    filter (string) – The filter expression to validate.

  • Returns

    Whether this filter is valid.

  • Return type

    bool

update(data, port_id=0)​

Update the Table with new data.

Updates on Table without an explicit index are treated as appends. Updates on Table with an explicit index should have the index as part of the data param, as this instructs the engine to locate the indexed row and write into it. If an index is not provided, the update is treated as an append.

  • Parameters

    data (dict/list/pandas.DataFrame) – The data with which to update the Table.

Examples​
>>> tbl = Table({"a": [1, 2, 3], "b": ["a", "b", "c"]}, index="a")
>>> tbl.update({"a": [2, 3], "b": ["a", "a"]})
>>> tbl.view().to_dict()
{"a": [1, 2, 3], "b": ["a", "a", "a"]}

remove(pkeys, port_id=0)​

Removes the rows with the primary keys specified in pkeys.

If the Table does not have an index, remove() has no effect. Removes propagate to views derived from the table.

  • Parameters

    pkeys (list) – a list of primary keys to indicate the rows that should be removed.

Examples​
>>> tbl = Table({"a": [1, 2, 3]}, index="a")
>>> tbl.remove([2, 3])
>>> tbl.view().to_records()
[{"a": 1}]

view(columns=None, group_by=None, split_by=None, aggregates=None, sort=None, filter=None, expressions=None)​

Create a new View from this Table via the supplied keyword arguments.

A View is an immutable set of transformations applied to the data stored in a Table, which can be used for querying, pivoting, aggregating, sorting, and filtering.

  • 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.

  • Returns

    A new View

    instance bound to this Table.

  • Return type

    View

Examples​
>>> tbl = Table({"a": [1, 2, 3]})
>>> view = tbl.view(filter=[["a", "==", 1]]
>>> view.to_dict()
>>> {"a": [1]}

on_delete(callback)​

Register a callback to be invoked when the delete() method is called on this Table.

  • Parameters

    callback (func) – A callback function to invoke on delete.

Examples​
>>> def deleter():
...     print("Delete called!")
>>> table.on_delete(deleter)
>>> table.delete()
>>> Delete called!

remove_delete(callback)​

De-register the supplied callback from the delete() event for this Table

Examples​
>>> def deleter():
...     print("Delete called!")
>>> table.on_delete(deleter)
>>> table.remove_delete(deleter)
>>> table.delete()

delete()​

Delete this Table and clean up associated resources, assuming it has no View instances registered to it (which must be deleted first).

View​

class perspective.table.view.View(Table, **kwargs)​

Bases: object

A View object represents a specific transform (pivot, filter, sort, etc) configuration on an underlying Table. View objects cannot be directly instantiated - they must be derived from an existing Table via the view() method.

View instances receive all updates from the Table from which they are derived, and can be serialized (via to_\* methods) or trigger a callback when it is updated. View objects will remain in memory and actively process updates until delete() method is called.

get_config()​

Returns a copy of the immutable configuration kwargs from which this View was instantiated.

  • Returns

    kwargs supplied to the

    perspective.Table.view() method.

  • Return type

    dict

sides()​

An integer representing the # of hierarchial axis on this View.

0 - Neither group_by nor split_by properties are set.

1 - group_by is set.

2 - split_by is set (and also maybe group_by).

  • Returns

    0 <= N <= 2

  • Return type

    int

get_min_max(colname)​

Calculates the [min, max] of the leaf nodes of a column colname.

  • Parameters

    colname (str) – The name of the column to calcualte range for.

  • Returns

    list of 2 elements, the min and max of the

num_rows()​

The number of aggregated rows in the View.

This count includes the total aggregate rows for all group_by depth levels, and can also be affected by any applied filter.

  • Returns

    Number of rows.

  • Return type

    int

num_columns()​

The number of aggregated columns in the View. This is affected by the split_by that are applied to the View.

  • Returns

    Number of columns.

  • Return type

    int

dimensions()​

The View and Table aggregated dimensions in the View.

  • Returns

    A dictionary with 4 fields indicating the dimensions of

    both the View and underlying Table objects: “num_view_rows”, “num_view_columns”, “num_table_rows”, “num_table_columns”

  • Return type

    dict

get_row_expanded(idx)​

Returns whether row at idx is expanded or collapsed.

  • Returns

    Is this row expanded?

  • Return type

    bool

expand(idx)​

Expands the row at ‘idx’, i.e. displaying its leaf rows.

  • Parameters

    idx (int) – Row index to expand.

collapse(idx)​

Collapses the row at ‘idx’, i.e. hiding its leaf rows.

  • Parameters

    idx (int) – Row index to collapse.

set_depth(depth)​

Sets the expansion depth of the pivot tree.

  • Parameters

    depth (int) – Depth to collapse all nodes to, which may be no greater then the length of the group_by property.

column_paths()​

Returns the names of the columns as they show in the View, i.e. the hierarchial columns when split_by is applied.

  • Returns

    obj`str`: Aggregated column names.

  • Return type

    list of

schema(as_string=False)​

The schema of this View, which is a key-value map that contains the column names and their Python data types.

If the columns are aggregated, their aggregated types will be shown returned instead.

  • Keyword Arguments

    as_string (bool) – returns data types as string representations, if True.

  • Returns

    A map of str column name to str or

    type, depending on the value of as_string kwarg.

  • Return type

    dict

expression_schema(as_string=False)​

Returns the expression schema of this View, which is a key-value map that contains the expressions and their Python data types.

If the columns are aggregated, their aggregated types will be returned instead.

  • Keyword Arguments

    as_string (bool) – returns data types as string representations, if True.

  • Returns

    A map of str column name to str or

    type, depending on the value of as_string kwarg.

  • Return type

    dict

on_update(callback, mode=None)​

Add a callback to be fired when perspective.Table.update() is called on the parent Table.

Multiple callbacks can be set through calling on_update multiple times, and will be called in the order they are set. Callback must be a callable function that takes exactly 1 or 2 parameters, depending on whether on_update is called with mode=”row”. The first parameter is always port_id, an int that indicates which input port the update comes from. A RuntimeError will be thrown if the callback has mis-configured parameters.

  • Parameters

    • callback (callable) – a callable function reference that will be called when perspective.Table.update() is called.

    • mode (str) – if set to “row”, the callback will be passed an Arrow-serialized dataset of the rows that were updated. Defaults to “none”.

Examples​
>>> def updater(port_id):
...     print("Update fired on port", port_id)
>>> def updater_with_delta(port_id, delta):
...     print("Update on port", port_id, "delta len:", len(delta)))
>>> view.on_update(updater)
>>> view.on_update(updater, mode="row")
>>> table.update({"a": [1]})'
>>> Update fired on port 0
>>> Update on port 0 delta len: 64

remove_update(callback)​

Given a callback function, remove it from the list of callbacks.

  • Parameters

    callback (func) – a function reference that will be removed.

Examples​
>>> table = perspective.Table(data)
>>> view = table.view()
>>> view2 = table.view()
>>> def callback():
...     print("called!")
>>> view.on_update(callback)
>>> view2.on_update(callback)
>>> table.update(new_data)
called!
>>> view2.remove_update(callback)
>>> table.update(new_data) # callback removed and will not fire

on_delete(callback)​

Set a callback to be run when the perspective.View.delete() method is called on this View.

  • Parameters

    callback (callable) – A callback to run after perspective.View.delete() method has been called.

Examples​
>>> def deleter():
>>>     print("Delete called!")
>>> view.on_delete(deleter)
>>> view.delete()
>>> Delete called!

delete()​

Delete the View and clean up all associated callbacks.

This method must be called to clean up callbacks used by the View, as well as allow for deletion of the underlying Table.

Examples​
>>> table = perspective.Table(data)
>>> view = table.view()
>>> view.delete()

remove_delete(callback)​

Remove the delete callback associated with this View.

  • Parameters

    callback (callable) – A reference to a callable function that will be removed from delete callbacks.

Examples​
>>> table = perspective.Table(data)
>>> view = table.view()
>>> view2 = table.view()
>>> def callback():
...     print("called!")
>>> view.on_delete(callback)
>>> view2.on_delete(callback)
>>> view.delete()
called!
>>> view2.remove_delete(callback)
>>> view2.delete() # callback removed and will not fire

to_records(**kwargs)​

Serialize the View’s dataset into a list of dict containing each row.

By default, the entire dataset is returned, though this can be windowed via kwargs. When group_by are applied, a __ROW_PATH__ column name will be generated in addition to the applied columns. When split_by are applied, column names will be qualified with their column group name.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • id (bool) – Whether to return a logical row ID for each row (Defaults to False).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A list of dict, where each dict

    represents a row of the current state of the View.

  • Return type

    list of dict

to_dict(**options)​

Serialize the View’s dataset into a dict of str keys and list values. Each key is a column name, and the associated value is the column’s data packed into a list. If the View is aggregated, the aggregated dataset will be returned.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • id (bool) – Whether to return a logical row ID for each row (Defaults to False).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A dictionary with string keys and list values, where

    key = column name and value = column values.

  • Return type

    dict

to_numpy(**options)​

Serialize the view’s dataset into a dict of str keys and numpy.array values. Each key is a column name, and the associated value is the column’s data packed into a numpy array.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • id (bool) – Whether to return a logical row ID for each row (Defaults to False).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A dictionary with string keys

    and numpy array values, where key = column name and value = column values.

  • Return type

    dict of numpy.array

to_df(**options)​

Serialize the view’s dataset into a pandas dataframe.

If the view is aggregated, the aggregated dataset will be returned.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • id (bool) – Whether to return a logical row ID for each row (Defaults to False).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A DataFrame serialization of the current

    state of this View.

  • Return type

    pandas.DataFrame

to_csv(**kwargs)​

Serialize the View’s dataset into a CSV string.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • id (bool) – Whether to return a logical row ID for each row (Defaults to False).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

    • date_format (str) – How datetime objects should be formatted in the CSV.

  • Returns

    A CSV-formatted string containing the serialized data.

  • Return type

    str

to_json(**kwargs)​

Serialize the View’s dataset into a list of dict containing each row.

By default, the entire dataset is returned, though this can be windowed via kwargs. When group_by are applied, a __ROW_PATH__ column name will be generated in addition to the applied columns. When split_by are applied, column names will be qualified with their column group name.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • id (bool) – Whether to return a logical row ID for each row (Defaults to False).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A list of dict, where each dict

    represents a row of the current state of the View.

  • Return type

    list of dict

to_columns(**options)​

Serialize the View’s dataset into a dict of str keys and list values. Each key is a column name, and the associated value is the column’s data packed into a list. If the View is aggregated, the aggregated dataset will be returned.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • id (bool) – Whether to return a logical row ID for each row (Defaults to False).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A dictionary with string keys and list values, where

    key = column name and value = column values.

  • Return type

    `dict`

    perspective.core contains modules that implements perspective-python in various environments, most notably PerspectiveWidget and the various Perspective web server handlers.

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

For usage of PerspectiveWidget and the Perspective web server handlers, see the User Guide in the sidebar.

perspective.set_threadpool_size(nthreads)​

Sets the size of the global Perspective thread pool, up to the total number of available cores. Passing an explicit None sets this limit to the detected hardware concurrency from the environment, which is also the default if this method is never called. set_threadpool_size() must be called before any other perspective-python API calls, and cannot be changed after such a call.

PerspectiveWidget​

PerspectiveWidget is a Perspective integration into JupyterLab.

class perspective.widget.widget.PerspectiveWidget(**kwargs: Any)​

Bases: DOMWidget, PerspectiveViewer

:class`~perspective.PerspectiveWidget` allows for Perspective to be used in the form of a Jupyter 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=False, **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: Any)​

Bases: 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, title=None)​

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.

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

    • table. (update data for the) –

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

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

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.

Perspective Webserver Handlers​

Perspective provides several ready-made integrations with webserver libraries that interfaces seamlessly with @finos/perspective-viewer in Javascript.

class perspective.handlers.tornado.PerspectiveTornadoHandler(*args, **kwargs)​

Bases: PerspectiveHandlerBase, WebSocketHandler

PerspectiveTornadoHandler is a drop-in implementation of Perspective.

Use it inside Tornado routing to create a server-side Perspective that is ready to receive websocket messages from the front-end perspective-viewer. Because Tornado implements an event loop, this handler links Perspective with IOLoop.current() in order to defer expensive operations until the next free iteration of the event loop.

The Perspective client and server will automatically keep the Websocket alive without timing out.

Examples​
>>> MANAGER = PerspectiveManager()
>>> MANAGER.host_table("data_source_one", Table(
...     pd.read_csv("superstore.csv")))
>>> app = tornado.web.Application([
...     (r"/", MainHandler),
...     (r"/websocket", PerspectiveTornadoHandler, {
...         "manager": MANAGER,
...         "check_origin": True
...     })
... ])

__init__(*args, **kwargs)​

Create a new instance of the PerspectiveHandlerBase with the given Manager instance.

  • Keyword Arguments

    • manager (PerspectiveManager) – A PerspectiveManager instance. Must be provided on initialization.

    • ( (check_origin) – obj`bool`): If True, all requests will be accepted regardless of origin. Defaults to False.

    • chunk_size (int) – Binary messages will not exceed this length (in bytes); payloads above this limit will be chunked across multiple messages. Defaults to 16_777_216 (16MB), and be disabled entirely with None.

on_message(*args, **kwargs)​

When the websocket receives a message, send it to the process method of the PerspectiveManager with a reference to the post callback.

async write_message(message: str, binary: bool = False)​

Websocket-specific implementation of writing a message to the websocket client. Must support writing either text or binary messages. Should only be called by this class’s post function, which handles all the perspective-specific logic

  • Parameters

    • message (str) – the message to write

    • binary (bool, optional) – whether or not to write as binary buffer

class perspective.handlers.starlette.PerspectiveStarletteHandler(**kwargs)​

Bases: PerspectiveHandlerBase

PerspectiveStarletteHandler is a drop-in implementation of Perspective.

The Perspective client and server will automatically keep the Websocket alive without timing out.

Examples​
>>> MANAGER = PerspectiveManager()
>>> MANAGER.host_table("data_source_one", Table(
...     pd.read_csv("superstore.csv")))
>>> app = FastAPI()
>>> async def endpoint(websocket: Websocket):
...     handler = PerspectiveStarletteHandler(manager, websocket)
...     await handler.run()
... app.add_api_websocket_route('/websocket', endpoint)

__init__(**kwargs)​

Create a new instance of the PerspectiveHandlerBase with the given Manager instance.

  • Keyword Arguments

    • manager (PerspectiveManager) – A PerspectiveManager instance. Must be provided on initialization.

    • ( (check_origin) – obj`bool`): If True, all requests will be accepted regardless of origin. Defaults to False.

    • chunk_size (int) – Binary messages will not exceed this length (in bytes); payloads above this limit will be chunked across multiple messages. Defaults to 16_777_216 (16MB), and be disabled entirely with None.

async write_message(message: str, binary: bool = False)​

Websocket-specific implementation of writing a message to the websocket client. Must support writing either text or binary messages. Should only be called by this class’s post function, which handles all the perspective-specific logic

  • Parameters

    • message (str) – the message to write

    • binary (bool, optional) – whether or not to write as binary buffer

class perspective.handlers.aiohttp.PerspectiveAIOHTTPHandler(**kwargs)​

Bases: PerspectiveHandlerBase

PerspectiveAIOHTTPHandler is a drop-in implementation of Perspective.

Use it inside AIOHTTP routing to create a server-side Perspective that is ready to receive websocket messages from the front-end perspective-viewer.

The Perspective client and server will automatically keep the Websocket alive without timing out.

Examples​
>>> manager = PerspectiveManager()
>>> async def websocket_handler(request):
...    handler = PerspectiveAIOHTTPHandler(manager=manager, request=request)
...    await handler.run()
>>> app = web.Application()
>>> app.router.add_get("/websocket", websocket_handler)

__init__(**kwargs)​

Create a new instance of the PerspectiveHandlerBase with the given Manager instance.

  • Keyword Arguments

    • manager (PerspectiveManager) – A PerspectiveManager instance. Must be provided on initialization.

    • ( (check_origin) – obj`bool`): If True, all requests will be accepted regardless of origin. Defaults to False.

    • chunk_size (int) – Binary messages will not exceed this length (in bytes); payloads above this limit will be chunked across multiple messages. Defaults to 16_777_216 (16MB), and be disabled entirely with None.

async write_message(message: str, binary: bool = False)​

Websocket-specific implementation of writing a message to the websocket client. Must support writing either text or binary messages. Should only be called by this class’s post function, which handles all the perspective-specific logic

  • Parameters

    • message (str) – the message to write

    • binary (bool, optional) – whether or not to write as binary buffer

Perspective Websocket Clients​

Perspective also provides several client interfaces to integrate with the above Perspective webserver handlers.

class perspective.client.tornado.TornadoPeriodic(*args, **kwargs)​

Bases: Periodic

class perspective.client.tornado.PerspectiveTornadoWebsocketConnection()​

Bases: PerspectiveWebsocketConnection

async perspective.client.tornado.websocket(url)​

Create a new websocket client at the given url using the thread current tornado loop.

class perspective.client.aiohttp.AIOHTTPPeriodic(*args, **kwargs)​

Bases: Periodic

class perspective.client.aiohttp.PerspectiveAIOHTTPWebsocketConnection(session=None)​

Bases: PerspectiveWebsocketConnection

async perspective.client.aiohttp.websocket(url, session=None)​

Create a new websocket client at the given url.

  • Parameters

    session (aiohttp.ClientSession) – An optional aiohtttp session

PerspectiveManager​

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

class perspective.manager.manager.PerspectiveManager(lock=False)​

Bases: _PerspectiveManagerInternal

PerspectiveManager is an orchestrator for running Perspective on the server side.

The core functionality resides in process(), which receives JSON-serialized messages from a client (implemented by perspective-viewer in the browser), executes the commands in the message, and returns the results of those commands back to the post_callback. Table instances should be passed to the manager using host_table - this allows server code to call Table APIs natively instead of proxying them through the Manager. Because Perspective is designed to be used in a shared context, i.e. multiple clients all accessing the same Table, PerspectiveManager comes with the context of sessions - an encapsulation of the actions and resources used by a single connection to Perspective, which can be cleaned up after the connection is closed.

  • When a client connects, for example through a websocket, a new session

    should be spawned using new_session().

  • When the websocket closes, call close() on the session instance to

    clean up associated resources.

__init__(lock=False)​

Create a new PerspectiveManager instance.

  • Keyword Arguments

    lock (bool) – [description]. Defaults to False.

lock()​

Block messages that can mutate the state of Table objects under management.

All PerspectiveManager objects exposed over the internet should be locked to prevent content from being mutated by clients.

unlock()​

Unblock messages that can mutate the state of Table objects under management.

host(item, name=None)​

Given a Table, place it under management and allow operations on it to be passed through the Manager instance.

  • Parameters

    item (Table) – a Table to be managed.

  • Keyword Arguments

    name (str) – an optional name to allow retrieval through get_table. A name will be generated if not provided.

host_table(name, table)​

Given a reference to a Table, manage it and allow operations on it to occur through the Manager.

If a function for queue_process is defined (i.e., by PerspectiveTornadoHandler), bind the function to Table and have it call the manager’s version of queue_process.

get_table(name)​

Return a table under management by name.

get_table_names()​

Return the tables that are hosted with this manager by name.

call_loop(f, *args, **kwargs)​

Calls f() on this PerspectiveManager’s event loop if it has one, or raise a PerspectiveError if there is no loop callback set using set_loop_callback().

set_loop_callback(loop_callback)​

Sets this PerspectiveManager to run in Async mode, defering update() application and releasing the GIL for expensive operations.

Once called, this PerspectiveManager and all Perspective objects it hosts must only be interacted with from the same thread.

  • Parameters

    loop_callback – A function which accepts a function reference and its args/kwargs, and schedules it to run on the same thread on which set_loop_callback()` was originally invoked.

perspective.manager.session.random()​

class perspective.manager.session.PerspectiveSession(manager)​

Bases: object

Encapsulates the actions and resources of a single connection to Perspective.

__init__(manager)​

Create a new session object, keeping track of a unique client_id and the manager the session belongs to.

PerspectiveSession should not be constructed directly. Instead, use PerspectiveManager.new_session() to create a new session.

process(message, post_callback)​

Pass a message to the manager’s process method, which passes the result to post_callback.

Additionally, intercept calls to on_update in order to track the callbacks that were created through this session. This allows for cleaning up callbacks after a session closes, which may not necessarily involve calling delete() on associated views.

close()​

Remove the views and callbacks that were created within this session when the session ends.