vgplot 0.29.0__tar.gz → 0.30.0__tar.gz

{vgplot-0.29.0 → vgplot-0.30.0}/.gitignore

@@ -22,6 +22,7 @@ transitionFolder
 # Virtual environment
 venv/
 .env/
+**/.python-version
 
 # Conda environment
 conda-env/

{vgplot-0.29.0 → vgplot-0.30.0}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.4
 Name: vgplot
-Version: 0.29.0
+Version: 0.30.0
 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
@@ -58,18 +59,30 @@ 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.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.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)"),
@@ -93,9 +106,7 @@ 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),
+        vg.area_y(walk, x="t", y=vg.sql("v + $bias")), vg.width(680), vg.height(200)
     ),
 )
 

{vgplot-0.29.0 → vgplot-0.30.0}/README.md

@@ -50,18 +50,30 @@ 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.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.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)"),
@@ -85,9 +97,7 @@ 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),
+        vg.area_y(walk, x="t", y=vg.sql("v + $bias")), vg.width(680), vg.height(200)
     ),
 )
 

{vgplot-0.29.0 → vgplot-0.30.0}/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vgplot-python",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "private": true,
   "scripts": {
     "prerelease": "uv run ruff check && uv run ruff format --check",

{vgplot-0.29.0 → vgplot-0.30.0}/pyproject.toml

@@ -4,7 +4,7 @@ dynamic = ["version"]
 description = "A Python API for authoring Mosaic vgplot visualizations"
 readme = "README.md"
 requires-python = ">=3.10"
-dependencies = []
+dependencies = ["narwhals>=2.8.0"]
 
 [project.urls]
 homepage = "https://github.com/uwdata/mosaic"
@@ -31,7 +31,3 @@ 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.0/test → vgplot-0.30.0/tests}/test_full_round_trip.py

@@ -3,26 +3,18 @@
 # 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
+# Run: pytest packages/vgplot/vgplot-python/tests/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"
+SPEC_DIR = Path(__file__).resolve().parents[4] / "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"))

{vgplot-0.29.0/test → vgplot-0.30.0/tests}/test_python_api.py

@@ -1,18 +1,11 @@
 # 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
+from typing import TYPE_CHECKING
 
 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
+import vgplot as vg
+from vgplot.plot import Mark
 
 
 class TestGeneratedMarks:
@@ -79,3 +72,48 @@ class TestAutoNaming:
         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):
+        pytest.importorskip("pyarrow")
+        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):
+        pytest.importorskip("pyarrow")
+        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"}
+
+
+if TYPE_CHECKING:
+
+    def typing_dunder_all() -> None:
+        # Ok
+        vg.arrow
+        vg.errorbar_x
+        vg.mark
+
+        # TODO @dangotbanned: Get pyright to error on these
+        # Error (`_generated` modules)
+        vg.attributes  # ty: ignore[unresolved-attribute]
+        vg.marks  # ty: ignore[unresolved-attribute]

{vgplot-0.29.0/test → vgplot-0.30.0/tests}/test_schema_coverage.py

@@ -4,16 +4,11 @@
 # 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
+import vgplot as vg
 
+ROOT = Path(__file__).resolve().parents[4]
 SCHEMA = ROOT / "docs" / "public" / "schema" / "latest.json"
 
 # Schema names whose Python export is renamed or intentionally absent.

vgplot-0.30.0/tests/test_unset_sentinel.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import copy
+from typing import TYPE_CHECKING, Any, Union, get_type_hints
+
+if TYPE_CHECKING:
+    # NOTE: Don't move this into a runtime import (yet)
+    from vgplot._types import UNSET
+
+
+def _import_unset() -> UNSET:
+    # NOTE: A regular import would add:
+    # - `vgplot._types` to `sys.modules`
+    # - `UNSET` to `globals`
+    # And we can't use `importlib.reload`, since that would create a new object
+    from vgplot._types import UNSET
+
+    return UNSET
+
+
+def test_unset_identity() -> None:
+    unset_1 = _import_unset()
+    unset_2 = _import_unset()
+    assert unset_1 is unset_2
+
+
+def test_unset_repr() -> None:
+    assert repr(_import_unset()) == "UNSET"
+
+
+def test_unset_pickle() -> None:
+    import pickle
+
+    unset = _import_unset()
+    assert pickle.loads(pickle.dumps(unset)) is unset  # noqa: S301
+
+
+def test_unset_type_expression_union() -> None:
+    # Adapted from https://github.com/python/typing_extensions/blob/83400e979b8e3b0b647f9a6a57f0275230e5f19f/src/test_typing_extensions.py#L9694-L9701
+    from vgplot._types import UNSET
+
+    def func1(a: int | UNSET = UNSET) -> None: ...
+    def func2(a: UNSET | int = UNSET) -> None: ...
+
+    assert get_type_hints(func1, localns=locals())["a"] == Union[int, UNSET]  # noqa: UP007
+    assert get_type_hints(func2, localns=locals())["a"] == Union[UNSET, int]  # noqa: UP007
+
+
+def test_unset_copy_identity() -> None:
+    # Adapted from https://github.com/python/typing_extensions/blob/83400e979b8e3b0b647f9a6a57f0275230e5f19f/src/test_typing_extensions.py#L9711-L9713
+    unset = _import_unset()
+    assert unset is copy.copy(unset)
+    assert unset is copy.deepcopy(unset)
+
+
+def test_unset_union_identity() -> None:
+    unset = _import_unset()
+    assert (unset | unset) is unset
+
+
+if TYPE_CHECKING:
+    from typing_extensions import assert_type
+
+    def typing_unset(
+        a: UNSET, b: str | UNSET, c: Any | UNSET, d: int | None | UNSET = UNSET
+    ) -> None:
+        assert_type(a, UNSET)
+        assert_type(b, str | UNSET)
+        assert_type(c, Any | UNSET)
+        assert_type(d, int | None | UNSET)

vgplot-0.30.0/vgplot/_compat.py

@@ -0,0 +1,103 @@
+"""Backwards compatibility for features not available at our [requires-python][1].
+
+Import from here to avoid introducing runtime dependency on [typing_extensions][2].
+
+[1]: https://packaging.python.org/en/latest/specifications/pyproject-toml/#requires-python
+[2]: https://github.com/python/typing_extensions
+
+## sentinel
+[`sentinel`][3] was introduced in `3.15` (see [PEP 661][4]).
+
+We can remove the backport after [3.15 end-of-life][5].
+
+[3]: https://docs.python.org/3.15/library/functions.html#sentinel
+[4]: https://peps.python.org/pep-0661/
+[5]: https://peps.python.org/pep-0790/#lifespan
+"""
+
+from __future__ import annotations
+
+import sys
+import typing
+
+# ruff: noqa: A002
+from contextlib import suppress
+from importlib.util import find_spec
+from typing import TYPE_CHECKING, Any, ClassVar
+
+
+def _sentinel_backport_pre_typing_extensions_4_16() -> Any:
+    class _sentinel_backport:
+        """Create a unique sentinel object.
+
+        *name* should be the name of the variable to which the return value shall be assigned.
+        """
+
+        def __init__(self, name: str, /, *, repr: str | None = None) -> None:
+            self.__name__: str = name
+            self._repr: str = repr if repr is not None else name
+            # TODO @dangotbanned: Figure out why they didn't use the `"__main__"` default here?
+            module: str | None = None
+            if hasattr(sys, "_getframemodulename"):
+                module = sys._getframemodulename(1) or "__main__"
+            elif hasattr(sys, "_getframe"):
+                with suppress(ValueError):
+                    module = sys._getframe(1).f_globals.get("__name__", "__main__")
+
+            # For pickling as a singleton
+            self.__module__ = module  # pyright: ignore[reportAttributeAccessIssue] # ty: ignore[invalid-assignment]
+
+        __init_subclass__: ClassVar[None] = None
+
+        def __repr__(self) -> str:
+            return self._repr
+
+        if sys.version_info < (3, 11):
+            # The presence of this method convinces typing._type_check that Sentinels are types.
+            def __call__(self, *args: Any, **kwargs: Any) -> Any:
+                msg = f"{type(self).__name__!r} object is not callable"
+                raise TypeError(msg)
+
+        def __or__(self, other: Any) -> Any:
+            return typing.Union[self, other]  # noqa: UP007
+
+        def __ror__(self, other: Any) -> Any:
+            return typing.Union[other, self]  # noqa: UP007
+
+        def __reduce__(self) -> str:
+            return self.__name__
+
+    return _sentinel_backport
+
+
+def _sentinel_backport_pre_py_3_15() -> Any:
+    """Return a [PEP 661]-compatible [`sentinel`](https://docs.python.org/3.15/library/functions.html#sentinel) factory.
+
+    [PEP 661]: https://peps.python.org/pep-0661/
+
+    ## Notes
+    - Does not depend on `typing_extensions`, but will use it if a suitable version is available
+    - Fallback is adapted from [`typing_extensions==4.16.0`](https://github.com/python/typing_extensions/blob/f29cd28d8ed7642cafb1d18daf5aa41be6a5c0aa/src/typing_extensions.py#L176-L271)
+    """
+    if find_spec("typing_extensions"):
+        import typing_extensions
+
+        # NOTE: In the same release the name changed, this guy landed https://github.com/python/typing_extensions/pull/617
+        # `4.14-4.15` is fine for typing, but the runtime changes are too big to rely on
+        if hasattr(typing_extensions, "sentinel"):
+            return getattr(typing_extensions, "sentinel", typing_extensions.Sentinel)
+
+    return _sentinel_backport_pre_typing_extensions_4_16()
+
+
+if TYPE_CHECKING:
+    # Was renamed in https://github.com/python/typing_extensions/releases/tag/4.16.0
+    from typing_extensions import Sentinel as sentinel  # noqa: N813
+else:  # noqa: PLR5501
+    if sys.version_info >= (3, 15):
+        from builtins import sentinel
+    else:
+        sentinel = _sentinel_backport_pre_py_3_15()
+
+
+__all__ = ("sentinel",)

{vgplot-0.29.0 → vgplot-0.30.0}/vgplot/_generated/__init__.py

@@ -7,4 +7,4 @@ from .attributes import __all__ as _attr_all
 from .encodings import __all__ as _enc_all
 from .marks import __all__ as _mark_all
 
-__all__ = [*_mark_all, *_attr_all, *_enc_all]
+__all__ = [*_mark_all, *_attr_all, *_enc_all]  # pyright: ignore[reportUnsupportedDunderAll]

{vgplot-0.29.0 → vgplot-0.30.0}/vgplot/_generated/encodings.py

@@ -54,7 +54,7 @@ def column(col: TransformArg, **options: Any) -> dict[str, Any]:
     return _transform("column", (col,), options)
 
 
-def count(col: TransformArg = UNSET, **options: Any) -> dict[str, Any]:
+def count(col: TransformArg | UNSET = UNSET, **options: Any) -> dict[str, Any]:
     """Compute the count of records in an aggregation group."""
     return _transform("count", (col,), options)
 
@@ -101,8 +101,8 @@ def geojson(col: TransformArg, **options: Any) -> dict[str, Any]:
 
 def lag(
     col: TransformArg,
-    offset: TransformArg = UNSET,
-    default: TransformArg = UNSET,
+    offset: TransformArg | UNSET = UNSET,
+    default: TransformArg | UNSET = UNSET,
     **options: Any,
 ) -> dict[str, Any]:
     """Compute lagging values in a column."""
@@ -121,8 +121,8 @@ def last_value(col: TransformArg, **options: Any) -> dict[str, Any]:
 
 def lead(
     col: TransformArg,
-    offset: TransformArg = UNSET,
-    default: TransformArg = UNSET,
+    offset: TransformArg | UNSET = UNSET,
+    default: TransformArg | UNSET = UNSET,
     **options: Any,
 ) -> dict[str, Any]:
     """Compute leading values in a column."""
@@ -150,7 +150,7 @@ def mode(col: TransformArg, **options: Any) -> dict[str, Any]:
 
 
 def nth_value(
-    col: TransformArg, offset: TransformArg = UNSET, **options: Any
+    col: TransformArg, offset: TransformArg | UNSET = UNSET, **options: Any
 ) -> dict[str, Any]:
     """Get the nth value of the given column in the current window frame, counting from one."""
     return _transform("nth_value", (col, offset), options)