perspective-python 3.0.0rc2__tar.gz → 3.0.0rc3__tar.gz

{perspective_python-3.0.0rc2 → perspective_python-3.0.0rc3}/Cargo.lock

@@ -1783,9 +1783,11 @@ checksum = "e3148f5046208a5d56bcfc03053e3ca6334e51da8dfb19b6cdc8b306fae3283e"
 
 [[package]]
 name = "perspective"
-version = "3.0.0-rc.2"
+version = "3.0.0-rc.3"
 dependencies = [
  "async-lock",
+ "axum",
+ "futures",
  "perspective-client",
  "perspective-server",
  "tokio",
@@ -1821,7 +1823,7 @@ dependencies = [
 
 [[package]]
 name = "perspective-client"
-version = "3.0.0-rc.2"
+version = "3.0.0-rc.3"
 dependencies = [
  "async-lock",
  "futures",
@@ -1843,7 +1845,7 @@ dependencies = [
 
 [[package]]
 name = "perspective-js"
-version = "3.0.0-rc.2"
+version = "3.0.0-rc.3"
 dependencies = [
  "anyhow",
  "base64 0.13.1",
@@ -1872,7 +1874,7 @@ dependencies = [
 
 [[package]]
 name = "perspective-lint"
-version = "3.0.0-rc.2"
+version = "3.0.0-rc.3"
 dependencies = [
  "glob",
  "yew-fmt",
@@ -1880,13 +1882,15 @@ dependencies = [
 
 [[package]]
 name = "perspective-python"
-version = "3.0.0-rc.2"
+version = "3.0.0-rc.3"
 dependencies = [
  "async-lock",
+ "cmake",
+ "cxx-build",
  "extend",
  "futures",
+ "num_cpus",
  "perspective-client",
- "perspective-server",
  "pollster",
  "pyo3",
  "pyo3-build-config 0.20.3",
@@ -1898,7 +1902,7 @@ dependencies = [
 
 [[package]]
 name = "perspective-server"
-version = "3.0.0-rc.2"
+version = "3.0.0-rc.3"
 dependencies = [
  "async-lock",
  "cmake",
@@ -1912,7 +1916,7 @@ dependencies = [
 
 [[package]]
 name = "perspective-viewer"
-version = "3.0.0-rc.2"
+version = "3.0.0-rc.3"
 dependencies = [
  "anyhow",
  "async-lock",

{perspective_python-3.0.0rc2 → perspective_python-3.0.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: perspective-python
-Version: 3.0.0rc2
+Version: 3.0.0rc3
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Summary: A data visualization and analytics component, especially well-suited for large and/or streaming datasets.
@@ -9,4 +9,10 @@ Author: Andrew Stein <steinlink@gmail.com>
 Author-email: Andrew Stein <steinlink@gmail.com>
 License: Apache-2.0
 Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 Project-URL: Source Code, https://github.com/finos/perspective
+
+# `perspective-python`
+
+This crate provides the Python bindings for Perspective.
+

{perspective_python-3.0.0rc2 → perspective_python-3.0.0rc3}/perspective/__init__.py

@@ -10,7 +10,7 @@
 #  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 #  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-__version__ = "3.0.0-rc.2"
+__version__ = "3.0.0-rc.3"
 __all__ = [
     "_jupyter_labextension_paths",
     "PerspectiveError",
@@ -25,7 +25,6 @@ __all__ = [
 from .perspective import (
     PySyncClient,
     PerspectiveError,
-    PySyncServer,
     Table,
     View,
     PySyncProxySession as ProxySession,
@@ -34,6 +33,7 @@ from .perspective import (
 from .widget import PerspectiveWidget
 from .viewer import PerspectiveViewer
 
+from .psp_cffi import ServerBase
 
 try:
     from .handlers import PerspectiveTornadoHandler
@@ -45,7 +45,7 @@ def default_loop_cb(fn, *args, **kwargs):
     return fn(*args, **kwargs)
 
 
-class Server(PySyncServer):
+class Server(ServerBase):
     def set_threadpool_size(self, n_cpus):
         pass
 

perspective_python-3.0.0rc3/perspective/psp_cffi.py

@@ -0,0 +1,127 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+#  ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+#  ┃ This file is part of the Perspective library, distributed under the terms ┃
+#  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+#  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import ctypes
+import os
+import platform
+from typing import Callable
+
+if "PSP_CXX_SO_PATH" in os.environ:
+    lib = ctypes.CDLL(os.environ["PSP_CXX_SO_PATH"])
+else:
+    ext = "so"
+    if platform.system().lower() == "windows":
+        ext = "dll"
+    arch = platform.machine().lower()
+    if arch == "amd64":
+        arch = "x86_64"
+    dylib_name = f"{platform.system().lower()}-{arch}-libpsp.{ext}"
+    lib = ctypes.CDLL(os.path.join(os.path.dirname(__file__), dylib_name))
+
+
+class EncodedApiResp(ctypes.Structure):
+    _pack_ = 1
+    _fields_ = [
+        ("data", ctypes.POINTER(ctypes.c_char)),
+        ("size", ctypes.c_uint32),
+        ("client_id", ctypes.c_uint32),
+    ]
+
+
+class EncodedApiEntries(ctypes.Structure):
+    _pack_ = 1
+    _fields_ = [
+        ("size", ctypes.c_uint32),
+        ("entries", ctypes.POINTER(EncodedApiResp)),
+    ]
+
+
+ProtoApiServerPtr = ctypes.c_void_p
+lib.psp_new_server.restype = ProtoApiServerPtr
+
+lib.psp_new_session.argtypes = [ProtoApiServerPtr]
+lib.psp_new_session.restype = ctypes.c_uint32
+
+lib.psp_handle_request.argtypes = [
+    ProtoApiServerPtr,
+    ctypes.c_uint32,
+    ctypes.c_char_p,
+    ctypes.c_size_t,
+]
+lib.psp_handle_request.restype = ctypes.POINTER(EncodedApiEntries)
+
+lib.psp_poll.argtypes = [ProtoApiServerPtr]
+lib.psp_poll.restype = ctypes.POINTER(EncodedApiEntries)
+
+lib.psp_new_session.argtypes = [ProtoApiServerPtr]
+lib.psp_new_session.restype = ctypes.c_uint32
+
+lib.psp_close_session.argtypes = [ProtoApiServerPtr, ctypes.c_uint32]
+lib.psp_close_session.restype = None
+
+lib.psp_delete_server.argtypes = [ProtoApiServerPtr]
+lib.psp_delete_server.restype = None
+
+
+class Session:
+    def __init__(self, server: "ServerBase"):
+        self._server: "ServerBase" = server
+        self._session_id = lib.psp_new_session(server._server)
+
+    def __del__(self):
+        lib.psp_close_session(self._server._server, self._session_id)
+
+    def handle_request(self, bytes_msg):
+        resps = lib.psp_handle_request(
+            self._server._server, self._session_id, bytes_msg, len(bytes_msg)
+        )
+        try:
+            size = resps.contents.size
+            for i in range(size):
+                resp = resps.contents.entries[i]
+                self._server._client_cbs[resp.client_id](resp.data[: resp.size])
+        finally:
+            for i in range(size):
+                lib.psp_free(resps.contents.entries[i].data)
+            lib.psp_free(resps.contents.entries)
+            lib.psp_free(resps)
+
+    def poll(self):
+        resps = lib.psp_poll(self._server._server)
+        try:
+            size = resps.contents.size
+            for i in range(size):
+                resp = resps.contents.entries[i]
+                self._server._client_cbs[resp.client_id](resp.data[: resp.size])
+        finally:
+            for i in range(size):
+                lib.psp_free(resps.contents.entries[i].data)
+            lib.psp_free(resps.contents.entries)
+            lib.psp_free(resps)
+
+
+class ServerBase:
+    def __init__(self):
+        self._client_cbs: dict[str, Callable[[bytes], None]] = {}
+        self._sessions: list[Session] = []
+        self._server: int = lib.psp_new_server()
+
+    def __del__(self):
+        for session in self._sessions:
+            del session
+        lib.psp_delete_server(self._server)
+
+    def new_session(self, cb: Callable[[bytes], None]):
+        session = Session(self)
+        self._client_cbs[session._session_id] = cb
+        self._sessions.append(session)
+        return session

{perspective_python-3.0.0rc2 → perspective_python-3.0.0rc3}/pyproject.toml

@@ -25,8 +25,12 @@ classifiers = [
 
 [tool.maturin]
 module-name = "perspective"
-data = "perspective_python-3.0.0rc2.data"
+data = "perspective_python-3.0.0rc3.data"
 features = ["pyo3/extension-module"]
+include = [
+    { path = "perspective/*libpsp.so", format = "wheel" },
+    { path = "perspective/*libpsp.dll", format = "wheel" },
+]
 manifest-path = "rust/perspective-python/Cargo.toml"
 
 [tool.pytest.ini_options]

{perspective_python-3.0.0rc2 → perspective_python-3.0.0rc3}/rust/perspective-client/Cargo.toml

@@ -12,7 +12,7 @@
 
 [package]
 name = "perspective-client"
-version = "3.0.0-rc.2"
+version = "3.0.0-rc.3"
 authors = ["Andrew Stein <steinlink@gmail.com>"]
 edition = "2021"
 description = "A data visualization and analytics component, especially well-suited for large and/or streaming datasets."
@@ -20,6 +20,7 @@ repository = "https://github.com/finos/perspective"
 license = "Apache-2.0"
 homepage = "https://perspective.finos.org"
 keywords = []
+links = "perspective_client"
 include = [
     "src/**/*",
     "Cargo.toml",
@@ -29,9 +30,13 @@ include = [
     "perspective.proto",
 ]
 
+[package.metadata.docs.rs]
+rustdoc-args = ["--html-in-header", "docs/index.html"]
+
 [features]
 default = []
 external-proto = ["protobuf-src"]
+external-protoc = []
 
 [lib]
 crate-type = ["rlib"]
@@ -46,12 +51,12 @@ async-lock = { version = "2.5.0" }
 futures = { version = "0.3.28" }
 itertools = { version = "0.10.1" }
 nanoid = { version = "0.4.0" }
-paste = { version = "1.0.14" }
+paste = { version = "1.0.12" }
 prost-types = { version = "0.12.3" }
 serde = { version = "1.0", features = ["derive"] }
 serde_bytes = { version = "0.11" }
 serde_json = { version = "1.0.107", features = ["raw_value"] }
-thiserror = { version = "1.0.56" }
+thiserror = { version = "1.0.55" }
 tracing = { version = ">=0.1.36" }
 tracing-unwrap = "1.0.1"
 

{perspective_python-3.0.0rc2 → perspective_python-3.0.0rc3}/rust/perspective-client/build.rs

@@ -14,6 +14,13 @@ use std::io::Result;
 use std::path::Path;
 
 fn prost_build() -> Result<()> {
+    // Output the path to docs files so they can be shared by `perspective-js` and
+    // `perspective-python`.
+    println!(
+        "cargo::metadata=DOCS_PATH={}/docs/",
+        env!("CARGO_MANIFEST_DIR")
+    );
+
     // This source file is included at `publish` time, but not `sbuild` time
     // because it is initially generated from the `perspective.proto` definition
     // in the C++ source.

perspective_python-3.0.0rc3/rust/perspective-client/docs/client/get_hosted_table_names.md

@@ -0,0 +1,34 @@
+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`]).
+
+<div class="javascript">
+
+# JavaScript Examples
+
+```javascript
+const tables = await client.get_hosted_table_names();
+```
+
+</div>
+<div class="python">
+
+# Python Examples
+
+```python
+tables = client.get_hosted_table_names();
+```
+
+</div>
+<div class="python">
+
+# Examples
+
+```rust
+let tables = client.get_hosted_table_names().await;
+```
+
+</div>

perspective_python-3.0.0rc3/rust/perspective-client/docs/client/open_table.md

@@ -0,0 +1,36 @@
+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`] `name`s can be looked up for each [`Client`] via
+[`Client::get_hosted_table_names`].
+
+<div class="javascript">
+
+# JavaScript Examples
+
+Get a virtual [`Table`] named "table_one" from this [`Client`]
+
+```javascript
+const tables = await client.open_table("table_one");
+```
+
+</div>
+<div class="python">
+
+# Python Examples
+
+```python
+tables = client.open_table("table_one");
+```
+
+</div>
+<div class="rust">
+
+# Examples
+
+```rust
+let tables = client.open_table("table_one").await;
+```
+
+</div>

perspective_python-3.0.0rc3/rust/perspective-client/docs/client/system_info.md

@@ -0,0 +1,14 @@
+Provides the [`SystemInfo`] struct, implementation-specific metadata about the
+`perspective_server::Server` runtime such as Memory and CPU usage.
+
+<div class="javascript">
+
+For WebAssembly servers, this method includes the WebAssembly heap size.
+
+# JavaScript Examples
+
+```javascript
+const info = await client.system_info();
+```
+
+</div>

perspective_python-3.0.0rc3/rust/perspective-client/docs/client/table.md

@@ -0,0 +1,84 @@
+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.
+
+<div class="javascript">
+
+# JavaScript Examples
+
+Load a CSV from a `string`:
+
+```javascript
+const table = await client.table("x,y\n1,2\n3,4");
+```
+
+Load an Arrow from an `ArrayBuffer`:
+
+```javascript
+import * as fs from "node:fs/promises";
+const table2 = await client.table(await fs.readFile("superstore.arrow"));
+```
+
+Create a table with an `index`:
+
+```javascript
+const table = await client.table(data, { index: "Row ID" });
+```
+
+</div>
+<div class="python">
+
+# Python Examples
+
+Load a CSV from a `str`:
+
+```python
+table = client.table("x,y\n1,2\n3,4")
+```
+
+</div>
+<div class="rust">
+
+# Examples
+
+Load a CSV from a `String`:
+
+```rust
+let opts = TableInitOptions::default();
+let data = TableData::Update(UpdateData::Csv("x,y\n1,2\n3,4".into()));
+let table = client.table(data, opts).await?;
+```
+
+</div>

perspective_python-3.0.0rc3/rust/perspective-client/docs/client/terminate.md

@@ -0,0 +1,2 @@
+Terminates this [`Client`], cleaning up any [`crate::View`] handles the
+[`Client`] has open as well as its callbacks.

perspective_python-3.0.0rc3/rust/perspective-client/docs/client.md

@@ -0,0 +1,70 @@
+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.
+
+<div class="javascript">
+
+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:
+
+```javascript
+import perspective from "@finos/perspective";
+const client = await perspective.worker();
+```
+
+Create a WebSocket connection to a remote `perspective_server::Server`:
+
+```javascript
+import perspective from "@finos/perspective";
+const client = await perspective.websocket("ws://locahost:8080/ws");
+```
+
+Access the synchronous client in node.js:
+
+```javascript
+import { default as client } from "@finos/perspective";
+```
+
+</div>
+<div class="python">
+
+# Python Examples
+
+Create a `perspective_server::Server` and a local, synchronous [`Client`]
+instance connected for it:
+
+```python
+import perspective;
+server = perspective.Server()
+client = server.new_local_client();
+```
+
+</div>
+<div class="rust">
+
+# Examples
+
+Create a `perspective_server::Server` and a synchronous [`Client`] via the
+`perspective` crate:
+
+```rust
+use perspective::server::Server;
+use perspective::LocalClient;
+
+let server = Server::default();
+let client = perspective::LocalClient::new(&server);
+```
+
+</div>

perspective_python-3.0.0rc3/rust/perspective-client/docs/index.html

@@ -0,0 +1,8 @@
+<style>
+    pre.language-javascript,
+    pre.language-python,
+    div.javascript,
+    div.python {
+        display: none;
+    }
+</style>

{perspective_python-3.0.0rc2/rust/perspective-python → perspective_python-3.0.0rc3/rust/perspective-client}/docs/table/clear.md

@@ -1,5 +1,5 @@
 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`].
+Calling [`Table::clear`], like [`Table::update`] and [`Table::remove`], will
+trigger an update event to any registered listeners via [`View::on_update`].

perspective_python-3.0.0rc3/rust/perspective-client/docs/table/columns.md

@@ -0,0 +1,30 @@
+Returns the column names of this [`Table`] in "natural" order (the ordering
+implied by the input format).
+
+<div class="javascript">
+
+# JavaScript Examples
+
+```javascript
+const columns = await table.columns();
+```
+
+</div>
+<div class="python">
+
+# Python Examples
+
+```python
+columns = table.columns()
+```
+
+</div>
+<div class="rust">
+
+# Examples
+
+```rust
+let columns = table.columns().await;
+```
+
+</div>

perspective_python-3.0.0rc3/rust/perspective-client/docs/table/delete.md

@@ -0,0 +1,48 @@
+Delete this [`Table`] and cleans up associated resources, assuming it has no
+[`View`] instances registered to it (which must be deleted first).
+
+[`Table`]s 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.
+
+<div class="javascript">
+
+# JavaScript Examples
+
+```javascript
+const table = await client.table("x,y\n1,2\n3,4");
+
+// ...
+
+await table.delete();
+```
+
+</div>
+<div class="python">
+
+# Python Examples
+
+```python
+table = client.table("x,y\n1,2\n3,4")
+
+// ...
+
+table.delete()
+```
+
+</div>
+<div class="rust">
+
+# Examples
+
+```rust
+let opts = TableInitOptions::default();
+let data = TableData::Update(UpdateData::Csv("x,y\n1,2\n3,4".into()));
+let table = client.table(data, opts).await?;
+
+// ...
+
+table.delete().await?;
+```
+
+</div>

perspective_python-3.0.0rc3/rust/perspective-client/docs/table/get_features.md

@@ -0,0 +1,2 @@
+Get a metadata dictionary of the `perspective_server::Server`'s features, which
+is (currently) implementation specific, but there is only one implementation.