Struct Client

pub struct Client(/* private fields */);

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

The examples in this module are in JavaScript. See perspective docs for the Rust API.

The browser and node.js libraries both support the websocket(url) constructor, which connects to a remote perspective_server::Server instance over a WebSocket transport.

In the browser, the worker() constructor creates a new Web Worker perspective_server::Server and returns a Client connected to it.

In node.js, a pre-instantied Client connected synhronously to a global singleton perspective_server::Server is the default module export.

JavaScript Examples

Create a Web Worker perspective_server::Server in the browser and return a Client instance connected for it:

import perspective from "@finos/perspective";
const client = await perspective.worker();

Create a WebSocket connection to a remote perspective_server::Server:

import perspective from "@finos/perspective";
const client = await perspective.websocket("ws://locahost:8080/ws");

Access the synchronous client in node.js:

import { default as client } from "@finos/perspective";

The examples in this module are in Python. See perspective docs for the Rust API.

Python Examples

Create a perspective_server::Server and a local, synchronous Client instance connected for it:

import perspective;
server = perspective.Server()
client = server.new_local_client();

Examples

Create a perspective_server::Server and a synchronous Client via the perspective crate:

use perspective::server::Server;
use perspective::LocalClient;

let server = Server::default();
let client = perspective::LocalClient::new(&server);

Implementations

impl Client

pub fn new( handle_request: Py<PyAny>, close_cb: Option<Py<PyAny>>, ) -> PyResult<Self>

pub fn from_server( py: Python<'_>, server: Py<PySyncServer>, loop_callback: Option<Py<PyAny>>, ) -> PyResult<Self>

pub fn handle_response( &self, py: Python<'_>, response: Py<PyBytes>, ) -> PyResult<bool>

pub fn table( &self, py: Python<'_>, input: Py<PyAny>, limit: Option<u32>, index: Option<Py<PyString>>, name: Option<Py<PyString>>, format: Option<Py<PyString>>, ) -> PyResult<Table>

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

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.

JavaScript Examples

Load a CSV from a string:

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

Load an Arrow from an ArrayBuffer:

import * as fs from "node:fs/promises";
const table2 = await client.table(await fs.readFile("superstore.arrow"));

Load a CSV from a UInt8Array (the default for this type is Arrow) using a format override:

const enc = new TextEncoder();
const table = await client.table(enc.encode("x,y\n1,2\n3,4"), {
    format: "csv",
});

Create a table with an index:

const table = await client.table(data, { index: "Row ID" });

Python Examples

Load a CSV from a str:

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

Examples

Load a CSV from a String:

let opts = TableInitOptions::default();
let data = TableData::Update(UpdateData::Csv("x,y\n1,2\n3,4".into()));
let table = client.table(data, opts).await?;

pub fn open_table(&self, py: Python<'_>, name: String) -> PyResult<Table>

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.

JavaScript Examples

Get a virtual Table named “table_one” from this Client

const tables = await client.open_table("table_one");

Python Examples

tables = client.open_table("table_one");

Examples

let tables = client.open_table("table_one").await;

pub fn get_hosted_table_names(&self, py: Python<'_>) -> PyResult<Vec<String>>

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

JavaScript Examples

const tables = await client.get_hosted_table_names();

Python Examples

tables = client.get_hosted_table_names();

Examples

let tables = client.get_hosted_table_names().await;

pub fn on_hosted_tables_update( &self, py: Python<'_>, callback: Py<PyAny>, ) -> PyResult<u32>

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

JavaScript Examples

const sub = await client.on_hosted_tables_update(() => {
    console.log("Tables have updated!", await client.get_hosted_table_names());
});

// This invokes the handler
const table = await client.table("x\n1", {name: "test"});

// So does this
await table.delete();

// cleanup
await client.remove_hosted_tables_update(sub);

pub fn remove_hosted_tables_update( &self, py: Python<'_>, callback_id: u32, ) -> PyResult<()>

Remove a callback previously registered via Client::on_hosted_tables_update.

pub fn set_loop_callback( &self, py: Python<'_>, loop_cb: Py<PyAny>, ) -> PyResult<()>

Methods such as View::on_update take a callback function as an argument, which may be invoked by the Perspective runtime when updates occur. If provided a loop callback function via Client::set_loop_callback, such callback function invocations be passed to the loop callback instead.

Client::set_loop_callback can be used to control scheduling/conflation (e.g. by adding a delay), as well as executor integration.

pub fn terminate(&self, py: Python<'_>) -> PyResult<()>

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

Trait Implementations

impl IntoPy<Py<PyAny>> for Client

fn into_py(self, py: Python<'_>) -> PyObject

👎Deprecated since 0.23.0: IntoPy is going to be replaced by IntoPyObject. See the migration guide (https://pyo3.rs/v0.23.0/migration) for more information.

Performs the conversion.

impl<'py> IntoPyObject<'py> for Client

type Target = Client

The Python output type

type Output = Bound<'py, <Client as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Self as IntoPyObject<'_>>::Output, <Self as IntoPyObject<'_>>::Error>

Performs the conversion.

impl PyClass for Client

type Frozen = False

Whether the pyclass is frozen.

impl PyClassBaseType for Client

type LayoutAsBase = PyClassObject<Client>

type BaseNativeType = <Client as PyClassImpl>::BaseNativeType

type Initializer = PyClassInitializer<Client>

type PyClassMutability = <Client as PyClassImpl>::PyClassMutability

impl PyClassImpl for Client

const IS_BASETYPE: bool = true

#[pyclass(subclass)]

const IS_SUBCLASS: bool = false

#[pyclass(extends=…)]

const IS_MAPPING: bool = false

#[pyclass(mapping)]

const IS_SEQUENCE: bool = false

#[pyclass(sequence)]

type BaseType = PyAny

Base class

type ThreadChecker = SendablePyClass<Client>

This handles following two situations:

type PyClassMutability = <<PyAny as PyClassBaseType>::PyClassMutability as PyClassMutability>::MutableChild

Immutable or mutable

type Dict = PyClassDummySlot

Specify this class has #[pyclass(dict)] or not.

type WeakRef = PyClassDummySlot

Specify this class has #[pyclass(weakref)] or not.

type BaseNativeType = PyAny

The closest native ancestor. This is PyAny by default, and when you declare #[pyclass(extends=PyDict)], it’s PyDict.

fn items_iter() -> PyClassItemsIter

fn doc(py: Python<'_>) -> PyResult<&'static CStr>

Rendered class doc

fn lazy_type_object() -> &'static LazyTypeObject<Self>

fn dict_offset() -> Option<isize>

fn weaklist_offset() -> Option<isize>

impl PyClassNewTextSignature<Client> for PyClassImplCollector<Client>

fn new_text_signature(self) -> Option<&'static str>

impl<'a, 'py> PyFunctionArgument<'a, 'py> for &'a Client

type Holder = Option<PyRef<'py, Client>>

fn extract( obj: &'a Bound<'py, PyAny>, holder: &'a mut Self::Holder, ) -> PyResult<Self>

impl<'a, 'py> PyFunctionArgument<'a, 'py> for &'a mut Client

type Holder = Option<PyRefMut<'py, Client>>

fn extract( obj: &'a Bound<'py, PyAny>, holder: &'a mut Self::Holder, ) -> PyResult<Self>

impl PyMethods<Client> for PyClassImplCollector<Client>

fn py_methods(self) -> &'static PyClassItems

impl PyTypeInfo for Client

const NAME: &'static str = "Client"

Class name.

const MODULE: Option<&'static str>

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn type_object_bound(py: Python<'_>) -> Bound<'_, PyType>

👎Deprecated since 0.23.0: renamed to PyTypeInfo::type_object

Deprecated name for PyTypeInfo::type_object.

fn is_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn is_type_of_bound(object: &Bound<'_, PyAny>) -> bool

👎Deprecated since 0.23.0: renamed to PyTypeInfo::is_type_of

Deprecated name for PyTypeInfo::is_type_of.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.

fn is_exact_type_of_bound(object: &Bound<'_, PyAny>) -> bool

👎Deprecated since 0.23.0: renamed to PyTypeInfo::is_exact_type_of

Deprecated name for PyTypeInfo::is_exact_type_of.

impl DerefToPyAny for Client