perspective

The Python language bindings for Perspective, a high performance data-visualization and analytics component for the web browser.

A simple example which loads an Apache Arrow and computes a "Group By" operation, returning a new Arrow.

from perspective import Server

client = Server().new_local_client()
table = client.table(arrow_bytes_data)
view = table.view(group_by = ["CounterParty", "Security"])
arrow = view.to_arrow()

Perspective for Python uses the exact same C++ data engine used by the WebAssembly version and Rust version. The library consists of many of the same abstractions and API as in JavaScript, as well as Python-specific data loading support for NumPy, Pandas (and Apache Arrow, as in JavaScript).

Additionally, perspective-python provides a session manager suitable for integration into server systems such as Tornado websockets, AIOHTTP, or Starlette/FastAPI, which allows fully _virtual_ Perspective tables to be interacted with by multiple <perspective-viewer> in a web browser. You can also interact with a Perspective table from python clients, and to that end client libraries are implemented for both Tornado and AIOHTTP.

As <perspective-viewer> will only consume the data necessary to render the current screen, this runtime mode allows _ludicrously-sized_ datasets with instant-load after they've been manifest on the server (at the expense of network latency on UI interaction).

The included PerspectiveWidget allows running such a viewer in JupyterLab in either server or client (via WebAssembly) mode, and the included PerspectiveTornadoHandler makes it simple to extend a Tornado server with virtual Perspective support.

The perspective module exports several tools:

This user's guide provides an overview of the most common ways to use Perspective in Python: the Table API, the JupyterLab widget, and the Tornado handler.

More Examples are available on GitHub.

Installation

perspective-python contains full bindings to the Perspective API, a JupyterLab widget, and a WebSocket handlers for several webserver libraries that allow you to host Perspective using server-side Python.

perspective-python can be installed from PyPI via pip:

pip install perspective-python

Quick Start

A Table can be created from a dataset or a schema, the specifics of which are discussed in the JavaScript section of the user's guide. In Python, however, Perspective supports additional data types that are commonly used when processing data:

  • pandas.DataFrame
  • polars.DataFrame
  • bytes (encoding an Apache Arrow)
  • objects (either extracting a repr or via reference)
  • str (encoding as a CSV)

A Table is created in a similar fashion to its JavaScript equivalent:

from datetime import date, datetime
import numpy as np
import pandas as pd
import perspective

data = pd.DataFrame({
    "int": np.arange(100),
    "float": [i * 1.5 for i in range(100)],
    "bool": [True for i in range(100)],
    "date": [date.today() for i in range(100)],
    "datetime": [datetime.now() for i in range(100)],
    "string": [str(i) for i in range(100)]
})

table = perspective.table(data, index="float")

Likewise, a View can be created via the view() method:

view = table.view(group_by=["float"], filter=[["bool", "==", True]])
column_data = view.to_columns()
row_data = view.to_json()

Pandas and Polars Support

Perspective's Table can be constructed from pandas.DataFrame and polars.DataFrame objects. Internally, this just uses pyarrow::from_pandas, which dictates behavior of this feature including type support.

If the dataframe does not have an index set, an integer-typed column named "index" is created. If you want to preserve the indexing behavior of the dataframe passed into Perspective, simply create the Table with index="index" as a keyword argument. This tells Perspective to once again treat the index as a primary key:

data.set_index("datetime")
table = perspective.table(data, index="index")

Time Zone Handling

When parsing "datetime" strings, times are assumed _local time_ unless an explicit timezone offset is parsed. All "datetime" columns (regardless of input time zone) are _output_ to the user as datetime.datetime objects in _local time_ according to the Python runtime.

This behavior is consistent with Perspective's behavior in JavaScript. For more details, see this in-depth explanation of perspective-python semantics around time zone handling.

Callbacks and Events

perspective.Table allows for on_update and on_delete callbacks to be set—simply call on_update or on_delete with a reference to a function or a lambda without any parameters:

def update_callback():
    print("Updated!")

# set the update callback
on_update_id = view.on_update(update_callback)


def delete_callback():
    print("Deleted!")

# set the delete callback
on_delete_id = view.on_delete(delete_callback)

# set a lambda as a callback
view.on_delete(lambda: print("Deleted x2!"))

If the callback is a named reference to a function, it can be removed with remove_update or remove_delete:

view.remove_update(on_update_id)
view.remove_delete(on_delete_id)

Callbacks defined with a lambda function cannot be removed, as lambda functions have no identifier.

Hosting Table and View instances

Server "hosts" all perspective.Table and perspective.View instances created by its connected Clients. Hosted tables/views can have their methods called from other sources than the Python server, i.e. by a perspective-viewer running in a JavaScript client over the network, interfacing with perspective-python through the websocket API.

The server has full control of all hosted Table and View instances, and can call any public API method on hosted instances. This makes it extremely easy to stream data to a hosted Table using .update():

server = perspective.Server()
client = server.new_local_client()
table = client.table(data, name="data_source")

for i in range(10):
    # updates continue to propagate automatically
    table.update(new_data)

The name provided is important, as it enables Perspective in JavaScript to look up a Table and get a handle to it over the network. Otherwise, name will be assigned randomlu and the Client must look this up with CLient.get_hosted_table_names()

Client/Server Replicated Mode

Using Tornado and PerspectiveTornadoHandler, as well as Perspective's JavaScript library, we can set up "distributed" Perspective instances that allows multiple browser perspective-viewer clients to read from a common perspective-python server, as in the Tornado Example Project.

This architecture works by maintaining two Tables—one on the server, and one on the client that mirrors the server's Table automatically using on_update. All updates to the table on the server are automatically applied to each client, which makes this architecture a natural fit for streaming dashboards and other distributed use-cases. In conjunction with multithreading, distributed Perspective offers consistently high performance over large numbers of clients and large datasets.

_*server.py*_

from perspective import Server
from perspective.hadnlers.tornado import PerspectiveTornadoHandler

# Create an instance of Server, and host a Table
SERVER = Server()
CLIENT = SERVER.new_local_client()

# The Table is exposed at `localhost:8888/websocket` with the name `data_source`
client.table(data, name = "data_source")

app = tornado.web.Application([
    # create a websocket endpoint that the client JavaScript can access
    (r"/websocket", PerspectiveTornadoHandler, {"perspective_server": SERVER})
])

# Start the Tornado server
app.listen(8888)
loop = tornado.ioloop.IOLoop.current()
loop.start()

Instead of calling load(server_table), create a View using server_table and pass that into viewer.load(). This will automatically register an on_update callback that synchronizes state between the server and the client.

_*index.html*_

<perspective-viewer id="viewer" editable></perspective-viewer>

<script type="module">
    // Create a client that expects a Perspective server
    // to accept connections at the specified URL.
    const websocket = await perspective.websocket(
        "ws://localhost:8888/websocket"
    );

    // Get a handle to the Table on the server
    const server_table = await websocket.open_table("data_source_one");

    // Create a new view
    const server_view = await table.view();

    // Create a Table on the client using `perspective.worker()`
    const worker = await perspective.worker();
    const client_table = await worker.table(view);

    // Load the client table in the `<perspective-viewer>`.
    document.getElementById("viewer").load(client_table);
</script>

For a more complex example that offers distributed editing of the server dataset, see client_server_editing.html.

We also provide examples for Starlette/FastAPI and AIOHTTP:

Server-only Mode

The server setup is identical to Distributed Mode above, but instead of creating a view, the client calls load(server_table): In Python, use Server and PerspectiveTornadoHandler to create a websocket server that exposes a Table. In this example, table is a proxy for the Table we created on the server. All API methods are available on _proxies_, the.g.us calling view(), schema(), update() on table will pass those operations to the Python Table, execute the commands, and return the result back to Javascript.

<perspective-viewer id="viewer" editable></perspective-viewer>

const websocket = perspective.websocket("ws://localhost:8888/websocket");
const table = websocket.open_table("data_source");
document.getElementById("viewer").load(table);

  1#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
  2#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
  3#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
  4#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
  5#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
  6#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
  7#  ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
  8#  ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
  9#  ┃ This file is part of the Perspective library, distributed under the terms ┃
 10#  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 11#  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 12
 13__version__ = "4.2.0"
 14__all__ = [
 15    "_jupyter_labextension_paths",
 16    "Server",
 17    "Client",
 18    "Table",
 19    "View",
 20    "PerspectiveError",
 21    "ProxySession",
 22    "AsyncClient",
 23    "AsyncServer",
 24    "GenericSQLVirtualServerModel",
 25    "VirtualServer",
 26    "num_cpus",
 27    "set_num_cpus",
 28    "system_info",
 29]
 30
 31__doc__ = """
 32The Python language bindings for [Perspective](https://perspective-dev.github.io), a
 33high performance data-visualization and analytics component for the web browser.
 34
 35A simple example which loads an [Apache Arrow](https://arrow.apache.org/) and
 36computes a "Group By" operation, returning a new Arrow.
 37
 38```python
 39from perspective import Server
 40
 41client = Server().new_local_client()
 42table = client.table(arrow_bytes_data)
 43view = table.view(group_by = ["CounterParty", "Security"])
 44arrow = view.to_arrow()
 45```
 46
 47Perspective for Python uses the exact same C++ data engine used by the
 48[WebAssembly version](https://docs.rs/perspective-js/latest/perspective_js/) and
 49[Rust version](https://docs.rs/crate/perspective/latest). The library consists
 50of many of the same abstractions and API as in JavaScript, as well as
 51Python-specific data loading support for [NumPy](https://numpy.org/),
 52[Pandas](https://pandas.pydata.org/) (and
 53[Apache Arrow](https://arrow.apache.org/), as in JavaScript).
 54
 55Additionally, `perspective-python` provides a session manager suitable for
 56integration into server systems such as
 57[Tornado websockets](https://www.tornadoweb.org/en/stable/websocket.html),
 58[AIOHTTP](https://docs.aiohttp.org/en/stable/web_quickstart.html#websockets), or
 59[Starlette](https://www.starlette.io/websockets/)/[FastAPI](https://fastapi.tiangolo.com/advanced/websockets/),
 60which allows fully _virtual_ Perspective tables to be interacted with by
 61multiple `<perspective-viewer>` in a web browser. You can also interact with a
 62Perspective table from python clients, and to that end client libraries are
 63implemented for both Tornado and AIOHTTP.
 64
 65As `<perspective-viewer>` will only consume the data necessary to render the
 66current screen, this runtime mode allows _ludicrously-sized_ datasets with
 67instant-load after they've been manifest on the server (at the expense of
 68network latency on UI interaction).
 69
 70The included `PerspectiveWidget` allows running such a viewer in
 71[JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) in either server or
 72client (via WebAssembly) mode, and the included `PerspectiveTornadoHandler`
 73makes it simple to extend a Tornado server with virtual Perspective support.
 74
 75The `perspective` module exports several tools:
 76
 77-   `Server` the constructor for a new isntance of the Perspective data engine.
 78-   The `perspective.widget` module exports `PerspectiveWidget`, the JupyterLab
 79    widget for interactive visualization in a notebook cell.
 80-   The `perspective.handlers` modules exports web frameworks handlers that
 81    interface with a `perspective-client` in JavaScript.
 82    -   `perspective.handlers.tornado.PerspectiveTornadoHandler` for
 83        [Tornado](https://www.tornadoweb.org/)
 84    -   `perspective.handlers.starlette.PerspectiveStarletteHandler` for
 85        [Starlette](https://www.starlette.io/) and
 86        [FastAPI](https://fastapi.tiangolo.com)
 87    -   `perspective.handlers.aiohttp.PerspectiveAIOHTTPHandler` for
 88        [AIOHTTP](https://docs.aiohttp.org),
 89
 90This user's guide provides an overview of the most common ways to use
 91Perspective in Python: the `Table` API, the JupyterLab widget, and the Tornado
 92handler.
 93
 94[More Examples](https://github.com/perspective-dev/perspective/tree/master/examples) are
 95available on GitHub.
 96
 97## Installation
 98
 99`perspective-python` contains full bindings to the Perspective API, a JupyterLab
100widget, and a WebSocket handlers for several webserver libraries that allow you
101to host Perspective using server-side Python.
102
103`perspective-python` can be installed from [PyPI](https://pypi.org) via `pip`:
104
105```bash
106pip install perspective-python
107```
108
109## Quick Start
110
111A `Table` can be created from a dataset or a schema, the specifics of which are
112[discussed](#loading-data-with-table) in the JavaScript section of the user's
113guide. In Python, however, Perspective supports additional data types that are
114commonly used when processing data:
115
116-   `pandas.DataFrame`
117-   `polars.DataFrame`
118-   `bytes` (encoding an Apache Arrow)
119-   `objects` (either extracting a repr or via reference)
120-   `str` (encoding as a CSV)
121
122A `Table` is created in a similar fashion to its JavaScript equivalent:
123
124```python
125from datetime import date, datetime
126import numpy as np
127import pandas as pd
128import perspective
129
130data = pd.DataFrame({
131    "int": np.arange(100),
132    "float": [i * 1.5 for i in range(100)],
133    "bool": [True for i in range(100)],
134    "date": [date.today() for i in range(100)],
135    "datetime": [datetime.now() for i in range(100)],
136    "string": [str(i) for i in range(100)]
137})
138
139table = perspective.table(data, index="float")
140```
141
142Likewise, a `View` can be created via the `view()` method:
143
144```python
145view = table.view(group_by=["float"], filter=[["bool", "==", True]])
146column_data = view.to_columns()
147row_data = view.to_json()
148```
149
150#### Pandas and Polars Support
151
152Perspective's `Table` can be constructed from `pandas.DataFrame` and
153`polars.DataFrame` objects. Internally, this just uses
154[`pyarrow::from_pandas`](https://arrow.apache.org/docs/python/pandas.html),
155which dictates behavior of this feature including type support.
156
157If the dataframe does not have an index set, an integer-typed column named
158`"index"` is created. If you want to preserve the indexing behavior of the
159dataframe passed into Perspective, simply create the `Table` with
160`index="index"` as a keyword argument. This tells Perspective to once again
161treat the index as a primary key:
162
163```python
164data.set_index("datetime")
165table = perspective.table(data, index="index")
166```
167
168#### Time Zone Handling
169
170When parsing `"datetime"` strings, times are assumed _local time_ unless an
171explicit timezone offset is parsed. All `"datetime"` columns (regardless of
172input time zone) are _output_ to the user as `datetime.datetime` objects in
173_local time_ according to the Python runtime.
174
175This behavior is consistent with Perspective's behavior in JavaScript. For more
176details, see this in-depth
177[explanation](https://github.com/perspective-dev/perspective/pull/867) of
178`perspective-python` semantics around time zone handling.
179
180#### Callbacks and Events
181
182`perspective.Table` allows for `on_update` and `on_delete` callbacks to be
183set—simply call `on_update` or `on_delete` with a reference to a function or a
184lambda without any parameters:
185
186```python
187def update_callback():
188    print("Updated!")
189
190# set the update callback
191on_update_id = view.on_update(update_callback)
192
193
194def delete_callback():
195    print("Deleted!")
196
197# set the delete callback
198on_delete_id = view.on_delete(delete_callback)
199
200# set a lambda as a callback
201view.on_delete(lambda: print("Deleted x2!"))
202```
203
204If the callback is a named reference to a function, it can be removed with
205`remove_update` or `remove_delete`:
206
207```python
208view.remove_update(on_update_id)
209view.remove_delete(on_delete_id)
210```
211
212Callbacks defined with a lambda function cannot be removed, as lambda functions
213have no identifier.
214
215### Hosting `Table` and `View` instances
216
217`Server` "hosts" all `perspective.Table` and `perspective.View` instances
218created by its connected `Client`s. Hosted tables/views can have their methods
219called from other sources than the Python server, i.e. by a `perspective-viewer`
220running in a JavaScript client over the network, interfacing with
221`perspective-python` through the websocket API.
222
223The server has full control of all hosted `Table` and `View` instances, and can
224call any public API method on hosted instances. This makes it extremely easy to
225stream data to a hosted `Table` using `.update()`:
226
227```python
228server = perspective.Server()
229client = server.new_local_client()
230table = client.table(data, name="data_source")
231
232for i in range(10):
233    # updates continue to propagate automatically
234    table.update(new_data)
235```
236
237The `name` provided is important, as it enables Perspective in JavaScript to
238look up a `Table` and get a handle to it over the network. Otherwise, `name`
239will be assigned randomlu and the `Client` must look this up with
240`CLient.get_hosted_table_names()`
241
242### Client/Server Replicated Mode
243
244Using Tornado and
245[`PerspectiveTornadoHandler`](python.md#perspectivetornadohandler), as well as
246`Perspective`'s JavaScript library, we can set up "distributed" Perspective
247instances that allows multiple browser `perspective-viewer` clients to read from
248a common `perspective-python` server, as in the
249[Tornado Example Project](https://github.com/perspective-dev/perspective/tree/master/examples/python-tornado).
250
251This architecture works by maintaining two `Tables`—one on the server, and one
252on the client that mirrors the server's `Table` automatically using `on_update`.
253All updates to the table on the server are automatically applied to each client,
254which makes this architecture a natural fit for streaming dashboards and other
255distributed use-cases. In conjunction with [multithreading](#multi-threading),
256distributed Perspective offers consistently high performance over large numbers
257of clients and large datasets.
258
259_*server.py*_
260
261```python
262from perspective import Server
263from perspective.hadnlers.tornado import PerspectiveTornadoHandler
264
265# Create an instance of Server, and host a Table
266SERVER = Server()
267CLIENT = SERVER.new_local_client()
268
269# The Table is exposed at `localhost:8888/websocket` with the name `data_source`
270client.table(data, name = "data_source")
271
272app = tornado.web.Application([
273    # create a websocket endpoint that the client JavaScript can access
274    (r"/websocket", PerspectiveTornadoHandler, {"perspective_server": SERVER})
275])
276
277# Start the Tornado server
278app.listen(8888)
279loop = tornado.ioloop.IOLoop.current()
280loop.start()
281```
282
283Instead of calling `load(server_table)`, create a `View` using `server_table`
284and pass that into `viewer.load()`. This will automatically register an
285`on_update` callback that synchronizes state between the server and the client.
286
287_*index.html*_
288
289```html
290<perspective-viewer id="viewer" editable></perspective-viewer>
291
292<script type="module">
293    // Create a client that expects a Perspective server
294    // to accept connections at the specified URL.
295    const websocket = await perspective.websocket(
296        "ws://localhost:8888/websocket"
297    );
298
299    // Get a handle to the Table on the server
300    const server_table = await websocket.open_table("data_source_one");
301
302    // Create a new view
303    const server_view = await table.view();
304
305    // Create a Table on the client using `perspective.worker()`
306    const worker = await perspective.worker();
307    const client_table = await worker.table(view);
308
309    // Load the client table in the `<perspective-viewer>`.
310    document.getElementById("viewer").load(client_table);
311</script>
312```
313
314For a more complex example that offers distributed editing of the server
315dataset, see
316[client_server_editing.html](https://github.com/perspective-dev/perspective/blob/master/examples/python-tornado/client_server_editing.html).
317
318We also provide examples for Starlette/FastAPI and AIOHTTP:
319
320-   [Starlette Example Project](https://github.com/perspective-dev/perspective/tree/master/examples/python-starlette).
321-   [AIOHTTP Example Project](https://github.com/perspective-dev/perspective/tree/master/examples/python-aiohttp).
322
323### Server-only Mode
324
325The server setup is identical to [Distributed Mode](#distributed-mode) above,
326but instead of creating a view, the client calls `load(server_table)`: In
327Python, use `Server` and `PerspectiveTornadoHandler` to create a websocket
328server that exposes a `Table`. In this example, `table` is a proxy for the
329`Table` we created on the server. All API methods are available on _proxies_,
330the.g.us calling `view()`, `schema()`, `update()` on `table` will pass those
331operations to the Python `Table`, execute the commands, and return the result
332back to Javascript.
333
334```html
335<perspective-viewer id="viewer" editable></perspective-viewer>
336```
337
338```javascript
339const websocket = perspective.websocket("ws://localhost:8888/websocket");
340const table = websocket.open_table("data_source");
341document.getElementById("viewer").load(table);
342```
343
344"""
345
346
347import functools
348
349from .perspective import (
350    Client,
351    PerspectiveError,
352    ProxySession,
353    Server,
354    AsyncServer,
355    AsyncClient,
356    VirtualServer,
357    GenericSQLVirtualServerModel,
358    # NOTE: these are classes without constructors,
359    # so we import them just for type hinting
360    Table,  # noqa: F401
361    View,  # noqa: F401
362    num_cpus,
363    set_num_cpus,
364)
365
366
367GLOBAL_SERVER = Server()
368GLOBAL_CLIENT = GLOBAL_SERVER.new_local_client()
369
370
371@functools.wraps(Client.table)
372def table(*args, **kwargs):
373    return GLOBAL_CLIENT.table(*args, **kwargs)
374
375
376@functools.wraps(Client.open_table)
377def open_table(*args, **kwargs):
378    return GLOBAL_CLIENT.table(*args, **kwargs)
379
380
381@functools.wraps(Client.get_hosted_table_names)
382def get_hosted_table_names(*args, **kwargs):
383    return GLOBAL_CLIENT.get_hosted_table_names(*args, **kwargs)
384
385
386@functools.wraps(Client.system_info)
387def system_info(*args, **kwargs):
388    return GLOBAL_CLIENT.system_info(*args, **kwargs)
389
390
391def _jupyter_labextension_paths():
392    """
393    Read by `jupyter labextension develop`
394    @private
395    """
396    return [{"src": "labextension", "dest": "@perspective-dev/jupyterlab"}]
class Server:

An instance of a Perspective server. Each Server instance is separate, and does not share Table (or other) data with other Servers.

Arguments

  • on_poll_request A callback function which the Server will invoke when there are updates that need to be flushed, after which you must _eventually_ call Server.poll (or else no updates will be processed). This optimization allows batching updates, depending on context.
def new_local_client(self, /):

Create a new Client instance bound to this Server directly.

def new_session(self, /, response_cb):

Create a Session for this Server, suitable for exactly one Client (not necessarily in this process). A Session represents the server-side state of a single client-to-server connection.

Arguments

  • session_handler - An implementor of SessionHandler which will be invoked by the Server when a response message needs to be sent to the Client. The response itself should be passed to Client.handle_response eventually, though it may-or-may-not be in the same process.
def poll(self, /):

Flush pending updates to this Server, including notifications to View.on_update callbacks.

Server.poll only needs to be called if you've implemented a custom Perspective Server and provided the on_poll_request constructor keyword argument.

Calling Session.poll may result in the send_response parameter which was used to construct this (or other) Session to fire. Whenever a Session.handle_request method is invoked for a perspective_server::Server, at least one Session.poll should be scheduled to clear other clients message queues.

poll() _must_ be called after Table.update or Table.remove and on_poll_request is notified, or the changes will not be applied.

class Client:

An instance of a Client is a connection to a single Server, whether locally in-memory or remote over some transport like a WebSocket.

Client and Perspective objects derived from it have _synchronous_ APIs, suitable for use in a repl or script context where this is the _only_ Client connected to its Server. If you want to integrate with a Web framework or otherwise connect multiple clients, use AsyncClient.

def from_server(server):

Create a new Client instance bound to a specific in-process Server (e.g. generally _not_ the global Server).

def handle_response(self, /, response):

Handle a message from the external message queue. Client.handle_response is part of the low-level message-handling API necessary to implement new transports for a Client connection to a local-or-remote Server, and doesn't generally need to be called directly by "users" of a Client once connected.

def table(self, /, input, limit=None, index=None, name=None, format=None):

Creates a new Table from either a _schema_ or _data_.

The Client.table factory function can be initialized with either a _schema_ (see Table.schema), or data in one of these formats:

  • Apache Arrow
  • CSV
  • JSON row-oriented
  • JSON column-oriented
  • NDJSON

When instantiated with _data_, the schema is inferred from this data. While this is convenient, inferrence is sometimes imperfect e.g. when the input is empty, null or ambiguous. For these cases, Client.table can first be instantiated with a explicit schema.

When instantiated with a _schema_, the resulting Table is empty but with known column names and column types. When subsqeuently populated with Table.update, these columns will be _coerced_ to the schema's type. This behavior can be useful when Client.table's column type inferences doesn't work.

The resulting Table is _virtual_, and invoking its methods dispatches events to the perspective_server::Server this Client connects to, where the data is stored and all calculation occurs.

Arguments

  • arg - Either _schema_ or initialization _data_.
  • options - Optional configuration which provides one of:
    • limit - The max number of rows the resulting Table can store.
    • index - The column name to use as an _index_ column. If this Table is being instantiated by _data_, this column name must be present in the data.
    • name - The name of the table. This will be generated if it is not provided.
    • format - The explicit format of the input data, can be one of "json", "columns", "csv" or "arrow". This overrides language-specific type dispatch behavior, which allows stringified and byte array alternative inputs.

Python Examples

Load a CSV from a str:

table = client.table("x,y\n1,2\n3,4")
def open_table(self, /, name):

Opens a Table that is hosted on the perspective_server::Server that is connected to this Client.

The name property of TableInitOptions is used to identify each Table. Table names can be looked up for each Client via Client.get_hosted_table_names.

Python Examples

table =  client.open_table("table_one");
def get_hosted_table_names(self, /):

Retrieves the names of all tables that this client has access to.

name is a string identifier unique to the Table (per Client), which can be used in conjunction with Client.open_table to get a Table instance without the use of Client.table constructor directly (e.g., one created by another Client).

Python Examples

tables = client.get_hosted_table_names();
def on_hosted_tables_update(self, /, callback):

Register a callback which is invoked whenever Client.table (on this Client) or Table.delete (on a Table belinging to this Client) are called.

def remove_hosted_tables_update(self, /, callback_id):

Remove a callback previously registered via Client.on_hosted_tables_update.

def system_info(self, /):

Provides the SystemInfo struct, implementation-specific metadata about the perspective_server.Server runtime such as Memory and CPU usage.

def terminate(self, /):

Terminates this Client, cleaning up any View handles the Client has open as well as its callbacks.

class Table:

Table is Perspective's columnar data frame, analogous to a Pandas/Polars DataFrame or Apache Arrow, supporting append & in-place updates, removal by index, and update notifications.

A Table contains columns, each of which have a unique name, are strongly and consistently typed, and contains rows of data conforming to the column's type. Each column in a Table must have the same number of rows, though not every row must contain data; null-values are used to indicate missing values in the dataset. The schema of a Table is _immutable after creation_, which means the column names and data types cannot be changed after the Table has been created. Columns cannot be added or deleted after creation either, but a View can be used to select an arbitrary set of columns from the Table.

def get_index(self, /):

Returns the name of the index column for the table.

Python Examples

table = perspective.table("x,y\n1,2\n3,4", index="x");
index = client.get_index()
def get_client(self, /):

Get a copy of the Client this Table came from.

def get_limit(self, /):

Returns the user-specified row limit for this table.

def get_name(self, /):

Returns the user-specified name for this table, or the auto-generated name if a name was not specified when the table was created.

def clear(self, /):

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

Calling Table.clear, like Table.update and Table.remove, will trigger an update event to any registered listeners via View.on_update.

def columns(self, /):

Returns the column names of this Table in "natural" order (the ordering implied by the input format).

# Python Examples

columns = table.columns()
def delete(self, /, lazy=False):

Delete this Table and cleans up associated resources.

Tables do not stop consuming resources or processing updates when they are garbage collected in their host language - you must call this method to reclaim these.

Arguments

  • options An options dictionary.
    • lazy Whether to delete this Table _lazily_. When false (the default), the delete will occur immediately, assuming it has no View instances registered to it (which must be deleted first, otherwise this method will throw an error). When true, the Table will only be marked for deltion once its View dependency count reaches 0.

Python Examples

table = client.table("x,y\n1,2\n3,4")

# ...

table.delete(lazy=True)
def make_port(self, /):

Create a unique channel ID on this Table, which allows View::on_update callback calls to be associated with the Table::update which caused them.

def on_delete(self, /, callback):

Register a callback which is called exactly once, when this Table is deleted with the Table.delete method.

Table.on_delete resolves when the subscription message is sent, not when the _delete_ event occurs.

def remove(self, /, input, format=None):

The type of the None singleton.

def remove_delete(self, /, callback_id):

Removes a listener with a given ID, as returned by a previous call to Table.on_delete.

def schema(self, /):

Returns a table's Schema, a mapping of column names to column types.

The mapping of a Table's column names to data types is referred to as a Schema. Each column has a unique name and a data type, one of:

  • "boolean" - A boolean type
  • "date" - A timesonze-agnostic date type (month/day/year)
  • "datetime" - A millisecond-precision datetime type in the UTC timezone
  • "float" - A 64 bit float
  • "integer" - A signed 32 bit integer (the integer type supported by JavaScript)
  • "string" - A String data type (encoded internally as a _dictionary_)

Note that all Table columns are _nullable_, regardless of the data type.

def validate_expressions(self, /, expression):

Validates the given expressions.

def view(self, /, **config):

Create a new View from this table with a specified ViewConfigUpdate.

See View struct.

Examples

view view = table.view(
    columns=["Sales"],
    aggregates={"Sales": "sum"},
    group_by=["Region", "State"],
)
def size(self, /):

Returns the number of rows in a Table.

def replace(self, /, input, format=None):

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

Calling Table.clear, like Table.update and Table.remove, will trigger an update event to any registered listeners via View.on_update.

def update(self, /, input, port_id=None, format=None):

Updates the rows of this table and any derived View instances.

Calling Table.update will trigger the View.on_update callbacks register to derived View, and the call itself will not resolve until _all_ derived View's are notified.

When updating a Table with an index, Table.update supports partial updates, by omitting columns from the update data.

Arguments

  • input - The input data for this Table. The schema of a Table is immutable after creation, so this method cannot be called with a schema.
  • options - Options for this update step - see perspective_client.UpdateOptions. ```
class View:

The View struct is Perspective's query and serialization interface. It represents a query on the Table's dataset and is always created from an existing Table instance via the Table.view method.

Views are immutable with respect to the arguments provided to the Table.view method; to change these parameters, you must create a new View on the same Table. However, each View is _live_ with respect to the Table's data, and will (within a conflation window) update with the latest state as its parent Table updates, including incrementally recalculating all aggregates, pivots, filters, etc. View query parameters are composable, in that each parameter works independently _and_ in conjunction with each other, and there is no limit to the number of pivots, filters, etc. which can be applied.

To construct a View, call the Table.view factory method. A Table can have as many Views associated with it as you need - Perspective conserves memory by relying on a single Table to power multiple Views concurrently.

def column_paths(self, /, **window):

Returns an array of strings containing the column paths of the View without any of the source columns.

A column path shows the columns that a given cell belongs to after pivots are applied.

def to_columns_string(self, /, **window):

Renders this View as a column-oriented JSON string. Useful if you want to save additional round trip serialize/deserialize cycles.

def to_json_string(self, /, **window):

Renders this View as a row-oriented JSON string.

def to_ndjson(self, /, **window):

Renders this View as an NDJSON formatted String.

def to_records(self, /, **window):

Renders this View as a row-oriented Python list.

def to_json(self, /, **window):

Renders this View as a row-oriented Python list.

def to_columns(self, /, **window):

Renders this View as a column-oriented Python dict.

def to_csv(self, /, **window):

Renders this View as a CSV String in a standard format.

def to_dataframe(self, /, **window):

Renders this View as a pandas.DataFrame.

def to_pandas(self, /, **window):

Renders this View as a pandas.DataFrame.

def to_polars(self, /, **window):

Renders this View as a polars.DataFrame.

def to_arrow(self, /, **window):

Renders this View as the Apache Arrow data format.

Arguments

def delete(self, /):

Delete this View and clean up all resources associated with it. View objects do not stop consuming resources or processing updates when they are garbage collected - you must call this method to reclaim these.

def expand(self, /, index):

The type of the None singleton.

def collapse(self, /, index):

The type of the None singleton.

def dimensions(self, /):

Returns this View's _dimensions_, row and column count, as well as those of the crate.Table from which it was derived.

  • num_table_rows - The number of rows in the underlying crate.Table.
  • num_table_columns - The number of columns in the underlying crate.Table (including the index column if this crate.Table was constructed with one).
  • num_view_rows - The number of rows in this View. If this View has a group_by clause, num_view_rows will also include aggregated rows.
  • num_view_columns - The number of columns in this View. If this View has a split_by clause, num_view_columns will include all _column paths_, e.g. the number of columns clause times the number of split_by groups.
def expression_schema(self, /):

The expression schema of this View, which contains only the expressions created on this View. See View.schema for details.

def get_config(self, /):

A copy of the ViewConfig object passed to the Table.view method which created this View.

def get_min_max(self, /, column_name):

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

Returns

A tuple of [min, max], whose types are column and aggregate dependent.

def num_rows(self, /):

The number of aggregated rows in this View. This is affected by the "group_by" configuration parameter supplied to this view's contructor.

Returns

The number of aggregated rows.

def schema(self, /):

The schema of this View.

The View schema differs from the schema returned by Table.schema; it may have different column names due to expressions or columns configs, or it maye have _different column types_ due to the application og group_by and aggregates config. You can think of Table.schema as the _input_ schema and View.schema as the _output_ schema of a Perspective pipeline.

def on_delete(self, /, callback):

Register a callback with this View. Whenever the View is deleted, this callback will be invoked.

def remove_delete(self, /, callback_id):

Unregister a previously registered View.on_delete callback.

def on_update(self, /, callback, mode=None):

Register a callback with this View. Whenever the view's underlying table emits an update, this callback will be invoked with an object containing port_id, indicating which port the update fired on, and optionally delta, which is the new data that was updated for each cell or each row.

Arguments

  • on_update - A callback function invoked on update, which receives an object with two keys: port_id, indicating which port the update was triggered on, and delta, whose value is dependent on the mode parameter.
  • options - If this is provided as OnUpdateOptions { mode: Some(OnUpdateMode::Row) }, then delta is an Arrow of the updated rows. Otherwise delta will be Option.None.
def remove_update(self, /, callback_id):

Unregister a previously registered update callback with this View.

Arguments

  • id - A callback id as returned by a recipricol call to View.on_update.

Examples

let callback = |_| async { print!("Updated!") };
let cid = view.on_update(callback, OnUpdateOptions::default()).await?;
view.remove_update(cid).await?;
PerspectiveError = <class 'perspective.PyPerspectiveError'>
class ProxySession:
def handle_request(self, /, data):

The type of the None singleton.

def handle_request_async(self, /, data):

The type of the None singleton.

def close(self, /):

The type of the None singleton.

class GenericSQLVirtualServerModel:
def get_hosted_tables(self, /):

The type of the None singleton.

def table_schema(self, /, table_id):

The type of the None singleton.

def table_size(self, /, table_id):

The type of the None singleton.

def view_column_size(self, /, view_id):

The type of the None singleton.

def table_validate_expression(self, /, table_id, expression):

The type of the None singleton.

def view_delete(self, /, view_id):

The type of the None singleton.

def table_make_view(self, /, table_id, view_id, config):

The type of the None singleton.

def view_get_data(self, /, view_id, config, viewport, schema):

The type of the None singleton.

def view_schema(self, /, view_id):

The type of the None singleton.

def view_size(self, /, view_id):

The type of the None singleton.

class VirtualServer:
def handle_request(self, /, bytes):

The type of the None singleton.

def num_cpus():

Returns the number of threads the internal threadpool will use.

def set_num_cpus(num_cpus):

Set the number of threads the internal threadpool will use. Can also be set with NUM_OMP_THREADS environment variable.

def system_info(self, /):

Provides the SystemInfo struct, implementation-specific metadata about the perspective_server.Server runtime such as Memory and CPU usage.