vgplot 0.29.0__py3-none-any.whl

vgplot/spec.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import inspect
+import json
+from typing import Any
+
+from .util import omit_none
+from .params import _ParamBase
+from .data import DataDef
+from .plot import _encode_component
+
+
+def _caller_locals() -> dict[str, Any]:
+    """Local variables of the caller of the method invoking this helper.
+
+    Returns an empty mapping when the frame is unavailable (e.g. on Python
+    implementations without ``sys._getframe`` support).
+    """
+    frame = inspect.currentframe()
+    method = frame.f_back if frame is not None else None
+    caller = method.f_back if method is not None else None
+    return caller.f_locals if caller is not None else {}
+
+
+def _collect_params(node: Any) -> list[_ParamBase]:
+    """Recursively collect all _ParamBase instances in a view tree."""
+    if isinstance(node, _ParamBase):
+        return [node]
+    if isinstance(node, View):
+        return _collect_params(node._view)
+    if isinstance(node, dict):
+        found = []
+        for v in node.values():
+            found.extend(_collect_params(v))
+        return found
+    if isinstance(node, list):
+        found = []
+        for item in node:
+            found.extend(_collect_params(item))
+        return found
+    return []
+
+
+def _collect_datadefs(node: Any) -> list[DataDef]:
+    """Recursively collect all DataDef instances in a view tree."""
+    if isinstance(node, DataDef):
+        return [node]
+    if isinstance(node, View):
+        return _collect_datadefs(node._view)
+    if isinstance(node, dict):
+        found = []
+        for v in node.values():
+            found.extend(_collect_datadefs(v))
+        return found
+    if isinstance(node, list):
+        found = []
+        for item in node:
+            found.extend(_collect_datadefs(item))
+        return found
+    return []
+
+
+class Spec:
+    def __init__(
+        self,
+        *,
+        data: dict[str, Any] | None = None,
+        data_names: dict[int, str] | None = None,
+        params: dict[str, Any] | None = None,
+        plotDefaults: dict[str, Any] | None = None,
+        plot_defaults: dict[str, Any] | None = None,
+        config: dict[str, Any] | None = None,
+        view: dict[str, Any] | None = None,
+        **extra: Any,
+    ) -> None:
+        # Serialize any DataDef values in data and build id→name mapping
+        resolved_data: dict[str, Any] = {}
+        resolved_data_names: dict[int, str] = dict(data_names or {})
+        for name, val in (data or {}).items():
+            if isinstance(val, DataDef):
+                resolved_data_names[id(val)] = name
+                resolved_data[name] = val.to_dict()
+            else:
+                resolved_data[name] = val
+        self.data = resolved_data or None
+        self.data_names = resolved_data_names
+        self.params = params
+        self.plotDefaults = plotDefaults or plot_defaults
+        self.config = config
+        self.view = view or {}
+        self.extra = extra
+
+    def to_dict(self) -> dict[str, Any]:
+        # Build a reverse lookup: id(param_object) -> param_name, so that
+        # _ParamBase instances appearing in the view resolve to "$name" refs.
+        param_names: dict[int, str] = {}
+        serialized_params: dict[str, Any] = {}
+        # First pass: register all named params
+        for name, p in (self.params or {}).items():
+            if isinstance(p, _ParamBase):
+                param_names[id(p)] = name
+
+        # Second pass: auto-name any _ParamBase in the view not yet registered,
+        # skipping names already taken by explicit params.
+        used = set(param_names.values()) | set(self.params or {})
+        counter = 0
+        for obj in _collect_params(self.view):
+            if id(obj) not in param_names:
+                while f"_param{counter}" in used:
+                    counter += 1
+                param_names[id(obj)] = f"_param{counter}"
+                counter += 1
+
+        # Third pass: serialize all known params
+        view_params = {id(obj): obj for obj in _collect_params(self.view)}
+        all_params = dict(self.params or {})
+        for obj_id, name in param_names.items():
+            if name not in all_params and obj_id in view_params:
+                all_params[name] = view_params[obj_id]
+        for name, p in all_params.items():
+            if isinstance(p, _ParamBase):
+                serialized_params[name] = p.param_def(param_names=param_names)
+            else:
+                serialized_params[name] = p
+
+        # Build data_names lookup and auto-register any unnamed DataDefs in the view
+        data_names = dict(self.data_names)
+        extra_data: dict[str, Any] = {}
+        used = set(data_names.values()) | set(self.data or {})
+        counter = 0
+        for obj in _collect_datadefs(self.view):
+            if id(obj) not in data_names:
+                while f"_data{counter}" in used:
+                    counter += 1
+                auto_name = f"_data{counter}"
+                data_names[id(obj)] = auto_name
+                extra_data[auto_name] = obj.to_dict()
+                counter += 1
+        merged_data = {**(self.data or {}), **extra_data} or None
+
+        base: dict[str, Any] = {}
+        if self.config:
+            base["config"] = self.config
+        if merged_data:
+            base["data"] = merged_data
+        if serialized_params:
+            base["params"] = serialized_params
+        if self.plotDefaults:
+            base["plotDefaults"] = self.plotDefaults
+        base.update(_encode_component(self.view, param_names, data_names))
+        base.update(omit_none(self.extra))
+        return base
+
+    def to_json(self, **kwargs: Any) -> str:
+        return json.dumps(self.to_dict(), **kwargs)
+
+    def _repr_mimebundle_(self, **kwargs):
+        try:
+            from mosaic_widget import MosaicWidget
+        except ImportError:
+            return {"text/plain": repr(self)}
+        widget = MosaicWidget(self.to_dict())
+        return widget._repr_mimebundle_(**kwargs)
+
+    def show(self, con=None, data=None):
+        try:
+            from mosaic_widget import MosaicWidget
+            from IPython.display import display
+        except ImportError as e:
+            raise ImportError("pip install mosaic-widget") from e
+        widget = MosaicWidget(self.to_dict(), con=con, data=data)
+        display(widget)
+
+
+class View:
+    """
+    A composable view returned by plot(), vconcat(), hconcat() etc.
+    Behaves like Spec but discovers data and params from the caller's
+    frame at display/export time rather than at construction time.
+    """
+
+    def __init__(
+        self,
+        view: dict[str, Any],
+        *,
+        data: dict[str, Any] | None = None,
+        plotDefaults: dict[str, Any] | None = None,
+        plot_defaults: dict[str, Any] | None = None,
+        config: dict[str, Any] | None = None,
+        **extra: Any,
+    ) -> None:
+        self._view = view
+        self._data = data  # explicit overrides for renamed data variables
+        self._plotDefaults = plotDefaults or plot_defaults
+        self._config = config
+        self._extra = extra
+
+    def _build_spec(self, caller_locals: dict[str, Any]) -> Spec:
+        explicit_ids = {
+            id(v) for v in (self._data or {}).values() if isinstance(v, DataDef)
+        }
+        frame_data: dict[str, Any] = {
+            name: obj
+            for name, obj in caller_locals.items()
+            if isinstance(obj, DataDef)
+            and not name.startswith("_")
+            and id(obj) not in explicit_ids
+        }
+        merged_data = {**(self._data or {}), **frame_data} or None
+        frame_params: dict[str, Any] = {
+            name: obj
+            for name, obj in caller_locals.items()
+            if isinstance(obj, _ParamBase) and not name.startswith("_")
+        }
+        return Spec(
+            data=merged_data,
+            params=frame_params or None,
+            plotDefaults=self._plotDefaults,
+            config=self._config,
+            view=self._view,
+            **self._extra,
+        )
+
+    def to_dict(self, _context: dict[str, Any] | None = None) -> dict[str, Any]:
+        locals_ = _context if _context is not None else _caller_locals()
+        return self._build_spec(locals_).to_dict()
+
+    def to_json(self, _context: dict[str, Any] | None = None, **kwargs: Any) -> str:
+        locals_ = _context if _context is not None else _caller_locals()
+        return self._build_spec(locals_).to_json(**kwargs)
+
+    def show(self, con: Any = None, data: Any = None) -> None:
+        self._build_spec(_caller_locals()).show(con=con, data=data)
+
+    def _repr_mimebundle_(self, **kwargs: Any):
+        # Walk up frames to find the one where this View object lives
+        frame = inspect.currentframe()
+        frame = frame.f_back if frame is not None else None
+        while frame is not None:
+            if any(v is self for v in frame.f_locals.values()):
+                break
+            frame = frame.f_back
+        locals_ = frame.f_locals if frame is not None else {}
+        return self._build_spec(locals_)._repr_mimebundle_(**kwargs)
+
+
+_VIEW_KEYS = {"plot", "vconcat", "hconcat", "hspace", "vspace", "input"}
+
+
+def spec(
+    *args: Any,
+    data: dict[str, Any] | None = None,
+    params: dict[str, Any] | None = None,
+    plotDefaults: dict[str, Any] | None = None,
+    plot_defaults: dict[str, Any] | None = None,
+    config: dict[str, Any] | None = None,
+    view: dict[str, Any] | None = None,
+    **extra: Any,
+) -> Spec:
+    """Assemble a Spec from a view plus data sources and params.
+
+    A positional dict holding a view key (plot/vconcat/hconcat/...) is used as
+    the view; any other positional dict is used as data. DataDef and param
+    objects bound to local variables in the caller are discovered automatically
+    by name unless passed explicitly via data= or params=.
+    """
+    for arg in args:
+        if isinstance(arg, dict) and _VIEW_KEYS.intersection(arg):
+            view = arg
+        elif isinstance(arg, dict):
+            data = arg
+
+    # Inspect caller frame to discover DataDef and _ParamBase objects by variable name.
+    caller_locals = _caller_locals()
+
+    # Collect DataDef objects not already covered by the explicit data= argument.
+    explicit_ids = {id(v) for v in (data or {}).values() if isinstance(v, DataDef)}
+    frame_data: dict[str, Any] = {
+        name: obj
+        for name, obj in caller_locals.items()
+        if isinstance(obj, DataDef)
+        and not name.startswith("_")
+        and id(obj) not in explicit_ids
+    }
+    merged_data = {**(data or {}), **frame_data} or None
+
+    # Collect _ParamBase objects when params were not passed explicitly.
+    if params is None:
+        frame_params: dict[str, Any] = {
+            name: obj
+            for name, obj in caller_locals.items()
+            if isinstance(obj, _ParamBase) and not name.startswith("_")
+        }
+        params = frame_params or None
+
+    return Spec(
+        data=merged_data,
+        params=params,
+        plotDefaults=plotDefaults,
+        plot_defaults=plot_defaults,
+        config=config,
+        view=view,
+        **extra,
+    )

vgplot/util.py

@@ -0,0 +1,14 @@
+from typing import Any
+
+
+def camelize(key: str) -> str:
+    """Convert snake_case to lowerCamelCase."""
+    if not key:
+        return key
+    parts = key.split("_")
+    return parts[0] + "".join(p[:1].upper() + p[1:] for p in parts[1:])
+
+
+def omit_none(d: dict[str, Any]) -> dict[str, Any]:
+    """Return a copy without None values."""
+    return {k: v for k, v in d.items() if v is not None}

vgplot-0.29.0.dist-info/METADATA

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: vgplot
+Version: 0.29.0
+Summary: A Python API for authoring Mosaic vgplot visualizations
+Project-URL: homepage, https://github.com/uwdata/mosaic
+Requires-Python: >=3.10
+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.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+vgplot/__init__.py,sha256=uALjBohruCjzzzXLOENDPbfYgCC5u7j2KLnTXaUcAHw,1678
+vgplot/_types.py,sha256=cs5FgHnBKmcx9HaH4AWOaBZkMR3Vlg2CR4QXcv_qmWE,870
+vgplot/data.py,sha256=VgG62a806C0bYo--sdpqK8r4pLZdeEKeUwhIJ3k_bTs,1493
+vgplot/encodings.py,sha256=sb_TcBzClBL3c9IID8OSGVExCYYE7pB35bRaJt680ns,197
+vgplot/params.py,sha256=d2copQfOHEu29cyS49_dgQSIe6ouU3_TSiafXUbFqg4,2724
+vgplot/plot.py,sha256=2ScCoEDgYog3MZWMKXvNtCE1Cnd41xVyCI8guGCbehw,13583
+vgplot/spec.py,sha256=MzI60-5rwu-UDCd1cn8oqj1Vl7FkCLwdEvPSWwF5MWs,11074
+vgplot/util.py,sha256=3HQBJaXyCmM680xHvpmE4OaGSf1Nm7_PpbIUGs1WP4k,394
+vgplot/_generated/__init__.py,sha256=S_iBHL2x70pcqk1OY-pw3xoXvSEcaxjpjpmN4n-zCxI,421
+vgplot/_generated/attributes.py,sha256=Ghgp-geFLefbwD9awAs8ja2bHd0MiKTirrJyT5bSJMo,46270
+vgplot/_generated/encodings.py,sha256=OcktD1tX2zqOb7X3XSZ6GNCpsNQW5B3pjF_vwzja_I4,8081
+vgplot/_generated/marks.py,sha256=z_iM_BZ7FCtjCgWuv9NRnW8g1tFg56NKQpQ4wV8Q48Q,137136
+vgplot-0.29.0.dist-info/METADATA,sha256=ZZqIFGtZaRQ2Ki-Acc8ZZ-4uE4XOeTOimdz4DoqYJYw,4414
+vgplot-0.29.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+vgplot-0.29.0.dist-info/RECORD,,

vgplot-0.29.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any