vgplot 0.1.0__tar.gz

vgplot-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+.DS_Store
+.mosaic
+.duckdb
+.ipynb_checkpoints
+.idea
+dev/specs
+docs/.vitepress/cache
+docs/.vitepress/dist
+node_modules
+**/dist
+**/test-output
+**/__pycache__
+**/.ruff_cache
+**/.pytest_cache
+**/.mypy_cache
+**/.coverage
+**/.venv
+**/tsconfig.tsbuildinfo
+packages/server/duckdb-server-go/duckdb-server-go
+transitionFolder
+
+# Virtual environment
+venv/
+.env/
+
+# Conda environment
+conda-env/
+
+# Python cache
+__pycache__/
+*.pyc
+
+# Test cache
+.pytest_cache/
+.coverage
+
+# Python API Generated classes
+packages/vgplot-python/schema_wrapper/generated_classes.py

vgplot-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: vgplot
+Version: 0.1.0
+Summary: Schema wrapper classes for Mosaic
+Project-URL: homepage, https://github.com/uwdata/mosaic
+Requires-Python: >=3.9
+Requires-Dist: narwhals
+Requires-Dist: pyyaml
+Description-Content-Type: text/markdown
+
+# Mosaic Python API
+
+## Generate the API from the JSON schama
+
+`uv run generate-schema-wrapper`.
+
+## Run Tests
+
+`uv run pytest -v`
+
+## Run the ruff formatter
+
+`uv run ruff format` and `uv run ruff check`.
+
+## Test notebook
+
+`uv run jupyter lab` and then open `example.ipynb`.

vgplot-0.1.0/README.md

@@ -0,0 +1,17 @@
+# Mosaic Python API
+
+## Generate the API from the JSON schama
+
+`uv run generate-schema-wrapper`.
+
+## Run Tests
+
+`uv run pytest -v`
+
+## Run the ruff formatter
+
+`uv run ruff format` and `uv run ruff check`.
+
+## Test notebook
+
+`uv run jupyter lab` and then open `example.ipynb`.

vgplot-0.1.0/__init__.py

@@ -0,0 +1 @@
+# Mosaic Python package namespace for vgplot authoring API.

vgplot-0.1.0/api/__init__.py

@@ -0,0 +1,119 @@
+from .spec import meta, spec, Spec
+from .data import parquet, table, data
+from .plot import (
+    plot,
+    from_,
+    rule_y,
+    rule_x,
+    line_y,
+    line_x,
+    bar_y,
+    bar_x,
+    area_y,
+    area_x,
+    text,
+    dot,
+    density,
+    y_grid,
+    y_label,
+    y_tick_format,
+    x_tick_format,
+    x_axis,
+    y_axis,
+    x_label,
+    x_label_anchor,
+    y_label_anchor,
+    r_range,
+    color_domain,
+    color_scale,
+    x_tick_size,
+    y_tick_size,
+    width,
+    height,
+    margins,
+    vconcat,
+    hconcat,
+    vspace,
+    hspace,
+    mark,
+    directive,
+    slider,
+    select,
+    checkbox,
+    input,
+)
+
+__all__ = [
+    "meta",
+    "spec",
+    "Spec",
+    "parquet",
+    "table",
+    "data",
+    "plot",
+    "from_",
+    "mark",
+    "rule_y",
+    "rule_x",
+    "line_y",
+    "line_x",
+    "bar_y",
+    "bar_x",
+    "area_y",
+    "area_x",
+    "text",
+    "dot",
+    "density",
+    "y_grid",
+    "y_label",
+    "y_tick_format",
+    "x_tick_format",
+    "x_axis",
+    "y_axis",
+    "x_label",
+    "x_label_anchor",
+    "y_label_anchor",
+    "r_range",
+    "color_domain",
+    "color_scale",
+    "x_tick_size",
+    "y_tick_size",
+    "width",
+    "height",
+    "margins",
+    "vconcat",
+    "hconcat",
+    "vspace",
+    "hspace",
+    "directive",
+    "slider",
+    "select",
+    "checkbox",
+    "input",
+]
+
+
+def __getattr__(name: str):
+    """Dynamic mark/directive factory for names not explicitly exported.
+
+    Allows any snake_case mark or directive to be used without an explicit
+    function definition, e.g.::
+    """
+    if name.startswith("_"):
+        raise AttributeError(name)
+
+    from .plot import Directive, Mark
+    from .util import camelize
+
+    camel = camelize(name)
+
+    def _factory(*args, data=None, **kwargs):
+        if len(args) == 1 and data is None and not kwargs:
+            # Single positional arg to directive
+            return Directive(camel, args[0])
+        # otherwise creates a mark
+        return Mark(camel, data=data, enc=kwargs if kwargs else None)
+
+    _factory.__name__ = name
+    _factory.__qualname__ = f"vgplot.{name}"
+    return _factory

vgplot-0.1.0/api/data.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict
+
+
+@dataclass
+class DataDef:
+    payload: Dict[str, Any]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return self.payload
+
+
+def parquet(file: str) -> DataDef:
+    return DataDef({"type": "parquet", "file": file})
+
+
+def table(query: str) -> DataDef:
+    return DataDef({"type": "table", "query": query})
+
+
+def data(**named_defs: DataDef) -> Dict[str, Any]:
+    out: Dict[str, Any] = {}
+    for k, v in named_defs.items():
+        out[k] = v.to_dict() if hasattr(v, "to_dict") else v
+    return out

vgplot-0.1.0/api/plot.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Union
+
+from .util import camelize, omit_none
+
+
+class FromRef:
+    def __init__(self, name: str):
+        self.name = name
+
+    def to_dict(self) -> Dict[str, str]:
+        return {"from": self.name}
+
+
+def from_(name: str) -> FromRef:
+    return FromRef(name)
+
+
+@dataclass
+class Directive:
+    key: str
+    value: Any
+
+    def to_kv(self):
+        return camelize(self.key), self.value
+
+
+@dataclass
+class Mark:
+    mark: str
+    data: Optional[Any] = None
+    enc: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {"mark": self.mark}
+        if self.data is not None:
+            payload["data"] = encode_value(self.data)
+        if self.enc:
+            for k, v in self.enc.items():
+                payload[camelize(k)] = encode_value(v)
+        return payload
+
+
+def encode_value(v: Any) -> Any:
+    if isinstance(v, FromRef):
+        return v.to_dict()
+    if isinstance(v, Mark):
+        return v.to_dict()
+    if isinstance(v, list):
+        return [encode_value(x) for x in v]
+    if isinstance(v, dict):
+        return {k: encode_value(val) for k, val in v.items()}
+    return v
+
+
+def plot(*items: Union[Mark, Directive]) -> Dict[str, Any]:
+    marks: List[Dict[str, Any]] = []
+    directives: Dict[str, Any] = {}
+    for item in items:
+        if isinstance(item, Mark):
+            marks.append(item.to_dict())
+        elif isinstance(item, Directive):
+            k, v = item.to_kv()
+            directives[k] = v
+        elif isinstance(item, dict):
+            # Treat dicts as already-structured mark entries.
+            marks.append(item)
+        else:
+            raise TypeError(f"Unsupported plot item: {item}")
+    root: Dict[str, Any] = {"plot": marks}
+    root.update(directives)
+    return root
+
+
+def directive(key: str, value: Any) -> Directive:
+    return Directive(key, value)
+
+
+def mark(name: str, data: Any = None, **enc: Any) -> Mark:
+    return Mark(name, data=data, enc=enc)
+
+
+def rule_y(data: Any = None, **enc: Any) -> Mark:
+    return Mark("ruleY", data=data, enc=enc)
+
+
+def rule_x(data: Any = None, **enc: Any) -> Mark:
+    return Mark("ruleX", data=data, enc=enc)
+
+
+def line_y(data: Any = None, **enc: Any) -> Mark:
+    return Mark("lineY", data=data, enc=enc)
+
+
+def line_x(data: Any = None, **enc: Any) -> Mark:
+    return Mark("lineX", data=data, enc=enc)
+
+
+def bar_y(data: Any = None, **enc: Any) -> Mark:
+    return Mark("barY", data=data, enc=enc)
+
+
+def bar_x(data: Any = None, **enc: Any) -> Mark:
+    return Mark("barX", data=data, enc=enc)
+
+
+def area_y(data: Any = None, **enc: Any) -> Mark:
+    return Mark("areaY", data=data, enc=enc)
+
+
+def area_x(data: Any = None, **enc: Any) -> Mark:
+    return Mark("areaX", data=data, enc=enc)
+
+
+def text(data: Any = None, **enc: Any) -> Mark:
+    return Mark("text", data=data, enc=enc)
+
+
+def dot(data: Any = None, **enc: Any) -> Mark:
+    return Mark("dot", data=data, enc=enc)
+
+
+def density(data: Any = None, **enc: Any) -> Mark:
+    return Mark("density", data=data, enc=enc)
+
+
+def y_grid(value: bool) -> Directive:
+    return Directive("y_grid", value)
+
+
+def y_label(value: str) -> Directive:
+    return Directive("y_label", value)
+
+
+def y_tick_format(value: str) -> Directive:
+    return Directive("y_tick_format", value)
+
+
+def x_tick_format(value: str) -> Directive:
+    return Directive("x_tick_format", value)
+
+
+def x_axis(value: Any) -> Directive:
+    return Directive("x_axis", value)
+
+
+def y_axis(value: Any) -> Directive:
+    return Directive("y_axis", value)
+
+
+def x_label(value: str) -> Directive:
+    return Directive("x_label", value)
+
+
+def x_label_anchor(value: str) -> Directive:
+    return Directive("x_label_anchor", value)
+
+
+def y_label_anchor(value: str) -> Directive:
+    return Directive("y_label_anchor", value)
+
+
+def r_range(value: Any) -> Directive:
+    return Directive("r_range", value)
+
+
+def color_domain(value: Any) -> Directive:
+    return Directive("color_domain", value)
+
+
+def color_scale(value: Any) -> Directive:
+    return Directive("color_scale", value)
+
+
+def width(value: int) -> Directive:
+    return Directive("width", value)
+
+
+def height(value: int) -> Directive:
+    return Directive("height", value)
+
+
+def margins(
+    top: int = None,
+    right: int = None,
+    bottom: int = None,
+    left: int = None,
+    **kwargs: Any,
+) -> Directive:
+    return Directive(
+        "margins",
+        omit_none(
+            {"top": top, "right": right, "bottom": bottom, "left": left, **kwargs}
+        ),
+    )
+
+
+def x_tick_size(value: Any) -> Directive:
+    return Directive("x_tick_size", value)
+
+
+def y_tick_size(value: Any) -> Directive:
+    return Directive("y_tick_size", value)
+
+
+# Layout helpers
+def vconcat(*items: Any) -> Dict[str, Any]:
+    return {"vconcat": [encode_value(i) for i in items]}
+
+
+def hconcat(*items: Any) -> Dict[str, Any]:
+    return {"hconcat": [encode_value(i) for i in items]}
+
+
+def hspace(px: int) -> Dict[str, Any]:
+    return {"hspace": px}
+
+
+def vspace(px: int) -> Dict[str, Any]:
+    return {"vspace": px}
+
+
+# Input helpers
+def input(kind: str, **opts: Any) -> Dict[str, Any]:
+    payload = {"input": kind}
+    payload.update({camelize(k): v for k, v in opts.items() if v is not None})
+    return payload
+
+
+def slider(
+    label: str,
+    as_: str,
+    min: Any = None,
+    max: Any = None,
+    step: Any = None,
+    value: Any = None,
+    **opts: Any,
+) -> Dict[str, Any]:
+    return input(
+        "slider", label=label, as_=as_, min=min, max=max, step=step, value=value, **opts
+    )
+
+
+def select(
+    label: str,
+    as_: str,
+    options: Any,
+    multiple: bool = False,
+    value: Any = None,
+    **opts: Any,
+) -> Dict[str, Any]:
+    return input(
+        "select",
+        label=label,
+        as_=as_,
+        options=options,
+        multiple=multiple,
+        value=value,
+        **opts,
+    )
+
+
+def checkbox(label: str, as_: str, value: bool = False, **opts: Any) -> Dict[str, Any]:
+    return input("checkbox", label=label, as_=as_, value=value, **opts)

vgplot-0.1.0/api/spec.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+from .util import omit_none
+
+
+@dataclass
+class Meta:
+    title: Optional[str] = None
+    description: Optional[str] = None
+    credit: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return omit_none(
+            {
+                "title": self.title,
+                "description": self.description,
+                "credit": self.credit,
+            }
+        )
+
+
+def meta(
+    title: str | None = None, description: str | None = None, credit: str | None = None
+) -> Meta:
+    return Meta(title=title, description=description, credit=credit)
+
+
+class Spec:
+    def __init__(
+        self,
+        *,
+        meta: Meta | Dict[str, Any] | None = None,
+        data: Dict[str, Any] | None = None,
+        params: Dict[str, Any] | None = None,
+        plotDefaults: Dict[str, Any] | None = None,
+        config: Dict[str, Any] | None = None,
+        view: Dict[str, Any] | None = None,
+        **extra: Any,
+    ) -> None:
+        self.meta = meta.to_dict() if hasattr(meta, "to_dict") else meta
+        self.data = data
+        self.params = params
+        self.plotDefaults = plotDefaults
+        self.config = config
+        self.view = view or {}
+        self.extra = extra
+
+    def to_dict(self) -> Dict[str, Any]:
+        base: Dict[str, Any] = {}
+        if self.meta:
+            base["meta"] = self.meta
+        if self.config:
+            base["config"] = self.config
+        if self.data:
+            base["data"] = self.data
+        if self.params:
+            base["params"] = self.params
+        if self.plotDefaults:
+            base["plotDefaults"] = self.plotDefaults
+        base.update(self.view)
+        base.update(omit_none(self.extra))
+        return base
+
+    def to_json(self, **kwargs: Any) -> str:
+        return json.dumps(self.to_dict(), **kwargs)
+
+
+def spec(
+    *,
+    meta: Meta | Dict[str, Any] | None = None,
+    data: Dict[str, Any] | None = None,
+    params: Dict[str, Any] | None = None,
+    plotDefaults: Dict[str, Any] | None = None,
+    config: Dict[str, Any] | None = None,
+    view: Dict[str, Any] | None = None,
+    **extra: Any,
+) -> Spec:
+    return Spec(
+        meta=meta,
+        data=data,
+        params=params,
+        plotDefaults=plotDefaults,
+        config=config,
+        view=view,
+        **extra,
+    )

vgplot-0.1.0/api/util.py

@@ -0,0 +1,14 @@
+from typing import Any, Dict
+
+
+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.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "vgplot"
+version = "0.1.0"
+description = "Schema wrapper classes for Mosaic"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "pyyaml",
+    "narwhals"
+]
+
+[project.urls]
+homepage = "https://github.com/uwdata/mosaic"
+
+[project.scripts]
+generate-schema-wrapper = "schema_wrapper.generate_schema_wrapper:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "jupyterlab>=4.2.5",
+    "mypy>=1.11.1",
+    "pytest>=7.4.4",
+    "pytest-cov",
+    "ruff>=0.6.1",
+    "pandas",
+    "mosaic-widget"
+]
+
+[tool.uv.sources]
+"mosaic-widget" = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["api", "schema_wrapper"]
+
+# https://mypy.readthedocs.io/en/stable/config_file.html
+[tool.mypy]
+files = "src/**/*.py"
+strict = false
+ignore_missing_imports = true