genome-spy-python 0.1.0__py3-none-any.whl

genome_spy/_render.py

@@ -0,0 +1,207 @@
+"""Private render-time preparation for binary dataframe transport."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+from hashlib import sha256
+from typing import Any, Callable, Literal, Protocol
+
+from genome_spy._chart_authoring import normalize_data
+from genome_spy.arrow import _try_to_arrow_ipc
+from genome_spy.data_transformers import (
+    _consolidate,
+    _data_slots,
+    _DatasetConsolidation,
+    data_transformers,
+)
+from genome_spy.schema import Root
+
+
+@dataclass(frozen=True, slots=True)
+class _PreparedSpec:
+    """A JSON-ready spec and the binary Arrow payloads it references."""
+
+    spec: dict[str, Any]
+    buffers: dict[str, bytes]
+    consolidate_datasets: bool | None = None
+
+
+_DatasetFormat = Literal["arrow", "records"]
+
+
+@dataclass(frozen=True, slots=True)
+class _LiveDataset:
+    """One named dataset synchronized by a live notebook widget."""
+
+    name: str
+    owner: str | None
+    scoped: bool
+    initial_payload: bytes | None
+    initial_format: _DatasetFormat | None
+
+
+@dataclass(frozen=True, slots=True)
+class _PreparedWidget:
+    """A runtime spec and its live named-dataset declarations."""
+
+    spec: dict[str, Any]
+    datasets: tuple[_LiveDataset, ...]
+
+
+class _RenderSerializable(Protocol):
+    """Structural type for charts using the shared serialization traversal."""
+
+    def _to_dict(
+        self,
+        *,
+        include_schema: bool,
+        validate: bool,
+        normalize_chart_data: Callable[[Any], Any],
+    ) -> dict[str, Any]: ...
+
+
+@dataclass(slots=True)
+class _RenderContext:
+    """State shared by one render-preparation traversal."""
+
+    buffers: dict[str, bytes] = field(default_factory=dict)
+    _table_cache: dict[int, tuple[Any, dict[str, Any]]] = field(default_factory=dict)
+
+    def normalize_data(self, data: Any) -> Any:
+        """Return JSON data or a content-addressed Arrow data source."""
+        cached = self._table_cache.get(id(data))
+        if cached is not None and cached[0] is data:
+            return dict(cached[1])
+
+        payload = _try_to_arrow_ipc(data)
+        if payload is None:
+            return normalize_data(data)
+
+        identifier = sha256(payload).hexdigest()
+        self.buffers.setdefault(identifier, payload)
+        normalized = {"url": f"arrow://{identifier}", "format": {"type": "arrow"}}
+        self._table_cache[id(data)] = (data, normalized)
+        return dict(normalized)
+
+
+def prepare_render(chart: _RenderSerializable) -> _PreparedSpec:
+    """Prepare one chart through its shared render-time serialization path."""
+    enabled = data_transformers.consolidate_datasets
+    context = _RenderContext()
+    collector = _DatasetConsolidation(chart) if enabled else None
+    spec = chart._to_dict(
+        include_schema=True,
+        validate=False,
+        normalize_chart_data=(
+            (lambda data: collector.source(context.normalize_data(data)))
+            if collector is not None
+            else context.normalize_data
+        ),
+    )
+    if collector is not None:
+        collector.finish(spec)
+    return _PreparedSpec(
+        spec=Root(**spec).to_dict(),
+        buffers=context.buffers,
+        consolidate_datasets=enabled,
+    )
+
+
+def prepare_widget(chart: _RenderSerializable) -> _PreparedWidget:
+    """Prepare a chart for live named-dataset widget updates."""
+    return prepare_widget_spec(prepare_render(chart))
+
+
+def prepare_widget_spec(prepared: _PreparedSpec) -> _PreparedWidget:
+    """Rewrite known eager sources in a prepared spec as named datasets."""
+    spec = deepcopy(prepared.spec)
+    enabled = prepared.consolidate_datasets
+    if enabled is None:
+        enabled = data_transformers.consolidate_datasets
+    if enabled:
+        _consolidate(spec)
+    root_datasets = spec.setdefault("datasets", {})
+    if not isinstance(root_datasets, dict):
+        raise TypeError("GenomeSpy root datasets must be a mapping.")
+
+    slots = [
+        (kind, dict(value) if kind == "datasets" else value, owner, scoped)
+        for kind, value, owner, scoped in _data_slots(spec)
+        if kind != "template"
+    ]
+    used_names: set[str] = set()
+    # Template references also reserve names, but their declarations belong to
+    # future import instances and must not be registered as live root datasets.
+    for kind, value, _, _ in _data_slots(spec, include_templates=True):
+        if kind == "datasets":
+            used_names.update(value)
+        elif kind == "data" and isinstance(value.get("name"), str):
+            used_names.add(value["name"])
+    generated_names: dict[str, str] = {}
+    datasets: list[_LiveDataset] = []
+
+    def register(
+        name: str,
+        *,
+        owner: str | None,
+        scoped: bool,
+        initial_payload: bytes | None = None,
+        initial_format: _DatasetFormat | None = None,
+    ) -> None:
+        datasets.append(
+            _LiveDataset(
+                name=name,
+                owner=owner,
+                scoped=scoped,
+                initial_payload=initial_payload,
+                initial_format=initial_format,
+            )
+        )
+
+    def generated_name(token: str) -> str:
+        existing = generated_names.get(token)
+        if existing is not None:
+            return existing
+        index = len(generated_names)
+        candidate = f"__genome_spy_python_data_{index}"
+        while candidate in used_names:
+            index += 1
+            candidate = f"__genome_spy_python_data_{index}"
+        used_names.add(candidate)
+        generated_names[token] = candidate
+        return candidate
+
+    for kind, data, owner, scoped in slots:
+        if kind == "datasets":
+            for name in data:
+                if isinstance(name, str) and name:
+                    register(name, owner=owner, scoped=scoped)
+        else:
+            url = data.get("url")
+            if isinstance(url, str) and url.startswith("arrow://"):
+                token = url.removeprefix("arrow://")
+                payload = prepared.buffers.get(token)
+                if payload is None:
+                    raise ValueError(f"No Arrow IPC payload provided for {token}.")
+                name = generated_name(
+                    token if enabled else f"{token}:{len(generated_names)}"
+                )
+                if name not in root_datasets:
+                    root_datasets[name] = []
+                    register(
+                        name,
+                        owner=None,
+                        scoped=False,
+                        initial_payload=payload,
+                        initial_format="arrow",
+                    )
+                data.clear()
+                data["name"] = name
+            elif set(data) == {"values"} and isinstance(data["values"], list):
+                name = generated_name(f"records:{len(generated_names)}")
+                root_datasets[name] = data["values"]
+                register(name, owner=None, scoped=False)
+                data.clear()
+                data["name"] = name
+    return _PreparedWidget(spec=spec, datasets=tuple(datasets))

genome_spy/_utils.py

@@ -0,0 +1,75 @@
+"""Internal helpers for the first GenomeSpy Python API slice."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+TYPE_ALIASES: dict[str, str] = {
+    "q": "quantitative",
+    "quantitative": "quantitative",
+    "n": "nominal",
+    "nominal": "nominal",
+    "o": "ordinal",
+    "ordinal": "ordinal",
+    "i": "index",
+    "index": "index",
+    "g": "locus",
+    "l": "locus",
+    "locus": "locus",
+}
+
+
+def compact_json(data: Any) -> str:
+    """Serialize JSON using stable, notebook-friendly formatting."""
+    return json.dumps(data, separators=(",", ":"), sort_keys=True)
+
+
+def pretty_json(data: Any) -> str:
+    """Serialize JSON for user-facing export."""
+    return json.dumps(data, indent=2)
+
+
+class JsonSpec(dict[str, Any]):
+    """Dict-like object whose display representation is valid JSON."""
+
+    def __repr__(self) -> str:
+        return pretty_json(self)
+
+    def __str__(self) -> str:
+        return pretty_json(self)
+
+    def _repr_pretty_(self, printer: Any, cycle: bool) -> None:
+        """Pretty-print JSON in IPython/Jupyter text output."""
+        if cycle:
+            printer.text("JsonSpec(...)")
+            return
+        printer.text(pretty_json(self))
+
+    def _repr_mimebundle_(
+        self,
+        include: object | None = None,
+        exclude: object | None = None,
+    ) -> dict[str, str]:
+        """Display as indented JSON text in notebook frontends."""
+        del include, exclude
+        return {"text/plain": pretty_json(self)}
+
+
+def is_mapping(value: Any) -> bool:
+    """Return whether ``value`` behaves like a mapping."""
+    return isinstance(value, Mapping)
+
+
+def parse_shorthand(shorthand: str) -> dict[str, Any]:
+    """Parse a compact ``field:type`` channel shorthand."""
+    field, separator, channel_type = shorthand.rpartition(":")
+    if not separator:
+        return {"field": shorthand}
+
+    normalized_type = TYPE_ALIASES.get(channel_type.lower())
+    if normalized_type is None:
+        return {"field": shorthand}
+
+    return {"field": field, "type": normalized_type}

genome_spy/_widget.py

@@ -0,0 +1,262 @@
+"""Anywidget-backed notebook renderer for GenomeSpy charts."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any, Literal, cast
+
+import anywidget
+import traitlets
+
+from genome_spy._embed import (
+    DEFAULT_CONTROLS,
+    DEFAULT_CONTROLS_MODULE_URL,
+    DEFAULT_EMBED_URL,
+    DEFAULT_INSPECTOR_MODULE_URL,
+    Controls,
+    control_definitions,
+    normalize_controls,
+)
+from genome_spy._chart_authoring import json_safe, records_from_data
+from genome_spy._render import _PreparedSpec, prepare_widget_spec
+from genome_spy.arrow import to_arrow_ipc
+from genome_spy.schemapi import Undefined, UndefinedType
+
+_ESM_PATH = Path(__file__).with_name("static") / "widget.js"
+_DatasetFormat = Literal["arrow", "records"]
+
+
+class JupyterChart(anywidget.AnyWidget):
+    """A lightweight anywidget wrapper around GenomeSpy's ``embed`` API."""
+
+    _esm = _ESM_PATH
+
+    spec = traitlets.Dict().tag(sync=True)
+    bundle_url = traitlets.Unicode(DEFAULT_EMBED_URL).tag(sync=True)
+    embed_options = traitlets.Dict(default_value={}).tag(sync=True)
+    controls = traitlets.List(
+        trait=traitlets.Unicode(), default_value=list[str](DEFAULT_CONTROLS)
+    ).tag(sync=True)
+    _control_definitions = traitlets.Dict(default_value=control_definitions()).tag(
+        sync=True
+    )
+    controls_module_url = traitlets.Unicode(DEFAULT_CONTROLS_MODULE_URL).tag(sync=True)
+    inspector_module_url = traitlets.Unicode(DEFAULT_INSPECTOR_MODULE_URL).tag(
+        sync=True
+    )
+    dataset_manifest = traitlets.List(trait=traitlets.Dict(), default_value=[]).tag(
+        sync=True
+    )
+    parameter_names = traitlets.List(trait=traitlets.Unicode(), default_value=[]).tag(
+        sync=True
+    )
+    parameter_values = traitlets.Dict(default_value={}).tag(sync=True)
+    enable_click_events = traitlets.Bool(False).tag(sync=True)
+    clicked_datum = traitlets.Dict(default_value={}).tag(sync=True)
+    click_revision = traitlets.Int(0).tag(sync=True)
+    error = traitlets.Unicode("").tag(sync=True)
+
+    def __init__(
+        self,
+        chart: Any,
+        *,
+        bundle_url: str = DEFAULT_EMBED_URL,
+        embed_options: dict[str, Any] | None = None,
+        controls: Controls | UndefinedType = Undefined,
+        controls_module_url: str = DEFAULT_CONTROLS_MODULE_URL,
+        inspector_module_url: str = DEFAULT_INSPECTOR_MODULE_URL,
+        parameter_names: Sequence[str] = (),
+        parameter_values: Mapping[str, Any] | None = None,
+        enable_click_events: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        if hasattr(chart, "_prepare_widget"):
+            prepared = chart._prepare_widget()
+        else:
+            prepared = prepare_widget_spec(_PreparedSpec(spec=dict(chart), buffers={}))
+
+        manifest: list[dict[str, Any]] = []
+        for index, dataset in enumerate(prepared.datasets):
+            prefix = f"_dataset_{index}"
+            manifest.append(
+                {
+                    "name": dataset.name,
+                    "owner": dataset.owner,
+                    "scoped": dataset.scoped,
+                    "payload_trait": f"{prefix}_payload",
+                    "format_trait": f"{prefix}_format",
+                    "revision_trait": f"{prefix}_revision",
+                    "initial_payload": dataset.initial_payload,
+                    "initial_format": dataset.initial_format,
+                }
+            )
+
+        super().__init__(
+            spec=prepared.spec,
+            bundle_url=bundle_url,
+            embed_options=embed_options or {},
+            controls=list(normalize_controls(controls)),
+            controls_module_url=controls_module_url,
+            inspector_module_url=inspector_module_url,
+            dataset_manifest=[self._manifest_entry(entry) for entry in manifest],
+            parameter_names=list(parameter_names),
+            parameter_values=dict(parameter_values or {}),
+            enable_click_events=enable_click_events,
+            **kwargs,
+        )
+
+        for entry in manifest:
+            initial_payload = entry["initial_payload"]
+            initial_format = entry["initial_format"] or "records"
+            self.add_traits(
+                **{
+                    entry["payload_trait"]: traitlets.Any(initial_payload).tag(
+                        sync=True
+                    ),
+                    entry["format_trait"]: traitlets.Unicode(initial_format).tag(
+                        sync=True
+                    ),
+                    entry["revision_trait"]: traitlets.Int(
+                        1 if initial_payload is not None else 0
+                    ).tag(sync=True),
+                }
+            )
+
+    @property
+    def dataset_names(self) -> tuple[str, ...]:
+        """Return live dataset names in declaration order.
+
+        Description:
+            Names are taken from the widget's fixed runtime dataset manifest.
+            Repeated names indicate scoped declarations and require a unique
+            name before they can be addressed through :meth:`set_dataset`.
+
+        Returns:
+            Dataset names in declaration order.
+
+        Raises:
+            No exceptions are raised directly here.
+
+        Example:
+            >>> chart.widget().dataset_names
+            ('table',)
+        """
+        return tuple(str(entry["name"]) for entry in self.dataset_manifest)
+
+    def set_dataset(
+        self,
+        name: str,
+        data: object,
+        *,
+        format: _DatasetFormat = "arrow",
+    ) -> None:
+        """Replace one declared live dataset without recreating GenomeSpy.
+
+        Description:
+            Arrow is the default and transfers supported dataframe/table inputs
+            as a binary AnyWidget buffer. Use ``format="records"`` only for
+            ordinary JSON-compatible record lists.
+
+        Args:
+            name: Declared dataset name.
+            data: Table or records used as the replacement value.
+            format: Transport format, either ``"arrow"`` or ``"records"``.
+
+        Returns:
+            ``None`` after the synchronized transport state has been updated.
+
+        Raises:
+            KeyError: If no declared dataset has ``name``.
+            ValueError: If ``name`` is ambiguous or cannot be addressed.
+            TypeError: If ``data`` cannot be serialized using ``format``.
+
+        Example:
+            >>> view.set_dataset('table', dataframe)
+        """
+        entry = self._dataset_entry(name)
+        payload = self._serialize_dataset(data, format)
+        revision_trait = cast(str, entry["revision_trait"])
+        with self.hold_sync():
+            setattr(self, cast(str, entry["payload_trait"]), payload)
+            setattr(self, cast(str, entry["format_trait"]), format)
+            setattr(self, revision_trait, getattr(self, revision_trait) + 1)
+
+    def set_data(
+        self,
+        data: object,
+        *,
+        format: _DatasetFormat = "arrow",
+    ) -> None:
+        """Replace the only declared live dataset.
+
+        Description:
+            This is a convenience alias for :meth:`set_dataset` when the widget
+            has exactly one live dataset.
+
+        Args:
+            data: Table or records used as the replacement value.
+            format: Transport format, either ``"arrow"`` or ``"records"``.
+
+        Returns:
+            ``None`` after the synchronized transport state has been updated.
+
+        Raises:
+            ValueError: If the widget has zero or multiple live datasets.
+            TypeError: If ``data`` cannot be serialized using ``format``.
+
+        Example:
+            >>> view.set_data(dataframe)
+        """
+        if len(self.dataset_manifest) != 1:
+            names = ", ".join(self.dataset_names) or "none"
+            raise ValueError(
+                "set_data() requires exactly one live dataset; "
+                f"available datasets: {names}."
+            )
+        self.set_dataset(str(self.dataset_manifest[0]["name"]), data, format=format)
+
+    def _dataset_entry(self, name: str) -> dict[str, Any]:
+        """Return the unambiguous manifest entry for a public dataset name."""
+        matches = [entry for entry in self.dataset_manifest if entry["name"] == name]
+        if not matches:
+            available = ", ".join(self.dataset_names) or "none"
+            raise KeyError(
+                f"Unknown dataset {name!r}. Available datasets: {available}."
+            )
+        if len(matches) != 1:
+            raise ValueError(
+                f"Dataset {name!r} is declared in multiple scopes and cannot be "
+                "addressed by name alone."
+            )
+        entry = dict(matches[0])
+        if entry["scoped"] and entry["owner"] is None:
+            raise ValueError(
+                f"Dataset {name!r} is declared in an unnamed nested view. "
+                "Give its owner view a unique name before updating it."
+            )
+        return entry
+
+    @staticmethod
+    def _manifest_entry(entry: Mapping[str, Any]) -> dict[str, Any]:
+        """Return synchronized metadata without Python-only initial values."""
+        return {
+            key: value
+            for key, value in entry.items()
+            if key not in {"initial_payload", "initial_format"}
+        }
+
+    @staticmethod
+    def _serialize_dataset(data: object, format: _DatasetFormat) -> bytes | list[Any]:
+        """Serialize one dataset before mutating synchronized trait state."""
+        if format == "arrow":
+            return to_arrow_ipc(data)
+        if format == "records":
+            records = records_from_data(data)
+            if records is None:
+                raise TypeError(
+                    "Record transport requires a list of records or a supported "
+                    "table with record conversion."
+                )
+            return cast(list[Any], json_safe(records))
+        raise ValueError(f"Unsupported dataset format {format!r}.")