perspective-python 5.6.0__cp311-abi3-pyemscripten_2026_0_wasm32.whl

perspective/tests/widget/test_widget_pandas.py

@@ -0,0 +1,453 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ 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 pandas as pd
+import numpy as np
+import pytest
+from perspective.widget import PerspectiveWidget
+import perspective as psp
+
+client = psp.Server().new_local_client()
+Table = client.table
+
+
+pytest.skip(allow_module_level=True)
+
+
+class TestWidgetPandas:
+    def test_widget_load_table_df(self, superstore):
+        table = Table(superstore)
+        widget = PerspectiveWidget(table)
+        assert widget.table.schema() == {
+            "index": "integer",
+            "Country": "string",
+            "Region": "string",
+            "Category": "string",
+            "City": "string",
+            "Customer ID": "string",
+            "Discount": "float",
+            "Order Date": "date",
+            "Order ID": "string",
+            "Postal Code": "string",
+            "Product ID": "string",
+            "Profit": "float",
+            "Quantity": "integer",
+            "Row ID": "integer",
+            "Sales": "integer",
+            "Segment": "string",
+            "Ship Date": "date",
+            "Ship Mode": "string",
+            "State": "string",
+            "Sub-Category": "string",
+        }
+
+        assert sorted(widget.columns) == sorted(
+            [
+                "index",
+                "Category",
+                "City",
+                "Country",
+                "Customer ID",
+                "Discount",
+                "Order Date",
+                "Order ID",
+                "Postal Code",
+                "Product ID",
+                "Profit",
+                "Quantity",
+                "Region",
+                "Row ID",
+                "Sales",
+                "Segment",
+                "Ship Date",
+                "Ship Mode",
+                "State",
+                "Sub-Category",
+            ]
+        )
+        view = widget.table.view()
+        assert view.num_rows() == len(superstore)
+        assert view.num_columns() == len(superstore.columns) + 1  # index
+
+    def test_widget_load_data_df(self, superstore):
+        widget = PerspectiveWidget(superstore)
+        assert sorted(widget.columns) == sorted(
+            [
+                "index",
+                "Category",
+                "City",
+                "Country",
+                "Customer ID",
+                "Discount",
+                "Order Date",
+                "Order ID",
+                "Postal Code",
+                "Product ID",
+                "Profit",
+                "Quantity",
+                "Region",
+                "Row ID",
+                "Sales",
+                "Segment",
+                "Ship Date",
+                "Ship Mode",
+                "State",
+                "Sub-Category",
+            ]
+        )
+        view = widget.table.view()
+        assert view.num_rows() == len(superstore)
+        assert view.num_columns() == 20
+
+    def test_widget_load_series(self, superstore):
+        series = pd.Series(superstore["Profit"].values, name="profit")
+        widget = PerspectiveWidget(series)
+        assert widget.table.schema() == {"index": "integer", "profit": "float"}
+
+        assert sorted(widget.columns) == sorted(["index", "profit"])
+        view = widget.table.view()
+        assert view.num_rows() == len(superstore)
+        assert view.num_columns() == 2
+
+    def test_widget_load_pivot_table(self, superstore):
+        pivot_table = pd.pivot_table(
+            superstore,
+            values="Discount",
+            index=["Country", "Region"],
+            columns=["Category", "Segment"],
+        )
+        widget = PerspectiveWidget(pivot_table)
+        assert widget.group_by == ["Country", "Region"]
+        assert widget.split_by == ["Category", "Segment"]
+        assert widget.columns == ["value"]
+        # table should host flattened data
+        view = widget.table.view()
+        assert view.num_rows() == 60
+        assert view.num_columns() == 6
+
+    def test_widget_load_pivot_table_with_user_pivots(self, superstore):
+        pivot_table = pd.pivot_table(
+            superstore,
+            values="Discount",
+            index=["Country", "Region"],
+            columns="Category",
+        )
+        widget = PerspectiveWidget(pivot_table, group_by=["Category", "Segment"])
+        assert widget.group_by == ["Category", "Segment"]
+        assert widget.split_by == []
+        assert widget.columns == [
+            "index",
+            "Country",
+            "Region",
+            "Financials",
+            "Industrials",
+            "Technology",
+        ]
+        # table should host flattened data
+        view = widget.table.view()
+        assert view.num_rows() == 5
+        assert view.num_columns() == 6
+
+    def test_widget_load_group_by(self, superstore):
+        df_pivoted = superstore.set_index(["Country", "Region"])
+        widget = PerspectiveWidget(df_pivoted)
+        assert widget.group_by == ["Country", "Region"]
+        assert widget.split_by == []
+        assert sorted(widget.columns) == sorted(
+            [
+                "index",
+                "Category",
+                "Country",
+                "City",
+                "Customer ID",
+                "Discount",
+                "Order Date",
+                "Order ID",
+                "Postal Code",
+                "Product ID",
+                "Profit",
+                "Quantity",
+                "Region",
+                "Row ID",
+                "Sales",
+                "Segment",
+                "Ship Date",
+                "Ship Mode",
+                "State",
+                "Sub-Category",
+            ]
+        )
+        assert widget.table.size() == 100
+        view = widget.table.view()
+        assert view.num_rows() == len(superstore)
+        assert view.num_columns() == len(superstore.columns) + 1  # index
+
+    def test_widget_load_group_by_with_user_pivots(self, superstore):
+        df_pivoted = superstore.set_index(["Country", "Region"])
+        widget = PerspectiveWidget(df_pivoted, group_by=["Category", "Segment"])
+        assert widget.group_by == ["Category", "Segment"]
+        assert widget.split_by == []
+        assert sorted(widget.columns) == sorted(
+            [
+                "index",
+                "Category",
+                "Country",
+                "City",
+                "Customer ID",
+                "Discount",
+                "Order Date",
+                "Order ID",
+                "Postal Code",
+                "Product ID",
+                "Profit",
+                "Quantity",
+                "Region",
+                "Row ID",
+                "Sales",
+                "Segment",
+                "Ship Date",
+                "Ship Mode",
+                "State",
+                "Sub-Category",
+            ]
+        )
+        assert widget.table.size() == 100
+        view = widget.table.view()
+        assert view.num_rows() == len(superstore)
+        assert view.num_columns() == len(superstore.columns) + 1  # index
+
+    def test_widget_load_split_by(self, superstore):
+        arrays = [
+            np.array(
+                [
+                    "bar",
+                    "bar",
+                    "bar",
+                    "bar",
+                    "baz",
+                    "baz",
+                    "baz",
+                    "baz",
+                    "foo",
+                    "foo",
+                    "foo",
+                    "foo",
+                    "qux",
+                    "qux",
+                    "qux",
+                    "qux",
+                ]
+            ),
+            np.array(
+                [
+                    "one",
+                    "one",
+                    "two",
+                    "two",
+                    "one",
+                    "one",
+                    "two",
+                    "two",
+                    "one",
+                    "one",
+                    "two",
+                    "two",
+                    "one",
+                    "one",
+                    "two",
+                    "two",
+                ]
+            ),
+            np.array(
+                [
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                ]
+            ),
+        ]
+        tuples = list(zip(*arrays))
+        index = pd.MultiIndex.from_tuples(tuples, names=["first", "second", "third"])
+        df_both = pd.DataFrame(
+            np.random.randn(3, 16), index=["A", "B", "C"], columns=index
+        )
+        widget = PerspectiveWidget(df_both)
+        assert widget.columns == ["value"]
+        assert widget.split_by == ["first", "second", "third"]
+        assert widget.group_by == ["index"]
+
+    def test_widget_load_split_by_preserve_user_settings(self, superstore):
+        arrays = [
+            np.array(
+                [
+                    "bar",
+                    "bar",
+                    "bar",
+                    "bar",
+                    "baz",
+                    "baz",
+                    "baz",
+                    "baz",
+                    "foo",
+                    "foo",
+                    "foo",
+                    "foo",
+                    "qux",
+                    "qux",
+                    "qux",
+                    "qux",
+                ]
+            ),
+            np.array(
+                [
+                    "one",
+                    "one",
+                    "two",
+                    "two",
+                    "one",
+                    "one",
+                    "two",
+                    "two",
+                    "one",
+                    "one",
+                    "two",
+                    "two",
+                    "one",
+                    "one",
+                    "two",
+                    "two",
+                ]
+            ),
+            np.array(
+                [
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                    "X",
+                    "Y",
+                ]
+            ),
+        ]
+        tuples = list(zip(*arrays))
+        index = pd.MultiIndex.from_tuples(tuples, names=["first", "second", "third"])
+        df_both = pd.DataFrame(
+            np.random.randn(3, 16), index=["A", "B", "C"], columns=index
+        )
+        widget = PerspectiveWidget(df_both, columns=["first", "third"])
+        assert widget.columns == ["first", "third"]
+        assert widget.split_by == ["first", "second", "third"]
+        assert widget.group_by == ["index"]
+
+    def test_pivottable_values_index(self, superstore):
+        arrays = {
+            "A": [
+                "bar",
+                "bar",
+                "bar",
+                "bar",
+                "baz",
+                "baz",
+                "baz",
+                "baz",
+                "foo",
+                "foo",
+                "foo",
+                "foo",
+                "qux",
+                "qux",
+                "qux",
+                "qux",
+            ],
+            "B": [
+                "one",
+                "one",
+                "two",
+                "two",
+                "one",
+                "one",
+                "two",
+                "two",
+                "one",
+                "one",
+                "two",
+                "two",
+                "one",
+                "one",
+                "two",
+                "two",
+            ],
+            "C": [
+                "X",
+                "Y",
+                "X",
+                "Y",
+                "X",
+                "Y",
+                "X",
+                "Y",
+                "X",
+                "Y",
+                "X",
+                "Y",
+                "X",
+                "Y",
+                "X",
+                "Y",
+            ],
+            "D": np.arange(16),
+        }
+
+        df = pd.DataFrame(arrays)
+        df_pivot = df.pivot_table(
+            values=["D"], index=["A"], columns=["B", "C"], aggfunc={"D": "count"}
+        )
+        widget = PerspectiveWidget(df_pivot)
+        assert widget.columns == ["value"]
+        assert widget.split_by == ["B", "C"]
+        assert widget.group_by == ["A"]
+
+    def test_pivottable_multi_values(self, superstore):
+        pt = pd.pivot_table(
+            superstore,
+            values=["Discount", "Sales"],
+            index=["Country", "Region"],
+            aggfunc={"Discount": "count", "Sales": "sum"},
+            columns=["State", "Quantity"],
+        )
+        widget = PerspectiveWidget(pt)
+        assert widget.columns == ["Discount", "Sales"]
+        assert widget.split_by == ["State", "Quantity"]
+        assert widget.group_by == ["Country", "Region"]

perspective/virtual_servers/__init__.py

@@ -0,0 +1,206 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ 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). ┃
+#  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+
+class VirtualServerHandler:
+    """
+    An interface for implementing a Perspective `VirtualServer`. It operates
+    thusly:
+
+    -   A table is selected by name (validated via `get_hosted_tables`).
+
+    -   The UI will ask the model to create a temporary table with the results
+        of querying this table with a specific query `config`, a simple struct
+        which reflects the UI configurable fields (see `get_features`).
+
+    -   The UI will query slices of the temporary table as it needs them to
+        render. This may be a rectangular slice, a whole column or the entire
+        set, and it is returned from teh model via a custom push-only
+        struct `PerspectiveColumn` for now, though in the future we will support
+        e.g. Polars and other arrow-native formats directly.
+
+    -   The UI will delete its own temporary tables via `view_delete` but it is
+        ok for them to die intermittently, the UI will recover automatically.
+    """
+
+    def get_features(self):
+        """
+        [OPTIONAL] Toggle UI features through data model support. For example,
+        setting `"group_by": False` would hide the "Group By" UI control, as
+        well as prevent this field from appearing in `config` dicts later
+        provided to `table_make_view`.
+
+        This API defaults to just "columns", e.g. a simple flat datagrid in
+        which you can just scroll, select and format columns.
+
+        # Example
+
+        ```python
+        return {
+            "group_by": True,
+            "split_by": True,
+            "sort": True,
+            "expressions": True,
+            "filter_ops": {
+                "integer": ["==", "<"],
+            },
+            "aggregates": {
+                "string": ["count"],
+                "float": ["count", "sum"],
+            },
+        }
+        ```
+        """
+
+        pass
+
+    def get_hosted_tables(self) -> list[str]:
+        """
+        List of `Table` names available to query from.
+        """
+
+        pass
+
+    def table_schema(self, table_name):
+        """
+        Get the _Perspective Schema_ for a `Table`, a mapping of column name to
+        Perspective column types, a simplified set of six visually-relevant
+        types mapped from DuckDB's much richer type system. Optionally,
+        a model may also implement `view_schema` which describes temporary
+        tables, but for DuckDB this method is identical.
+        """
+
+        pass
+
+    def table_size(self, table_name):
+        """
+        Get a table's row count. Optionally, a model may also implement the
+        `view_size` method to get the row count for temporary tables, but for
+        DuckDB this method is identical.
+        """
+
+        pass
+
+    def view_schema(self, view_name, config):
+        return self.table_schema(view_name)
+
+    def view_size(self, view_name):
+        return self.table_size(view_name)
+
+    def table_make_view(self, table_name, view_name, config):
+        """
+        Create a temporary table `view_name` from the results of querying
+        `table_name` with a query configuration `config`.
+        """
+
+        pass
+
+    def table_describe(self, table_name, config):
+        """
+        Validate a complete query configuration `config` against `table_name`
+        and report the schema `table_make_view` would create, without creating
+        it.
+        """
+
+        pass
+
+    def view_delete(self, view_name):
+        """
+        Delete a temporary table. The UI will do this automatically, and it
+        can recover.
+        """
+
+        pass
+
+    def view_get_min_max(self, view_name, column_name, config):
+        """
+        [OPTIONAL] Get the min and max values of a column in a view.
+        Returns a tuple of (min, max) as native Python values.
+        """
+
+        pass
+
+    def view_get_data(self, view_name, config, viewport, data):
+        """
+        Serialize a rectangular slice `viewport` from temporary table
+        `view_name`, into the `PerspectiveColumn` serialization API injected
+        via `data`. The push-only `PerspectiveColumn` type can handle casting
+        Python types as input, but once a type is pushed to a column name it
+        must not be changed.
+        """
+
+        pass
+
+
+
+def describe_via_make_view(handler, table_name, config):
+    """A `table_describe` that builds a temporary table, reads its schema and
+    deletes it."""
+    view_name = f"__psp_describe_{id(config)}__"
+    try:
+        handler.table_make_view(table_name, view_name, config)
+    except Exception as e:
+        return {"config_error": str(e)}
+
+    try:
+        view_schema = handler.view_schema(view_name, config)
+    finally:
+        handler.view_delete(view_name)
+
+    expression_schema = {
+        name: view_schema[name]
+        for name in config.get("expressions", {})
+        if name in view_schema
+    }
+
+    return {"expression_schema": expression_schema, "view_schema": view_schema}
+
+
+def sql_table_describe(sql_builder, table_name, config, describe_query, schema=None):
+    """The `table_describe` flow shared by the SQL models."""
+    expression_schema = {}
+    query = sql_builder.expressions_describe(table_name, config)
+    if query is not None:
+        try:
+            expression_schema = describe_query(query)
+        except Exception as error:
+            expression_errors = {}
+            for name, expression in config.get("expressions", {}).items():
+                try:
+                    single = describe_query(
+                        sql_builder.expression_describe(table_name, expression)
+                    )
+                    expression_schema[name] = next(iter(single.values()))
+                except Exception as e:
+                    expression_errors[name] = {
+                        "error_message": str(e),
+                        "line": 0,
+                        "column": 0,
+                    }
+
+            if not expression_errors:
+                return {"config_error": str(error)}
+
+            return {
+                "expression_schema": expression_schema,
+                "expression_errors": expression_errors,
+            }
+
+    view_schema = {}
+    query = sql_builder.table_describe(table_name, config, schema)
+    if query is not None:
+        try:
+            view_schema = describe_query(query)
+        except Exception as error:
+            return {"config_error": str(error)}
+
+    return {"expression_schema": expression_schema, "view_schema": view_schema}