vgplot 0.1.0__tar.gz → 0.29.1__tar.gz

{vgplot-0.1.0 → vgplot-0.29.1}/.gitignore

@@ -27,12 +27,7 @@ venv/
 conda-env/
 
 # Python cache
-__pycache__/
 *.pyc
 
-# Test cache
-.pytest_cache/
-.coverage
-
-# Python API Generated classes
-packages/vgplot-python/schema_wrapper/generated_classes.py
+.pnpm-store
+dev/notebooks/__marimo__

vgplot-0.29.1/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to the vgplot Python API
+
+Most of the API — every **mark**, **plot attribute**, and **encoding
+transform** (aggregates, window functions, column transforms) — is generated
+from the Mosaic JSON schema, which is itself generated from the JavaScript
+spec ([`Spec.ts`]). The JS API is the source of truth.
+
+Hand-written (not generated): the runtime core (`plot.py`, `spec.py`), data
+sources (`data.py`), params (`params.py`), the shared value types
+(`_types.py`), the `sql()` / `channels()` helpers (`encodings.py`), and the
+interactor / input / legend helpers.
+
+[`Spec.ts`]: ../../../packages/vgplot/spec/src/spec/Spec.ts
+
+## Regenerating the API
+
+After any change to the vgplot spec types (or the generator), regenerate:
+
+```sh
+pnpm run generate:python-api
+```
+
+This rebuilds the schema, runs [`bin/generate-python-api.js`], and formats the
+output into [`vgplot/_generated/`]. Commit the regenerated files.
+
+CI fails if the committed [`vgplot/_generated/`] output does not match a fresh
+regeneration, so the generated code always matches the schema.
+
+[`bin/generate-python-api.js`]: ../../../bin/generate-python-api.js
+[`vgplot/_generated/`]: ./vgplot/_generated/__init__.py
+
+## Adding a new mark, attribute, or transform
+
+Add it on the JS side ([`Spec.ts`]), then run `pnpm run generate:python-api`.
+Nothing in the Python package needs hand-editing — there is no dynamic
+fallback, so a name that is missing from the generated API raises
+`AttributeError` (and is flagged by type checkers) rather than silently
+appearing.
+
+## Tests
+
+```sh
+cd packages/vgplot/vgplot-python
+uv run --group dev pytest      # round-trip + API + schema-coverage tests
+uv run --group dev ty check
+```

vgplot-0.29.1/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: vgplot
+Version: 0.29.1
+Summary: A Python API for authoring Mosaic vgplot visualizations
+Project-URL: homepage, https://github.com/uwdata/mosaic
+Requires-Python: >=3.10
+Requires-Dist: narwhals>=2.8.0
+Description-Content-Type: text/markdown
+
+# vgplot
+
+[![PyPI](https://img.shields.io/pypi/v/vgplot.svg)](https://pypi.org/project/vgplot/)
+
+A Python API for authoring [Mosaic](https://uwdata.github.io/mosaic/) visualizations. Build declarative, interactive plots backed by DuckDB — in notebooks, as JSON specs, or as part of a data pipeline.
+
+`vgplot` produces Mosaic `View` objects that can be rendered with [`mosaic-widget`](https://pypi.org/project/mosaic-widget/) or exported to JSON for use in a browser. Data sources and parameters defined as local variables are automatically discovered at render time.
+
+## Installation
+
+```bash
+pip install vgplot
+```
+
+To render visualizations in the widget, install the widget:
+
+```bash
+pip install mosaic-widget
+```
+
+## Usage
+
+### File-based data
+
+Load data from a file using `vg.parquet()`, `vg.csv()`, or `vg.table()`, pass it directly to a mark, then call `view.show()` or `view`:
+
+```python
+import vgplot as vg
+
+athletes = vg.parquet("data/athletes.parquet")
+
+view = vg.plot(
+    vg.dot(athletes, x="weight", y="height", fill="sex", opacity=0.5),
+    vg.width(600),
+    vg.height(400),
+)
+
+view
+```
+
+### Interactive selections
+
+Params and selections are first-class objects. Declare them before the view so they can be referenced by multiple marks or interactors:
+
+```python
+import vgplot as vg
+
+flights = vg.parquet("data/flights-200k.parquet")
+brush = vg.selection.crossfilter()
+
+view = vg.vconcat(
+    vg.plot(
+        vg.rect_y(flights, x=vg.bin("delay"), y=vg.count(),
+                  filter_by=brush, fill="steelblue",
+                  inset_left=0.5, inset_right=0.5),
+        vg.interval_x(bind=brush),
+        vg.x_domain("Fixed"),
+        vg.x_label("Arrival Delay (min)"),
+        vg.height(200),
+    ),
+    vg.plot(
+        vg.rect_y(flights, x=vg.bin("time"), y=vg.count(),
+                  filter_by=brush, fill="steelblue",
+                  inset_left=0.5, inset_right=0.5),
+        vg.interval_x(bind=brush),
+        vg.x_domain("Fixed"),
+        vg.x_label("Departure Time (hour)"),
+        vg.height(200),
+    ),
+)
+
+view
+```
+
+### Scalar params and input widgets
+
+Use `vg.param()` for scalar parameters bound to input controls:
+
+```python
+import vgplot as vg
+
+walk = vg.parquet("data/random-walk.parquet")
+bias = vg.param(0)
+
+view = vg.vconcat(
+    vg.slider(label="Bias", bind=bias, min=0, max=1000, step=1),
+    vg.plot(
+        vg.area_y(walk, x="t", y=vg.sql("v + $bias")),
+        vg.width(680),
+        vg.height(200),
+    ),
+)
+
+view
+```
+
+## Key concepts
+
+| Concept | Python API |
+|---|---|
+| File-based data | `vg.parquet(path)`, `vg.csv(path)`, `vg.spatial(path)`, `vg.table(query)` |
+| Mark | `vg.dot(...)`, `vg.bar_y(...)`, `vg.area_y(...)`, `vg.line_y(...)`, … |
+| Aggregation / transform | `vg.count()`, `vg.bin("col")`, `vg.avg("col")`, `vg.sum("col")`, … |
+| SQL expression | `vg.sql("expr")` — use `$param` to interpolate a param, e.g. `vg.sql("v + $bias")` |
+| Plot attributes | `vg.width(n)`, `vg.height(n)`, `vg.x_label("…")`, `vg.color_scheme("…")`, … |
+| Interactor | `vg.interval_x(...)`, `vg.interval_xy(...)`, `vg.region(...)`, `vg.highlight(...)`, … |
+| Layout | `vg.vconcat(...)`, `vg.hconcat(...)`, `vg.vspace(n)`, `vg.hspace(n)` |
+| Crossfilter selection | `vg.selection.crossfilter()` |
+| Intersect / union selection | `vg.selection.intersect()`, `vg.selection.union()` |
+| Scalar param | `vg.param(value)` |
+| Input widgets | `vg.slider(...)`, `vg.menu(...)`, `vg.select(...)`, `vg.checkbox(...)` |
+| Named data reference | `vg.source("table_name")` |
+| Render | `view.show()` or `view` as last cell expression in notebooks |
+
+Option names match the [vgplot API reference](https://uwdata.github.io/mosaic/api/), but in snake_case. For example, `xDomain` → `x_domain`, `colorScheme` → `color_scheme`, `filterBy` → `filter_by`.
+
+Any mark or directive not listed above is also accessible by its snake_case name — `vg.regression_y(...)` and `vg.x_tick_rotate(45)` work without explicit exports.
+
+## Exporting specs
+
+`view.to_dict()` returns a plain Python dictionary. `view.to_json()` returns a JSON string:
+
+```python
+from pprint import pprint
+
+pprint(view.to_dict())
+print(view.to_json(indent=2))
+```

vgplot-0.29.1/README.md

@@ -0,0 +1,128 @@
+# vgplot
+
+[![PyPI](https://img.shields.io/pypi/v/vgplot.svg)](https://pypi.org/project/vgplot/)
+
+A Python API for authoring [Mosaic](https://uwdata.github.io/mosaic/) visualizations. Build declarative, interactive plots backed by DuckDB — in notebooks, as JSON specs, or as part of a data pipeline.
+
+`vgplot` produces Mosaic `View` objects that can be rendered with [`mosaic-widget`](https://pypi.org/project/mosaic-widget/) or exported to JSON for use in a browser. Data sources and parameters defined as local variables are automatically discovered at render time.
+
+## Installation
+
+```bash
+pip install vgplot
+```
+
+To render visualizations in the widget, install the widget:
+
+```bash
+pip install mosaic-widget
+```
+
+## Usage
+
+### File-based data
+
+Load data from a file using `vg.parquet()`, `vg.csv()`, or `vg.table()`, pass it directly to a mark, then call `view.show()` or `view`:
+
+```python
+import vgplot as vg
+
+athletes = vg.parquet("data/athletes.parquet")
+
+view = vg.plot(
+    vg.dot(athletes, x="weight", y="height", fill="sex", opacity=0.5),
+    vg.width(600),
+    vg.height(400),
+)
+
+view
+```
+
+### Interactive selections
+
+Params and selections are first-class objects. Declare them before the view so they can be referenced by multiple marks or interactors:
+
+```python
+import vgplot as vg
+
+flights = vg.parquet("data/flights-200k.parquet")
+brush = vg.selection.crossfilter()
+
+view = vg.vconcat(
+    vg.plot(
+        vg.rect_y(flights, x=vg.bin("delay"), y=vg.count(),
+                  filter_by=brush, fill="steelblue",
+                  inset_left=0.5, inset_right=0.5),
+        vg.interval_x(bind=brush),
+        vg.x_domain("Fixed"),
+        vg.x_label("Arrival Delay (min)"),
+        vg.height(200),
+    ),
+    vg.plot(
+        vg.rect_y(flights, x=vg.bin("time"), y=vg.count(),
+                  filter_by=brush, fill="steelblue",
+                  inset_left=0.5, inset_right=0.5),
+        vg.interval_x(bind=brush),
+        vg.x_domain("Fixed"),
+        vg.x_label("Departure Time (hour)"),
+        vg.height(200),
+    ),
+)
+
+view
+```
+
+### Scalar params and input widgets
+
+Use `vg.param()` for scalar parameters bound to input controls:
+
+```python
+import vgplot as vg
+
+walk = vg.parquet("data/random-walk.parquet")
+bias = vg.param(0)
+
+view = vg.vconcat(
+    vg.slider(label="Bias", bind=bias, min=0, max=1000, step=1),
+    vg.plot(
+        vg.area_y(walk, x="t", y=vg.sql("v + $bias")),
+        vg.width(680),
+        vg.height(200),
+    ),
+)
+
+view
+```
+
+## Key concepts
+
+| Concept | Python API |
+|---|---|
+| File-based data | `vg.parquet(path)`, `vg.csv(path)`, `vg.spatial(path)`, `vg.table(query)` |
+| Mark | `vg.dot(...)`, `vg.bar_y(...)`, `vg.area_y(...)`, `vg.line_y(...)`, … |
+| Aggregation / transform | `vg.count()`, `vg.bin("col")`, `vg.avg("col")`, `vg.sum("col")`, … |
+| SQL expression | `vg.sql("expr")` — use `$param` to interpolate a param, e.g. `vg.sql("v + $bias")` |
+| Plot attributes | `vg.width(n)`, `vg.height(n)`, `vg.x_label("…")`, `vg.color_scheme("…")`, … |
+| Interactor | `vg.interval_x(...)`, `vg.interval_xy(...)`, `vg.region(...)`, `vg.highlight(...)`, … |
+| Layout | `vg.vconcat(...)`, `vg.hconcat(...)`, `vg.vspace(n)`, `vg.hspace(n)` |
+| Crossfilter selection | `vg.selection.crossfilter()` |
+| Intersect / union selection | `vg.selection.intersect()`, `vg.selection.union()` |
+| Scalar param | `vg.param(value)` |
+| Input widgets | `vg.slider(...)`, `vg.menu(...)`, `vg.select(...)`, `vg.checkbox(...)` |
+| Named data reference | `vg.source("table_name")` |
+| Render | `view.show()` or `view` as last cell expression in notebooks |
+
+Option names match the [vgplot API reference](https://uwdata.github.io/mosaic/api/), but in snake_case. For example, `xDomain` → `x_domain`, `colorScheme` → `color_scheme`, `filterBy` → `filter_by`.
+
+Any mark or directive not listed above is also accessible by its snake_case name — `vg.regression_y(...)` and `vg.x_tick_rotate(45)` work without explicit exports.
+
+## Exporting specs
+
+`view.to_dict()` returns a plain Python dictionary. `view.to_json()` returns a JSON string:
+
+```python
+from pprint import pprint
+
+pprint(view.to_dict())
+print(view.to_json(indent=2))
+```

vgplot-0.29.1/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "vgplot-python",
+  "version": "0.29.1",
+  "private": true,
+  "scripts": {
+    "prerelease": "uv run ruff check && uv run ruff format --check",
+    "release": "uv build && uvx twine upload --skip-existing ../../../dist/vgplot*"
+  }
+}

vgplot-0.29.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "vgplot"
+dynamic = ["version"]
+description = "A Python API for authoring Mosaic vgplot visualizations"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["narwhals>=2.8.0"]
+
+[project.urls]
+homepage = "https://github.com/uwdata/mosaic"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "mosaic-widget",
+    "pytest",
+    "pytest-cov",
+    "ruff",
+    "ty",
+]
+
+[tool.uv.sources]
+"mosaic-widget" = { workspace = true }
+
+[tool.hatch.version]
+path = "package.json"
+pattern = "\"version\": \"(?P<version>.+?)\""
+
+[tool.hatch.build.targets.wheel]
+packages = ["vgplot"]
+
+[tool.pyright]
+ignore = ["../**/.venv/"]  # Do not display diagnostics in external source code
+typeCheckingMode = "standard"

vgplot-0.29.1/test/test_full_round_trip.py

@@ -0,0 +1,74 @@
+# Tests that every generated Python spec (specs/python/*.py) round-trips
+# correctly: running the file produces JSON identical to the reference fixture
+# in specs/json/. Also checks that Python, JSON, and ESM example sets stay
+# in sync (same filenames).
+#
+# Run: pytest packages/vgplot/vgplot-python/test/test_full_round_trip.py
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[4]  # mosaic project root
+SPEC_DIR = ROOT / "specs"
+JSON_DIR = SPEC_DIR / "json"
+ESM_DIR = SPEC_DIR / "esm"
+PYTHON_DIR = SPEC_DIR / "python"
+
+VGPLOT_PKG = ROOT / "packages" / "vgplot" / "vgplot-python"
+
+for p in (VGPLOT_PKG, ROOT):
+    if str(p) not in sys.path:
+        sys.path.insert(0, str(p))
+
+
+def load_json_fixture(name: str) -> dict:
+    return json.loads((JSON_DIR / f"{name}.json").read_text(encoding="utf-8"))
+
+
+def run_spec_file_with_exec(path: Path) -> dict:
+    namespace: dict[str, Any] = {
+        "__name__": "__spec_exec__",
+        "__file__": str(path),
+        "__builtins__": __builtins__,
+    }
+    code = compile(path.read_text(encoding="utf-8"), str(path), "exec")
+    exec(code, namespace)
+
+    view = namespace.get("view")
+    if view is None:
+        raise AssertionError(f"`{path.name}` must define a top-level `view` variable")
+    if not hasattr(view, "to_dict"):
+        raise AssertionError(f"`view` in `{path.name}` does not expose to_dict()")
+    # Execute to_dict() within the spec namespace so frame inspection finds the right variables
+    namespace["__view__"] = view
+    exec("__result__ = __view__.to_dict()", namespace)
+    return namespace["__result__"]
+
+
+JSON_EXAMPLES = sorted(path.stem for path in JSON_DIR.glob("*.json"))
+ESM_EXAMPLES = sorted(path.stem for path in ESM_DIR.glob("*.js"))
+PYTHON_EXAMPLES = sorted(path.stem for path in PYTHON_DIR.glob("*.py"))
+
+
+def test_generated_examples_stay_in_sync():
+    assert PYTHON_EXAMPLES == JSON_EXAMPLES
+    assert ESM_EXAMPLES == JSON_EXAMPLES
+
+
+@pytest.mark.parametrize("example_name", PYTHON_EXAMPLES)
+def test_python_round_trip(example_name: str):
+    generated = run_spec_file_with_exec(PYTHON_DIR / f"{example_name}.py")
+    original = load_json_fixture(example_name)
+
+    # meta is documentation-only and not emitted by the Python DSL
+    original.pop("meta", None)
+    generated.pop("meta", None)
+
+    assert generated == original, (
+        f"Round-trip Python mismatch for '{example_name}'.\n"
+        f"> original:  {original}\n"
+        f"> generated: {generated}"
+    )

vgplot-0.29.1/test/test_python_api.py

@@ -0,0 +1,110 @@
+# Unit tests for the vgplot Python API, covering behaviors that the
+# generated-spec round-trip suite does not exercise directly.
+import sys
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[4]
+VGPLOT_PKG = ROOT / "packages" / "vgplot" / "vgplot-python"
+for p in (VGPLOT_PKG, ROOT):
+    if str(p) not in sys.path:
+        sys.path.insert(0, str(p))
+
+import vgplot as vg  # noqa: E402
+from vgplot.plot import Mark  # noqa: E402
+
+
+class TestGeneratedMarks:
+    """Marks are generated from the schema; there is no dynamic fallback, so
+    unknown names fail loudly rather than being silently fabricated."""
+
+    def test_positional_data_with_encodings_is_kept(self):
+        # A leading positional arg is the data source even when the call also
+        # has keyword encodings.
+        mark = vg.waffle_y("athletes", x="a", y={"count": ""})
+        assert isinstance(mark, Mark)
+        d = mark.to_dict()
+        assert d["mark"] == "waffleY"
+        assert d["data"] == {"from": "athletes"}
+        assert d["x"] == "a"
+
+    def test_explicit_none_channel_is_preserved(self):
+        # Passing a channel explicitly as None keeps it in the output (distinct
+        # from not passing it at all).
+        assert vg.line_y("t", x="a", z=None).to_dict()["z"] is None
+        assert "z" not in vg.line_y("t", x="a").to_dict()
+
+    def test_unknown_name_raises(self):
+        # No __getattr__ fallback: a missing or mis-typed API name is an error.
+        with pytest.raises(AttributeError):
+            vg.some_custom_mark  # pyright: ignore[reportAttributeAccessIssue] # ty: ignore[unresolved-attribute]
+        with pytest.raises(AttributeError):
+            vg.definitely_not_a_real_directive  # pyright: ignore[reportAttributeAccessIssue] # ty: ignore[unresolved-attribute]
+
+
+class TestDataHelpers:
+    def test_json_inline_data(self):
+        d = vg.json([{"a": 1}, {"a": 2}])
+        assert d.to_dict() == {"type": "json", "data": [{"a": 1}, {"a": 2}]}
+
+    def test_json_file(self):
+        assert vg.json(file="x.json").to_dict() == {"type": "json", "file": "x.json"}
+
+
+class TestParams:
+    def test_date_param(self):
+        from datetime import date
+
+        assert vg.param(date(2013, 5, 13)).param_def() == {"date": "2013-05-13"}
+
+    def test_datetime_param(self):
+        from datetime import datetime
+
+        assert vg.param(datetime(2013, 5, 13, 10, 30)).param_def() == {
+            "date": "2013-05-13T10:30:00"
+        }
+
+
+class TestAutoNaming:
+    def test_auto_param_name_skips_explicit_name(self):
+        from vgplot.spec import Spec
+
+        named = vg.param(1)
+        unnamed = vg.param(2)
+        view = vg.plot(vg.dot("t", x=unnamed))
+        # The explicit param already occupies "_param0"; the in-view param must
+        # not collide with it.
+        d = Spec(params={"_param0": named}, view=view).to_dict()
+        assert d["params"]["_param0"] == 1
+        assert d["params"]["_param1"] == 2
+        assert d["plot"][0]["x"] == "$_param1"
+
+
+class TestDataFrames:
+    """A DataFrame passed directly to a mark is discovered by variable name,
+    referenced as a table, and carried in the spec's data section for the host
+    (e.g. the widget) to register."""
+
+    def test_frame_is_referenced_and_named_after_variable(self):
+        import pyarrow as pa
+
+        weather = pa.table({"a": [1, 2, 3]})
+        view = vg.plot(vg.dot(weather, x="a"))
+        d = view.to_dict()
+
+        assert d["plot"][0]["data"] == {"from": "weather"}
+        assert d["data"]["weather"] is weather
+
+    def test_frame_and_datadef_share_the_data_section(self):
+        import pyarrow as pa
+
+        weather = pa.table({"a": [1]})
+        athletes = vg.csv("athletes.csv")
+        view = vg.plot(vg.dot(weather, x="a"), vg.dot(athletes, x="a"))
+        d = view.to_dict()
+
+        assert d["plot"][0]["data"] == {"from": "weather"}
+        assert d["plot"][1]["data"] == {"from": "athletes"}
+        assert d["data"]["weather"] is weather
+        assert d["data"]["athletes"] == {"type": "csv", "file": "athletes.csv"}

vgplot-0.29.1/test/test_schema_coverage.py

@@ -0,0 +1,61 @@
+# Ensures the exported vgplot API covers every mark, attribute, interactor, and
+# input in the Mosaic JSON schema (the source of truth). Marks and attributes
+# are generated; interactors and inputs are hand-written. This guards against a
+# schema addition that was never generated or hand-added.
+import json
+import re
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[4]
+for p in (ROOT / "packages" / "vgplot" / "vgplot-python", ROOT):
+    if str(p) not in sys.path:
+        sys.path.insert(0, str(p))
+
+import vgplot as vg  # noqa: E402
+
+SCHEMA = ROOT / "docs" / "public" / "schema" / "latest.json"
+
+# Schema names whose Python export is renamed or intentionally absent.
+RENAME = {"table": "table_input"}  # `table` input -> vg.table_input (vg.table is data)
+IGNORE = {"value"}  # internal selection const, not a user-facing interactor
+
+
+def _snake(name: str) -> str:
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", name).lower()
+
+
+def _const(node: dict, key: str):
+    prop = node.get("properties", {}).get(key)
+    return prop["const"] if isinstance(prop, dict) and "const" in prop else None
+
+
+def _consts(defs: dict, key: str) -> set[str]:
+    """Const values for `key`, including intersection defs (anyOf/allOf) whose
+    branches all agree on a single const (e.g. the densityX mark)."""
+    out = set()
+    for d in defs.values():
+        c = _const(d, key)
+        if c is not None:
+            out.add(c)
+            continue
+        branch_consts = {
+            _const(b, key) for b in (d.get("anyOf") or d.get("allOf") or [])
+        } - {None}
+        if len(branch_consts) == 1:
+            out |= branch_consts
+    return out
+
+
+def test_schema_surface_is_exported():
+    defs = json.loads(SCHEMA.read_text("utf-8"))["definitions"]
+    names = (
+        _consts(defs, "mark")
+        | _consts(defs, "select")
+        | _consts(defs, "input")
+        | set(defs["PlotAttributes"]["properties"])
+    ) - IGNORE
+
+    exported = set(vg.__all__)
+    missing = sorted(n for n in names if RENAME.get(n, _snake(n)) not in exported)
+    assert not missing, f"schema names with no exported vgplot function: {missing}"