Merge pull request #3125 from perspective-dev/polars-virtual-server

`polars` Virtual Server

Author: texodus

docs/md/SUMMARY.md

@@ -56,6 +56,7 @@
 - [Virtual Servers](./how_to/python/virtual_server.md)
     - [DuckDB](./how_to/python/virtual_server/duckdb.md)
     - [ClickHouse](./how_to/python/virtual_server/clickhouse.md)
+    - [Polars](./how_to/python/virtual_server/polars.md)
     - [Custom](./how_to/python/virtual_server/custom.md)
 
 # Rust

docs/md/how_to/python/virtual_server.md

@@ -13,6 +13,8 @@ Perspective ships with built-in virtual server implementations for:
   `duckdb` Python package.
 - [**ClickHouse**](./virtual_server/clickhouse.md) — query a ClickHouse server
   using the `clickhouse-connect` Python package.
+- [**Polars**](./virtual_server/polars.md) — query in-memory Polars DataFrames
+  using the `polars` Python package.
 
 You can also [**implement your own**](./virtual_server/custom.md) virtual server
 to connect Perspective to any data source by subclassing `VirtualServerHandler`.

docs/md/how_to/python/virtual_server/polars.md

@@ -0,0 +1,49 @@
+# Polars Virtual Server
+
+Perspective provides a built-in virtual server for
+[Polars](https://pola.rs/), allowing `<perspective-viewer>` clients to query
+in-memory Polars DataFrames over WebSocket.
+
+## Installation
+
+```bash
+pip install perspective-python polars
+```
+
+## Usage
+
+Create a server that exposes Polars DataFrames to browser clients:
+
+```python
+import polars as pl
+import tornado.web
+import tornado.ioloop
+from perspective.virtual_servers.polars import PolarsVirtualServer
+from perspective.handlers.tornado import PerspectiveTornadoHandler
+
+# Load data into Polars DataFrames
+df = pl.read_parquet("data.parquet")
+
+# Create virtual server backed by Polars (dict of name -> DataFrame)
+server = PolarsVirtualServer({"my_table": df})
+
+# Serve over WebSocket
+app = tornado.web.Application([
+    (r"/websocket", PerspectiveTornadoHandler, {"perspective_server": server}),
+])
+
+app.listen(8080)
+tornado.ioloop.IOLoop.current().start()
+```
+
+Connect from the browser:
+
+```javascript
+const websocket = await perspective.websocket("ws://localhost:8080/websocket");
+const table = await websocket.open_table("my_table");
+document.getElementById("viewer").load(table);
+```
+
+## Examples
+
+- [Python Polars example](https://github.com/perspective-dev/perspective/tree/master/examples/python-polars-virtual)

examples/python-clickhouse-virtual/server.py

@@ -10,6 +10,7 @@
 #  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 #  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+import logging
 from pathlib import Path
 
 import clickhouse_connect
@@ -20,9 +21,13 @@
 import tornado.ioloop
 import tornado.web
 
-from loguru import logger
 from tornado.web import StaticFileHandler
 
+logging.basicConfig(
+    level=logging.DEBUG,
+)
+
+logger = logging.getLogger(__name__)
 
 INPUT_FILE = (
     Path(__file__).parent.resolve()

examples/python-duckdb-virtual/index.html

@@ -23,7 +23,7 @@
             // Websocket connections at the specified URL.
             const websocket = await perspective.websocket("ws://localhost:3000/websocket");
             viewer.load(websocket);
-            viewer.restore({table: "data_source_one"})
+            viewer.restore({table: "memory.data_source_one"})
         </script>
     </body>
 </html>

examples/python-duckdb-virtual/server.py

@@ -10,6 +10,7 @@
 #  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 #  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
+import logging
 from pathlib import Path
 
 import duckdb
@@ -20,9 +21,13 @@
 import tornado.web
 import tornado.websocket
 
-from loguru import logger
 from tornado.web import StaticFileHandler
 
+logging.basicConfig(
+    level=logging.DEBUG,
+)
+
+logger = logging.getLogger(__name__)
 
 INPUT_FILE = (
     Path(__file__).parent.resolve()
@@ -31,7 +36,6 @@
     / "superstore.parquet"
 )
 
-
 if __name__ == "__main__":
     db = duckdb.connect(":memory:perspective")
     db.sql(

examples/python-polars-virtual/index.html

@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html>
+    <head>
+        <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no" />
+        <link rel="stylesheet" crossorigin="anonymous" href="/node_modules/@perspective-dev/viewer/dist/css/themes.css" />
+        <style>
+            perspective-viewer {
+                position: absolute;
+                inset: 0;
+            }
+        </style>
+    </head>
+    <body>
+        <perspective-viewer id="viewer" ,> </perspective-viewer>
+        <script type="module">
+            import "/node_modules/@perspective-dev/viewer/dist/cdn/perspective-viewer.js";
+            import "/node_modules/@perspective-dev/viewer-datagrid/dist/cdn/perspective-viewer-datagrid.js";
+            import "/node_modules/@perspective-dev/viewer-d3fc/dist/cdn/perspective-viewer-d3fc.js";
+            import perspective from "/node_modules/@perspective-dev/client/dist/cdn/perspective.js";
+            const viewer = document.getElementById("viewer");
+
+            // Create a client that expects a Perspective server to accept
+            // Websocket connections at the specified URL.
+            const websocket = await perspective.websocket("ws://localhost:3000/websocket");
+            viewer.load(websocket);
+            viewer.restore({table: "data_source_one"})
+        </script>
+    </body>
+</html>

examples/python-polars-virtual/package.json

@@ -0,0 +1,22 @@
+{
+    "name": "python-polars-virtual",
+    "private": true,
+    "version": "4.2.0",
+    "description": "An example of a Polars-backed Perspective virtual server.",
+    "scripts": {
+        "start": "PYTHONPATH=../../python/perspective python3 server.py"
+    },
+    "keywords": [],
+    "license": "Apache-2.0",
+    "dependencies": {
+        "@perspective-dev/client": "workspace:^",
+        "@perspective-dev/viewer": "workspace:^",
+        "@perspective-dev/viewer-d3fc": "workspace:^",
+        "@perspective-dev/viewer-datagrid": "workspace:^",
+        "@perspective-dev/workspace": "workspace:^",
+        "superstore-arrow": "catalog:"
+    },
+    "devDependencies": {
+        "npm-run-all": "catalog:"
+    }
+}

examples/python-polars-virtual/server.py

@@ -0,0 +1,61 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ 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 logging
+from pathlib import Path
+
+import polars as pl
+import perspective
+import perspective.handlers.tornado
+import perspective.virtual_servers.polars
+import tornado.ioloop
+import tornado.web
+import tornado.websocket
+
+from tornado.web import StaticFileHandler
+
+logger = logging.getLogger(__name__)
+
+INPUT_FILE = (
+    Path(__file__).parent.resolve()
+    / "node_modules"
+    / "superstore-arrow"
+    / "superstore.parquet"
+)
+
+
+if __name__ == "__main__":
+    df = pl.read_parquet(INPUT_FILE)
+    tables = {"data_source_one": df}
+
+    virtual_server = perspective.virtual_servers.polars.PolarsVirtualServer(tables)
+    app = tornado.web.Application(
+        [
+            (
+                r"/websocket",
+                perspective.handlers.tornado.PerspectiveTornadoHandler,
+                {"perspective_server": virtual_server},
+            ),
+            (r"/node_modules/(.*)", StaticFileHandler, {"path": "../../node_modules/"}),
+            (
+                r"/(.*)",
+                StaticFileHandler,
+                {"path": "./", "default_filename": "index.html"},
+            ),
+        ],
+        websocket_max_message_size=100 * 1024 * 1024,
+    )
+
+    app.listen(3000)
+    logger.info("Listening on http://localhost:3000")
+    loop = tornado.ioloop.IOLoop.current()
+    loop.start()