perspective-python 3.1.0__tar.gz → 3.1.2__tar.gz

{perspective_python-3.1.0 → perspective_python-3.1.2}/Cargo.lock

@@ -1783,7 +1783,7 @@ checksum = "e3148f5046208a5d56bcfc03053e3ca6334e51da8dfb19b6cdc8b306fae3283e"
 
 [[package]]
 name = "perspective"
-version = "3.1.0"
+version = "3.1.2"
 dependencies = [
  "async-lock",
  "axum",
@@ -1823,7 +1823,7 @@ dependencies = [
 
 [[package]]
 name = "perspective-client"
-version = "3.1.0"
+version = "3.1.2"
 dependencies = [
  "async-lock",
  "futures",
@@ -1845,7 +1845,7 @@ dependencies = [
 
 [[package]]
 name = "perspective-js"
-version = "3.1.0"
+version = "3.1.2"
 dependencies = [
  "anyhow",
  "base64 0.13.1",
@@ -1874,15 +1874,26 @@ dependencies = [
 
 [[package]]
 name = "perspective-lint"
-version = "3.1.0"
+version = "3.1.2"
 dependencies = [
  "glob",
  "yew-fmt",
 ]
 
+[[package]]
+name = "perspective-metadata"
+version = "0.0.0"
+dependencies = [
+ "perspective-client",
+ "perspective-js",
+ "perspective-server",
+ "perspective-viewer",
+ "ts-rs",
+]
+
 [[package]]
 name = "perspective-python"
-version = "3.1.0"
+version = "3.1.2"
 dependencies = [
  "async-lock",
  "cmake",
@@ -1902,7 +1913,7 @@ dependencies = [
 
 [[package]]
 name = "perspective-server"
-version = "3.1.0"
+version = "3.1.2"
 dependencies = [
  "async-lock",
  "base64 0.22.1",
@@ -1912,12 +1923,13 @@ dependencies = [
  "num_cpus",
  "perspective-client",
  "regex",
+ "shlex",
  "tracing",
 ]
 
 [[package]]
 name = "perspective-viewer"
-version = "3.1.0"
+version = "3.1.2"
 dependencies = [
  "anyhow",
  "async-lock",
@@ -2666,6 +2678,12 @@ dependencies = [
  "lazy_static",
 ]
 
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
 [[package]]
 name = "signal-hook-registry"
 version = "1.4.2"
@@ -3125,10 +3143,11 @@ dependencies = [
 
 [[package]]
 name = "ts-rs"
-version = "9.0.1"
+version = "10.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b44017f9f875786e543595076374b9ef7d13465a518dd93d6ccdbf5b432dde8c"
+checksum = "3a2f31991cee3dce1ca4f929a8a04fdd11fd8801aac0f2030b0fa8a0a3fef6b9"
 dependencies = [
+ "lazy_static",
  "serde_json",
  "thiserror",
  "ts-rs-macros",
@@ -3136,9 +3155,9 @@ dependencies = [
 
 [[package]]
 name = "ts-rs-macros"
-version = "9.0.1"
+version = "10.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c88cc88fd23b5a04528f3a8436024f20010a16ec18eb23c164b1242f65860130"
+checksum = "0ea0b99e8ec44abd6f94a18f28f7934437809dd062820797c52401298116f70e"
 dependencies = [
  "proc-macro2 1.0.83",
  "quote 1.0.36",

{perspective_python-3.1.0 → perspective_python-3.1.2}/Cargo.toml

@@ -12,6 +12,14 @@
 
 [workspace]
 resolver = "2"
+default-members = [
+    "rust/perspective",
+    "rust/perspective-client",
+    "rust/perspective-js",
+    "rust/perspective-python",
+    "rust/perspective-server",
+    "rust/perspective-viewer",
+]
 members = ["rust/perspective-python"]
 
 [profile.dev]

{perspective_python-3.1.0 → perspective_python-3.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: perspective-python
-Version: 3.1.0
+Version: 3.1.2
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython

{perspective_python-3.1.0/rust/perspective-python → perspective_python-3.1.2}/perspective/__init__.py

@@ -10,7 +10,7 @@
 #  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
 #  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
-__version__ = "3.1.0"
+__version__ = "3.1.2"
 __all__ = [
     "_jupyter_labextension_paths",
     "Server",

{perspective_python-3.1.0 → perspective_python-3.1.2}/rust/perspective-client/Cargo.toml

@@ -12,7 +12,7 @@
 
 [package]
 name = "perspective-client"
-version = "3.1.0"
+version = "3.1.2"
 authors = ["Andrew Stein <steinlink@gmail.com>"]
 edition = "2021"
 description = "A data visualization and analytics component, especially well-suited for large and/or streaming datasets."
@@ -35,8 +35,17 @@ rustdoc-args = ["--html-in-header", "docs/index.html"]
 
 [features]
 default = []
-external-proto = ["protobuf-src"]
-external-protoc = []
+
+# Should the project build the `proto.rs` via protoc from source or assume it
+# already exists?
+generate-proto = []
+# Should the project build protobuf from source? If not, building this crate
+# requires PROTOC be set in the environment
+protobuf-src = ["dep:protobuf-src"]
+
+# When generating metadata, we can't rely on its existence - so enable this
+# to skip metadata generation. This currently only affects docs.
+omit_metadata = []
 
 [lib]
 crate-type = ["rlib"]
@@ -66,5 +75,5 @@ default-features = false
 features = ["prost-derive", "std"]
 
 [dependencies.ts-rs]
-version = "9.0.1"
+version = "10.0.0"
 features = ["serde-json-impl", "no-serde-warnings"]

{perspective_python-3.1.0 → perspective_python-3.1.2}/rust/perspective-client/build.rs

@@ -24,7 +24,7 @@ fn prost_build() -> Result<()> {
     // 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.
-    if std::env::var("CARGO_FEATURE_EXTERNAL_PROTO").is_ok() {
+    if std::env::var("CARGO_FEATURE_GENERATE_PROTO").is_ok() {
         println!("cargo:warning=MESSAGE Building in development mode");
         let root_dir_env = std::env::var("PSP_ROOT_DIR").expect("Must set PSP_ROOT_DIR");
         let root_dir = Path::new(root_dir_env.as_str());
@@ -36,8 +36,19 @@ fn prost_build() -> Result<()> {
 
         println!("cargo:rerun-if-changed={}", proto_file.to_str().unwrap());
 
-        #[cfg(feature = "external-proto")]
+        // prost_build reads PROTOC from the environment.  When the `protobuf-src`
+        // feature is enabled, the build script sets PROTOC to the one built by
+        // that crate. When protobuf-src is disabled, builders must set PROTOC
+        // in the environment to a protocol buffer compiler.
+        #[cfg(feature = "protobuf-src")]
         std::env::set_var("PROTOC", protobuf_src::protoc());
+        #[cfg(not(feature = "protobuf-src"))]
+        if std::env::var("PROTOC").is_err() {
+            panic!(
+                "generate-proto is enabled and protobuf-src is disabled.  PROTOC must be set in \
+                 the environment to the path of a protocol buffer compiler"
+            )
+        }
 
         prost_build::Config::new()
             // .bytes(["ViewToArrowResp.arrow", "from_arrow"])

{perspective_python-3.1.0 → perspective_python-3.1.2}/rust/perspective-client/docs/client/set_loop_callback.md

@@ -3,5 +3,5 @@ which may be invoked by the Perspective runtime when updates occur. If provided
 a _loop callback_ function via [`Client::set_loop_callback`], such callback
 function invocations be passed to the _loop callback_ instead.
 
-[`Client::set_loop_callback`] can be used to control scheduling/conflation
-(e.g. by adding a delay), as well as executor integration.
+[`Client::set_loop_callback`] can be used to control scheduling/conflation (e.g.
+by adding a delay), as well as executor integration.

perspective_python-3.1.2/rust/perspective-client/docs/expressions.md

@@ -0,0 +1,141 @@
+Perspective supports _expression columns_, which are virtual columns calculated
+as part of the [`crate::View`], optionally using values from its underlying
+[`crate::Table`]'s columns. Such expression columns are defined in Perspective's
+expression language, an extended version of
+[ExprTK](https://github.com/ArashPartow/exprtk), which is itself quite similar
+(in design and features) to expressions in Excel.
+
+## UI
+
+Expression columns can be created in `<perspective-viewer>` by clicking the "New
+Column" button at the bottom of the column list, or via the API by adding the
+expression to the `expressions` config key when calling `viewer.restore()`.
+
+By default, such expression columns are not "used", and will appear above the
+`Table`'s other deselected columns in the column list, with an additional set of
+buttons for:
+
+-   _Editing_ the column's expression. Doing so will update the definitions of
+    _all_ usage of the expression column.
+-   _Deleting_ the column. Clicking `Reset` (or calling the `reset()` method)
+    will not delete expressions unless the `Shift` key is held (or `true`
+    parameter supplied, respectively). This button only appears if the
+    expression column i unused.
+
+To use the column, just drag/select the column as you would a normal column,
+e.g. as a "Filter", "Group By", etc. Expression columns will recalculate
+whenever their dependent columns update.
+
+## Perspective Extensions to ExprTK
+
+ExprTK has its own
+[excellent documentation](http://www.partow.net/programming/exprtk/) which
+covers the core langauge in depth, which is an excellent place to start in
+learning the basics. In addition to these features, Perspective adds a few of
+its own custom extensions and syntax.
+
+#### Static Typing
+
+In addition to `float` values which ExprTK supports natively, Perspective's
+expression language also supports Perspective's other types `date`, `datetime`,
+`integer`, `boolean`; as well as rudimentary type-checking, which will report an
+<span>error</span> when the values/columns supplied as arguments cannot be
+resolved to the expected type, e.g. `length(x)` expects an argument `x` of type
+`string` and is not a valid expression for an `x` of another type. Perspective
+supplies a set of _cast_ functions for converting between types where possible
+e.g. `string(x)` to cast a variable `x` to a `string`.
+
+#### Expression Column Name
+
+Expressions can be _named_ by providing a comment as the first line of the
+expression. This name will be used in the `<perspective-viewer>` UI when
+referring to the column, but will also be used in the API when specifying e.g.
+`group_by` or `sort` fields. When creating a new column via
+`<oerspective-viewer>`'s expression editor, new columns will get a default name
+(which you may delete or change):
+
+```html
+// New Column 1
+```
+
+Without such a comment, an expression will show up in the `<perspective-viewer>`
+API and UI as itself (clipped to a reasonable length for the latter).
+
+#### Referencing [`crate::Table`] Columns
+
+Columns from the [`crate::Table`] can be referenced in an expression with
+_double quotes_.
+
+```text
+// Expected Sales ("Sales" * 10) + "Profit"
+```
+
+#### String Literals
+
+In contrast to standard ExprTK, string literals are declared with _single
+quotes_:
+
+```text
+// Profitable
+if ("Profit" > 0) {
+  'Stonks'
+} else {
+  'Not Stonks'
+}
+```
+
+#### Extended Library
+
+Perspective adds many of its own functions in addition to `ExprTK`'s standard
+ones, including common functions for `datetime` and `string` types such as
+`substring()`, `bucket()`, `day_of_week()`, etc. A full list of available
+functions is available in the
+[Expression Columns API](../obj/perspective-viewer-exprtk).
+
+## Examples
+
+#### Casting
+
+Just `2`, as an `integer` (numeric literals currently default to `float` unless
+cast).
+
+```text
+integer(2)
+```
+
+#### Variables
+
+```text
+// My Column Name
+var incrementedBy200 := "Sales" + 200;
+var half := incrementedBy200 / 2;
+half
+```
+
+```text
+// Complex Expression
+var upperCustomer := upper("Customer Name");
+var separator := concat(upperCustomer, ' | ');
+var profitRatio := floor(percent_of("Profit", "Sales")); // Remove trailing decimal.
+var combined := concat(separator, string(profitRatio));
+var percentDisplay := concat(combined, '%');
+percentDisplay
+```
+
+#### Conditionals
+
+```text
+// Conditional
+var priceAdjustmentDate := date(2016, 6, 18);
+var finalPrice := "Sales" - "Discount";
+var additionalModifier := 0;
+
+if("Order Date" > priceAdjustmentDate) {
+  finalPrice -= 5;
+  additionalModifier -= 2;
+}
+else
+  finalPrice += 5;
+
+finalPrice + additionalModifier
+```

{perspective_python-3.1.0 → perspective_python-3.1.2}/rust/perspective-client/docs/table/remove_delete.md

@@ -1 +1,2 @@
-Removes a listener with a given ID, as returned by a previous call to [`Table::on_delete`].
+Removes a listener with a given ID, as returned by a previous call to
+[`Table::on_delete`].

perspective_python-3.1.2/rust/perspective-client/docs/table.md

@@ -0,0 +1,281 @@
+[`Table`] is Perspective's columnar data frame, analogous to a Pandas
+`DataFrame` or Apache Arrow, supporting append & in-place updates, removal by
+index, and update notifications.
+
+A [`Table`] contains columns, each of which have a unique name, are strongly and
+consistently typed, and contains rows of data conforming to the column's type.
+Each column in a [`Table`] must have the same number of rows, though not every
+row must contain data; null-values are used to indicate missing values in the
+dataset.
+
+The schema of a [`Table`] is _immutable after creation_, which means the column
+names and data types cannot be changed after the [`Table`] has been created.
+Columns cannot be added or deleted after creation either, but a [`View`] can be
+used to select an arbitrary set of columns from the [`Table`].
+
+<div class="javascript">
+<div class="warning">
+The examples in this module are in JavaScript. See <a href="https://docs.rs/crate/perspective/latest"><code>perspective</code></a> docs for the Rust API.
+</div>
+</div>
+<div class="python">
+<div class="warning">
+The examples in this module are in Python. See <a href="https://docs.rs/crate/perspective/latest"><code>perspective</code></a> docs for the Rust API.
+</div>
+</div>
+
+## Schema and Types
+
+The mapping of a `Table`'s column names to data types is referred to as a
+`schema`. Each column has a unique name and a single data type:
+
+<div class="javascript">
+
+```javascript
+var schema = {
+    x: "integer",
+    y: "string",
+    z: "boolean",
+};
+
+const table2 = await worker.table(schema);
+```
+
+</div>
+<div class="python">
+
+```python
+from datetime import date, datetime
+
+schema = {
+    "x": "integer",
+    "y": "string",
+    "z": "boolean",
+}
+
+table2 = perspective.Table(schema)
+```
+
+</div>
+<div class="rust">
+
+```rust
+let data = TableData::Schema(vec![(" a".to_string(), ColumnType::FLOAT)]);
+let options = TableInitOptions::default();
+let table = client.table(data.into(), options).await?;
+```
+
+</div>
+
+When passing data directly to the [`crate::Client::table`] constructor, the type
+of each column is inferred automatically. In some cases, the inference algorithm
+may not return exactly what you'd like. For example, a column may be interpreted
+as a `datetime` when you intended it to be a `string`, or a column may have no
+values at all (yet), as it will be updated with values from a real-time data
+source later on. In these cases, create a `table()` with a _schema_.
+
+Once the [`Table`] has been created with a schema, further `update()` calls will
+no longer perform type inference, so columns must only include values supported
+by the column's [`ColumnType`].
+
+## Data Formats
+
+A [`Table`] may also be created-or-updated by data in CSV,
+[Apache Arrow](https://arrow.apache.org/), JSON row-oriented or JSON
+column-oriented formats.
+
+<div class="python">
+
+In addition to these core formats, `perspective-python` additionally supports
+`pyarrow.Table` and `pandas.DataFrame` objects directly. These formats are
+otherwise identical to the built-in formats and don't exhibit any additional
+support or type-awareness; e.g., `pandas.DataFrame` support is _just_
+`pyarrow.Table.from_pandas` piped into Perspective's Arrow reader.
+
+</div>
+
+[`crate::Client::table`] and [`Table::update`] perform _coercion_ on their input
+for all input formats _except_ Arrow (which comes with its own schema and has no
+need for coercion).
+
+`"date"` and `"datetime"` column types do not have native JSON representations,
+so these column types _cannot_ be inferred from JSON input. Instead, for columns
+of these types for JSON input, a [`Table`] must first be constructed with a
+_schema_. Next, call [`Table::update`] with the JSON input - Perspective's JSON
+reader may _coerce_ a `date` or `datetime` from these native JSON types:
+
+-   `integer` as milliseconds-since-epoch.
+-   `string` as a any of Perspective's built-in date format formats.
+-   JavaScript `Date` and Python `datetime.date` and `datetime.datetime` are
+    _not_ supported directly. However, in JavaScript `Date` types are
+    automatically coerced to correct `integer` timestamps by default when
+    converted to JSON.
+
+For CSV input types, Perspective relies on Apache Arrow's CSV parser, and as
+such uses the same column-type inference logic as Arrow itself.
+
+## Index and Limit
+
+Initializing a [`Table`] with an `index` tells Perspective to treat a column as
+the primary key, allowing in-place updates of rows. Only a single column (of any
+type) can be used as an `index`. Indexed [`Table`] instances allow:
+
+-   In-place _updates_ whenever a new row shares an `index` values with an
+    existing row
+-   _Partial updates_ when a data batch omits some column.
+-   _Removes_ to delete a row by `index`.
+
+To create an indexed `Table`, provide the `index` property with a string column
+name to be used as an index:
+
+<div class="javascript">
+
+```javascript
+const indexed_table = await perspective.table(data, { index: "a" });
+```
+
+</div>
+<div class="javascript">
+
+```python
+indexed_table = perspective.Table(data, index="a");
+```
+
+</div>
+
+Initializing a [`Table`] with a `limit` sets the total number of rows the
+[`Table`] is allowed to have. When the [`Table`] is updated, and the resulting
+size of the [`Table`] would exceed its `limit`, rows that exceed `limit`
+overwrite the oldest rows in the [`Table`]. To create a [`Table`] with a
+`limit`, provide the `limit` property with an integer indicating the maximum
+rows:
+
+<div class="javascript">
+
+```javascript
+const limit_table = await perspective.table(data, { limit: 1000 });
+```
+
+</div>
+<div class="python">
+
+```python
+limit_table = perspective.Table(data, limit=1000);
+```
+
+</div>
+
+## [`Table::update`] and [`Table::remove`]
+
+Once a [`Table`] has been created, it can be updated with new data conforming to
+the [`Table`]'s schema. [`Table::update`] supports the same data formats as
+[`crate::Client::table`], minus _schema_.
+
+<div class="javascript">
+
+```javascript
+const schema = {
+    a: "integer",
+    b: "float",
+};
+
+const table = await perspective.table(schema);
+table.update(new_data);
+```
+
+</div>
+<div class="python">
+
+```python
+schema = {"a": "integer", "b": "float"}
+
+table = perspective.Table(schema)
+table.update(new_data)
+```
+
+</div>
+
+Without an `index` set, calls to `update()` _append_ new data to the end of the
+`Table`. Otherwise, Perspective allows
+[_partial updates_ (in-place)](#index-and-limit) using the `index` to determine
+which rows to update:
+
+<div class="javascript">
+
+```javascript
+indexed_table.update({ id: [1, 4], name: ["x", "y"] });
+```
+
+</div>
+<div class="python">
+
+```python
+indexed_table.update({"id": [1, 4], "name": ["x", "y"]})
+```
+
+</div>
+
+Any value on a [`Client::table`] can be unset using the value `null` in JSON or
+Arrow input formats. Values may be unset on construction, as any `null` in the
+dataset will be treated as an unset value. [`Table::update`] calls do not need
+to provide _all columns_ in the [`Table`]'s schema; missing columns will be
+omitted from the [`Table`]'s updated rows.
+
+<div class="javascript">
+
+```javascript
+table.update([{ x: 3, y: null }]); // `z` missing
+```
+
+</div>
+<div class="python">
+
+```python
+table.update([{"x": 3, "y": None}]) // `z` missing
+```
+
+</div>
+
+Rows can also be removed from an indexed [`Table`], by calling [`Table::remove`]
+with an array of index values:
+
+<div class="javascript">
+
+```javascript
+indexed_table.remove([1, 4]);
+```
+
+</div>
+<div class="python">
+
+```python
+indexed_table.remove([1, 4])
+```
+
+</div>
+
+# [`Table::clear`] and [`Table::replace`]
+
+Calling [`Table::clear`] will remove all data from the underlying [`Table`].
+Calling [`Table::replace`] with new data will clear the [`Table`], and update it
+with a new dataset that conforms to Perspective's data types and the existing
+schema on the `Table`.
+
+<div class="javascript">
+
+```javascript
+table.clear();
+table.replace(json);
+```
+
+</div>
+<div class="python">
+
+```python
+table.clear()
+table.replace(df)
+```
+
+</div>
+
+<div class="warning">`limit` cannot be used in conjunction with `index`.</div>

{perspective_python-3.1.0 → perspective_python-3.1.2}/rust/perspective-client/docs/view/column_paths.md

@@ -1,3 +1,5 @@
-Returns an array of strings containing the column paths of the View without any of the source columns.
+Returns an array of strings containing the column paths of the View without any
+of the source columns.
 
-A column path shows the columns that a given cell belongs to after pivots are applied.
+A column path shows the columns that a given cell belongs to after pivots are
+applied.

perspective_python-3.1.2/rust/perspective-client/docs/view/delete.md

@@ -0,0 +1,3 @@
+Delete this [`View`] and clean up all resources associated with it. View objects
+do not stop consuming resources or processing updates when they are garbage
+collected - you must call this method to reclaim these.