perspective-python 4.2.0__cp311-abi3-win_amd64.whl

perspective/handlers/tornado.py

@@ -0,0 +1,184 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ 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). ┃
+#  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+from tornado.websocket import WebSocketHandler, WebSocketClosedError
+from tornado.ioloop import IOLoop
+import perspective
+
+__doc__ = """
+Perspective ships with a pre-built Tornado handler that makes integration with
+`tornado.websockets` extremely easy. This allows you to run an instance of
+`Perspective` on a server using Python, open a websocket to a `Table`, and
+access the `Table` in JavaScript and through `<perspective-viewer>`. All
+instructions sent to the `Table` are processed in Python, which executes the
+commands, and returns its output through the websocket back to Javascript.
+
+### Python setup
+
+To use the handler, we need to first have a `Server`, a `Client` and an instance
+of a `Table`:
+
+```python
+SERVER = Server()
+CLIENT = SERVER.new_local_client()
+```
+
+Once the server has been created, create a `Table` instance with a name. The
+name that you host the table under is important — it acts as a unique accessor
+on the JavaScript side, which will look for a Table hosted at the websocket with
+the name you specify.
+
+```python
+TABLE = client.table(data, name="data_source_one")
+```
+
+After the server and table setup is complete, create a websocket endpoint and
+provide it a reference to `PerspectiveTornadoHandler`. You must provide the
+configuration object in the route tuple, and it must contain
+`"perspective_server"`, which is a reference to the `Server` you just created.
+
+```python
+from perspective.handlers.tornado import PerspectiveTornadoHandler
+
+app = tornado.web.Application([
+
+    # ... other handlers ...
+
+    # Create a websocket endpoint that the client JavaScript can access
+    (r"/websocket", PerspectiveTornadoHandler, {"perspective_server": SERVER, "check_origin": True})
+])
+```
+
+Optionally, the configuration object can also include `check_origin`, a boolean
+that determines whether the websocket accepts requests from origins other than
+where the server is hosted. See
+[Tornado docs](https://www.tornadoweb.org/en/stable/websocket.html#tornado.websocket.WebSocketHandler.check_origin)
+for more details.
+
+### JavaScript setup
+
+Once the server is up and running, you can access the Table you just hosted
+using `perspective.websocket` and `open_table()`. First, create a client that
+expects a Perspective server to accept connections at the specified URL:
+
+```javascript
+const websocket = await perspective.websocket("ws://localhost:8888/websocket");
+```
+
+Next open the `Table` we created on the server by name:
+
+```javascript
+const table = await websocket.open_table("data_source_one");
+```
+
+`table` is a proxy for the `Table` we created on the server. All operations that
+are possible through the JavaScript API are possible on the Python API as well,
+thus calling `view()`, `schema()`, `update()` etc. on `const table` will pass
+those operations to the Python `Table`, execute the commands, and return the
+result back to JavaScript. Similarly, providing this `table` to a
+`<perspective-viewer>` instance will allow virtual rendering:
+
+```javascript
+await viewer.load(table);
+```
+
+`perspective.websocket` expects a Websocket URL where it will send instructions.
+When `open_table` is called, the name to a hosted Table is passed through, and a
+request is sent through the socket to fetch the Table. No actual `Table`
+instance is passed inbetween the runtimes; all instructions are proxied through
+websockets.
+
+This provides for great flexibility — while `Perspective.js` is full of
+features, browser WebAssembly runtimes currently have some performance
+restrictions on memory and CPU feature utilization, and the architecture in
+general suffers when the dataset itself is too large to download to the client
+in full.
+
+The Python runtime does not suffer from memory limitations, utilizes Apache
+Arrow internal threadpools for threading and parallel processing, and generates
+architecture optimized code, which currently makes it more suitable as a
+server-side runtime than `node.js`.
+"""
+
+
+class PerspectiveTornadoHandler(WebSocketHandler):
+    """`PerspectiveTornadoHandler` is a `perspective.Server` API as a `tornado`
+    websocket handler.
+
+    Use it inside `tornado` routing to create a `perspective.Server` that can
+    connect to a JavaScript (Wasm) `Client`, providing a virtual interface to
+    the `Server`'s resources for e.g. `<perspective-viewer>`.
+
+    You may need to increase the `websocket_max_message_size` kwarg
+    to the `tornado.web.Application` constructor, as well as provide the
+    `max_buffer_size` optional arg, for large datasets.
+
+    # Arguments
+
+    -   `loop`: An optional `IOLoop` instance to use for scheduling IO calls,
+        defaults to `IOLoop.current()`.
+    -   `executor`: An optional executor for scheduling `perspective.Server`
+        message processing calls from websocket `Client`s.
+
+    # Examples
+
+    >>> server = psp.Server()
+    >>> client = server.new_local_client()
+    >>> client.table(pd.read_csv("superstore.csv"), name="data_source_one")
+    >>> app = tornado.web.Application([
+    ...     (r"/", MainHandler),
+    ...     (r"/websocket", PerspectiveTornadoHandler, {
+    ...         "perspective_server": server,
+    ...     })
+    ... ])
+    """
+
+    def check_origin(self, origin):
+        return True
+
+    def initialize(
+        self,
+        perspective_server=perspective.GLOBAL_SERVER,
+        loop=None,
+        executor=None,
+        max_buffer_size=None,
+    ):
+        self.server = perspective_server
+        self.loop = loop or IOLoop.current()
+        self.executor = executor
+        if max_buffer_size is not None:
+            self.request.connection.stream.max_buffer_size = max_buffer_size
+
+    def open(self):
+        def write(msg):
+            try:
+                self.write_message(msg, binary=True)
+            except WebSocketClosedError:
+                self.close()
+
+        def send_response(msg):
+            self.loop.add_callback(write, msg)
+
+        self.session = self.server.new_session(send_response)
+
+    def on_close(self) -> None:
+        self.session.close()
+        del self.session
+
+    def on_message(self, msg: bytes):
+        if not isinstance(msg, bytes):
+            return
+
+        if self.executor is None:
+            self.session.handle_request(msg)
+        else:
+            self.executor.submit(self.session.handle_request, msg)

perspective/templates/exported_widget.html.template

@@ -0,0 +1,35 @@
+<script type="module" src="$psp_cdn_perspective"></script>
+<script type="module" src="$psp_cdn_perspective_viewer"></script>
+<script type="module" src="$psp_cdn_perspective_viewer_datagrid"></script>
+<script type="module" src="$psp_cdn_perspective_viewer_d3fc"></script>
+<link rel="stylesheet" crossorigin="anonymous" href="$psp_cdn_perspective_viewer_themes" />
+
+<div class="perspective-envelope" id="perspective-envelope-$viewer_id">
+    <script type="application/vnd.apache.arrow.file">
+    $b64_data
+    </script>
+    <perspective-viewer style="height: 690px;"></perspective-viewer>
+    <script type="module">
+        // from MDN
+        function base64ToBytes(base64) {
+            const binString = atob(base64);
+            return Uint8Array.from(binString, (m) => m.codePointAt(0));
+        }
+
+        import * as perspective from "$psp_cdn_perspective";
+        const viewerId = $viewer_id;
+        const currentScript = document.scripts[document.scripts.length - 1];
+        const envelope = document.getElementById(`perspective-envelope-$${viewerId}`);
+        const dataScript = envelope.querySelector('script[type="application/vnd.apache.arrow.file"]');;
+        if (!dataScript)
+            throw new Error('data script missing for viewer', viewerId);
+        const data = base64ToBytes(dataScript.textContent);
+        const viewerAttrs = $viewer_attrs;
+
+        // Create a new worker, then a new table promise on that worker.
+        const table = await perspective.worker().table(data.buffer);
+        const viewer = envelope.querySelector('perspective-viewer');
+        viewer.load(table);
+        viewer.restore(viewerAttrs);
+    </script>
+</div>

perspective/tests/__init__.py

@@ -0,0 +1,11 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ 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). ┃
+#  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

perspective/tests/async/test_async_client.py

@@ -0,0 +1,83 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ 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). ┃
+#  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+from perspective import (
+    AsyncClient,
+    AsyncServer,
+    PerspectiveError,
+)
+
+
+import pytest
+from unittest.mock import Mock
+
+
+@pytest.fixture
+def server():
+    return AsyncServer()
+
+
+@pytest.fixture
+def client(server):
+    async def send_request(msg):
+        await sess.handle_request(msg)
+
+    async def send_response(msg):
+        await client.handle_response(msg)
+
+    sess = server.new_session(send_response)
+    client = AsyncClient(send_request)
+    return client
+
+
+@pytest.mark.asyncio
+async def test_send_request_callback_awaited(client):
+    table_names = await client.get_hosted_table_names()
+    assert table_names == []
+
+
+# This test also exists in the pyodide-tests/ pytest suite, with the same name.
+# Unfortunately code sharing between the two test suites is currently not easy.
+@pytest.mark.asyncio
+async def test_async_client_kitchen_sink(client):
+    """run various things on the async client"""
+    table = await client.table({"a": [0]}, name="my-cool-data", limit=100)
+    view = await table.view()
+    # synchronous methods
+    assert table.get_index() is None
+    assert table.get_name() == "my-cool-data"
+    limit = table.get_limit()
+    assert limit == 100
+
+    # view update callbacks
+    view_updated = Mock()
+    await view.on_update(view_updated)
+    for i in range(1, limit):
+        await table.update([{"a": i}])
+        await table.size()  # force update to process
+    assert (await table.size()) == limit
+    assert view_updated.call_count == limit - 1
+    rex = await view.to_records()
+    assert rex == [{"a": i} for i in range(limit)]
+
+    # view/table delete callbacks
+    view_deleted = Mock()
+    table_deleted = Mock()
+    await table.on_delete(table_deleted)
+    await view.on_delete(view_deleted)
+    with pytest.raises(PerspectiveError) as excinfo:
+        await table.delete()
+    assert excinfo.match(r"Cannot delete table with views")
+    await view.delete()
+    view_deleted.assert_called_once()
+    await table.delete()
+    table_deleted.assert_called_once()

perspective/tests/async/test_websocket_client.py

@@ -0,0 +1,124 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ 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 asyncio
+import threading
+import websocket
+
+import tornado.websocket
+import tornado.web
+import tornado.ioloop
+
+import perspective
+import perspective.handlers.tornado
+
+PORT = 8082
+
+
+def test_big_multi_thing(superstore):
+    async def init_table(client):
+        global SERVER_DATA
+        global SERVER_TABLE
+
+        SERVER_DATA = "x,y\n1,2\n3,4"
+        # with open(file_path, mode="rb") as file:
+        SERVER_TABLE = client.table(SERVER_DATA, name="superstore")
+
+        global ws
+        ws = websocket.WebSocketApp(
+            "ws://localhost:{}/websocket".format(PORT),
+            on_open=on_open,
+            on_message=on_message,
+            # on_error=on_error,
+            # on_close=on_close,
+        )
+
+        global ws_thread
+        ws_thread = threading.Thread(target=ws.run_forever)
+        ws_thread.start()
+
+    def server_thread():
+        def make_app(perspective_server):
+            return tornado.web.Application(
+                [
+                    (
+                        r"/websocket",
+                        perspective.handlers.tornado.PerspectiveTornadoHandler,
+                        {"perspective_server": perspective_server},
+                    ),
+                ]
+            )
+
+        perspective_server = perspective.Server()
+        app = make_app(perspective_server)
+        global server
+        server = app.listen(PORT, "0.0.0.0")
+
+        global server_loop
+        server_loop = tornado.ioloop.IOLoop.current()
+        client = perspective_server.new_local_client()
+        server_loop.call_later(0, init_table, client)
+        server_loop.start()
+
+    server_thread = threading.Thread(target=server_thread)
+    server_thread.start()
+
+    client_loop = asyncio.new_event_loop()
+    client_loop.set_debug(True)
+    client_thread = threading.Thread(target=client_loop.run_forever)
+    client_thread.start()
+
+    async def send_request(msg):
+        global ws
+        ws.send(msg, websocket.ABNF.OPCODE_BINARY)
+
+    def on_message(ws, message):
+        async def poke_client():
+            await client.handle_response(message)
+
+        asyncio.run_coroutine_threadsafe(poke_client(), client_loop)
+
+    # def on_error(ws, error):
+    #     print(f"Error!: {error}")
+
+    # def on_close(ws, close_status_code, close_msg):
+    #     print("Connection closed")
+
+    def on_open(ws):
+        global client
+        client = perspective.AsyncClient(send_request)
+        asyncio.run_coroutine_threadsafe(test(client), client_loop)
+
+    global count
+    count = 0
+
+    def update(x):
+        global count
+        count += 1
+
+    async def test(client):
+        table = await client.open_table("superstore")
+        view = await table.view()
+        await view.on_update(update)
+        SERVER_TABLE.update(SERVER_DATA)
+        assert await table.size() == 4
+        assert count == 1
+        await server.close_all_connections()
+        client_loop.stop()
+
+    client_thread.join()
+    client_loop.close()
+    ws.close()
+    ws_thread.join()
+    server_loop.add_callback(server_loop.stop)
+    server_thread.join()
+    server_loop.close()