chore: import upstream snapshot with attribution

2026-07-13 12:25:07 +08:00
commit a26e856398
1681 changed files with 296950 additions and 0 deletions
@@ -0,0 +1,142 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ 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_validate_expression(self, view_name, expression):
+        """
+        [OPTIONAL] Given a temporary table `view_name`, validate the type of
+        a column expression string `expression`, or raise an error if the
+        expression is invalid. This is enabeld by `"expressions"` via
+        `get_features` and defaults to allow all expressions.
+        """
+
+        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