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

genome_spy/schemapi.py

@@ -0,0 +1,264 @@
+"""Runtime primitives for generated GenomeSpy schema wrappers.
+
+Unlike Altair, this small GenomeSpy-specific runtime is maintained directly in
+the installable package. Generation tooling imports it from generated classes
+but does not maintain a duplicate source copy.
+
+Portions are adapted from Vega-Altair's schema runtime:
+https://github.com/vega/altair/blob/main/altair/utils/schemapi.py
+Copyright (c) 2015-2025, Vega-Altair Developers. BSD-3-Clause license; see
+``LICENSES/ALTAIR-BSD-3-Clause.txt``.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+from typing import Any, ClassVar, Self
+
+from jsonschema import ValidationError
+from jsonschema.validators import validator_for
+
+
+class SchemaValidationError(ValueError):
+    """Report a generated-schema validation failure.
+
+    The error retains the original ``jsonschema`` failure and adds the wrapper
+    class and failing JSON path to the message.
+
+    Args:
+        schema_class: Wrapper class whose schema rejected the instance.
+        error: Original JSON Schema validation error.
+
+    Returns:
+        A contextual validation exception.
+
+    Raises:
+        No exceptions are raised during initialization.
+
+    Example:
+        ``SchemaValidationError(UnitSpec, error)``
+    """
+
+    def __init__(self, schema_class: type[SchemaBase], error: ValidationError) -> None:
+        self.schema_class = schema_class
+        self.original = error
+        path = ".".join(str(part) for part in error.absolute_path) or "<root>"
+        super().__init__(f"Invalid {schema_class.__name__} at {path}: {error.message}")
+
+
+class UndefinedType:
+    """Sentinel for properties omitted from a serialized spec."""
+
+    def __repr__(self) -> str:
+        return "Undefined"
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> UndefinedType:
+        """Preserve sentinel identity when schema state is deeply copied."""
+        del memo
+        return self
+
+
+Undefined = UndefinedType()
+
+
+class SchemaBase:
+    """Small base class for future generated GenomeSpy schema wrappers."""
+
+    _schema: ClassVar[dict[str, Any]] = {}
+    _rootschema: ClassVar[dict[str, Any]] = {}
+
+    def __init__(self, **kwds: Any) -> None:
+        self._kwds = kwds
+
+    def __getattr__(self, name: str) -> Any:
+        """Expose stored schema properties as attributes."""
+        if name == "_kwds":
+            raise AttributeError(name)
+        try:
+            return self._kwds[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+    def copy(self, *, deep: bool = True, **kwds: Any) -> Self:
+        """Return a copy with optional keyword updates."""
+        values = deepcopy(self._kwds) if deep else dict(self._kwds)
+        merged = {**values, **kwds}
+        return self.__class__(**merged)
+
+    def _with_property(
+        self, name: str, value: Any = Undefined, /, **kwargs: Any
+    ) -> Self:
+        """Return a shallow copy with one schema property updated."""
+        if kwargs:
+            if value is Undefined:
+                merged_value: Any = dict(kwargs)
+            elif value is None:
+                raise TypeError(f"Cannot merge keyword properties into null {name!r}.")
+            elif isinstance(value, SchemaBase):
+                merged_value = value.to_dict(validate=False)
+                merged_value.update(kwargs)
+            elif isinstance(value, dict):
+                merged_value = dict(value)
+                merged_value.update(kwargs)
+            else:
+                raise TypeError(f"Unsupported nested {name!r} value: {type(value)!r}")
+            return self.copy(deep=False, **{name: merged_value})
+        return self.copy(deep=False, **{name: value})
+
+    def to_dict(self, *, validate: bool = True) -> dict[str, Any]:
+        """Serialize this schema wrapper to a JSON-compatible dictionary."""
+        result = {
+            key: _todict(value)
+            for key, value in self._kwds.items()
+            if value is not Undefined
+        }
+        if validate:
+            try:
+                self.validate(result)
+            except ValidationError as error:
+                raise SchemaValidationError(type(self), error) from None
+        return result
+
+    def to_json(self, *, validate: bool = True) -> str:
+        """Serialize this schema wrapper to formatted JSON."""
+        return json.dumps(self.to_dict(validate=validate), indent=2)
+
+    @classmethod
+    def validate(cls, instance: dict[str, Any]) -> None:
+        """Validate an instance against this wrapper's schema."""
+        rootschema = cls._rootschema or cls._schema
+        validator_class = validator_for(rootschema)
+        validator_class.check_schema(rootschema)
+        validator = validator_class(rootschema).evolve(schema=cls._schema)
+        validator.validate(instance)
+
+    @classmethod
+    def resolve_references(cls) -> dict[str, Any]:
+        """Return this class schema with referenced properties merged in."""
+        rootschema = cls._rootschema or cls._schema
+        return _resolve_schema_references(cls._schema, rootschema)
+
+
+def _todict(value: Any) -> Any:
+    return normalize_schema_value(value, validate=True)
+
+
+def normalize_schema_value(value: Any, *, validate: bool = False) -> Any:
+    """Recursively convert schema wrappers into plain Python values."""
+    if isinstance(value, str):
+        return str(value)
+    if isinstance(value, SchemaBase):
+        return value.to_dict(validate=validate)
+    if isinstance(value, list | tuple):
+        return [normalize_schema_value(item, validate=validate) for item in value]
+    if isinstance(value, dict):
+        return {
+            key: normalize_schema_value(item, validate=validate)
+            for key, item in value.items()
+            if item is not Undefined
+        }
+    return value
+
+
+def normalize_mapping_value(
+    value: SchemaBase | dict[str, Any],
+    *,
+    key: str,
+    validate: bool = False,
+) -> dict[str, Any]:
+    """Convert a schema wrapper or mapping into a plain mapping."""
+    normalized = normalize_schema_value(value, validate=validate)
+    if not isinstance(normalized, dict):
+        raise TypeError(f"Unsupported nested {key!r} value: {type(value)!r}")
+    return normalized
+
+
+def merge_mapping_value(
+    current: Any,
+    key: str,
+    value: Any = Undefined,
+    /,
+    **kwargs: Any,
+) -> Any:
+    """Merge a nested schema object using builder-style semantics."""
+    if value is Undefined:
+        if current is Undefined or current is None:
+            return dict(kwargs)
+        if isinstance(current, SchemaBase | dict):
+            merged = normalize_mapping_value(current, key=key, validate=False)
+            merged.update(kwargs)
+            return merged
+        raise TypeError(f"Cannot merge {key!r} into non-mapping value.")
+
+    if value is None:
+        if kwargs:
+            raise TypeError(f"Cannot merge keyword properties into null {key!r}.")
+        return None
+
+    merged = normalize_mapping_value(value, key=key, validate=False)
+    if kwargs:
+        merged.update(kwargs)
+    return merged
+
+
+def _ref_name(schema: dict[str, Any]) -> str | None:
+    ref = schema.get("$ref")
+    if not isinstance(ref, str):
+        return None
+    return ref.split("/")[-1]
+
+
+def _resolve_schema_references(
+    schema: dict[str, Any],
+    rootschema: dict[str, Any],
+    *,
+    seen: frozenset[str] = frozenset(),
+) -> dict[str, Any]:
+    ref_name = _ref_name(schema)
+    if ref_name is not None:
+        definitions = rootschema.get("definitions", {})
+        if not isinstance(definitions, dict) or ref_name in seen:
+            return {}
+        target = definitions.get(ref_name)
+        if not isinstance(target, dict):
+            return {}
+        return _resolve_schema_references(
+            target,
+            rootschema,
+            seen=seen | {ref_name},
+        )
+
+    resolved = dict(schema)
+    properties: dict[str, Any] = {}
+    own_properties = schema.get("properties", {})
+    if isinstance(own_properties, dict):
+        properties.update(own_properties)
+    for key in ("anyOf", "oneOf", "allOf"):
+        variants = schema.get(key, [])
+        if not isinstance(variants, list):
+            continue
+        for variant in variants:
+            if not isinstance(variant, dict):
+                continue
+            variant_properties = _resolve_schema_references(
+                variant,
+                rootschema,
+                seen=seen,
+            ).get("properties", {})
+            if isinstance(variant_properties, dict):
+                properties.update(variant_properties)
+    if properties:
+        resolved["properties"] = properties
+    return resolved
+
+
+__all__ = [
+    "merge_mapping_value",
+    "normalize_mapping_value",
+    "normalize_schema_value",
+    "SchemaBase",
+    "SchemaValidationError",
+    "Undefined",
+    "UndefinedType",
+]

genome_spy/static/widget.js

@@ -0,0 +1,345 @@
+export function datasetApi(api, descriptor) {
+  if (!descriptor.scoped) {
+    return api.datasets;
+  }
+  if (!descriptor.owner) {
+    throw new Error(
+      `Dataset "${descriptor.name}" belongs to an unnamed nested view.`
+    );
+  }
+  const owner = api.views?.get({ scope: [], view: descriptor.owner });
+  if (!owner) {
+    throw new Error(
+      `Could not find the view that declares dataset "${descriptor.name}".`
+    );
+  }
+  return owner.datasets;
+}
+
+export function setLoading(el, loading) {
+  if (el.style) {
+    el.style.visibility = loading ? "hidden" : "";
+  }
+}
+
+export async function mountControls({
+  container,
+  api,
+  names,
+  definitions,
+  moduleUrls,
+}) {
+  if (!names.length) {
+    return null;
+  }
+
+  const controlsModule = await import(moduleUrls.core);
+  const modules = { core: controlsModule };
+  const controls = [];
+  for (const name of names) {
+    const definition = definitions[name];
+    if (!definition) {
+      throw new Error(`Control ${name} has no definition.`);
+    }
+    if (!modules[definition.module]) {
+      const moduleUrl = moduleUrls[definition.module];
+      if (!moduleUrl) {
+        throw new Error(`Control module ${definition.module} has no URL.`);
+      }
+      modules[definition.module] = await import(moduleUrl);
+    }
+    const factory = modules[definition.module][definition.export];
+    if (typeof factory !== "function") {
+      throw new Error(`Control ${name} is unavailable.`);
+    }
+    controls.push(factory());
+  }
+
+  if (typeof controlsModule.attachControls !== "function") {
+    throw new Error("GenomeSpy attachControls export was not found.");
+  }
+  return controlsModule.attachControls(container, api, { controls });
+}
+
+export async function renderChart({ model, el, signal }) {
+  if (!model.get("spec")) {
+    el.textContent = "No GenomeSpy specification provided.";
+    return;
+  }
+
+  let api = null;
+  let mountedControls = null;
+  let parameterSubscriptions = [];
+  let renderRevision = 0;
+  let syncingParameterValues = false;
+  const datasetListeners = [];
+  const activeErrors = new Map();
+
+  const publishErrors = () => {
+    model.set("error", [...activeErrors.values()].join("\n"));
+    model.save_changes();
+  };
+
+  const setError = (error, source = "runtime") => {
+    activeErrors.delete(source);
+    activeErrors.set(source, String(error));
+    publishErrors();
+  };
+
+  const clearError = (source) => {
+    if (activeErrors.delete(source)) {
+      publishErrors();
+    }
+  };
+
+  const disposeCurrent = ({ reportErrors = true } = {}) => {
+    const controls = mountedControls;
+    const currentApi = api;
+    mountedControls = null;
+    api = null;
+    const errors = [];
+    try {
+      controls?.dispose?.();
+    } catch (error) {
+      errors.push(error);
+    }
+    try {
+      currentApi?.finalize?.();
+    } catch (error) {
+      errors.push(error);
+    }
+    if (errors.length && reportErrors) {
+      setError(errors.map(String).join("\n"), "cleanup");
+    } else if (!errors.length) {
+      clearError("cleanup");
+    } else {
+      console.error("GenomeSpy cleanup failed", ...errors);
+    }
+  };
+
+  const publishParameterValue = (name, value) => {
+    const values = { ...(model.get("parameter_values") || {}) };
+    values[name] = value;
+    syncingParameterValues = true;
+    model.set("parameter_values", values);
+    model.save_changes();
+    syncingParameterValues = false;
+  };
+
+  const clearInteractions = () => {
+    for (const unsubscribe of parameterSubscriptions) {
+      unsubscribe();
+    }
+    parameterSubscriptions = [];
+  };
+
+  const attachInteractions = () => {
+    if (!api) {
+      return;
+    }
+    clearInteractions();
+
+    for (const name of model.get("parameter_names") || []) {
+      try {
+        const parameter = api.getParam(name);
+        const values = model.get("parameter_values") || {};
+        if (Object.prototype.hasOwnProperty.call(values, name)) {
+          parameter.setValue(values[name]);
+        }
+        parameterSubscriptions.push(
+          parameter.subscribe((value) => publishParameterValue(name, value))
+        );
+        publishParameterValue(name, parameter.getValue());
+      } catch (error) {
+        setError(error);
+      }
+    }
+
+    if (model.get("enable_click_events")) {
+      const interactionApi = api;
+      const onClick = (event) => {
+        const datum = event?.datum;
+        model.set("clicked_datum", datum && typeof datum === "object" ? datum : {});
+        model.set("click_revision", (model.get("click_revision") || 0) + 1);
+        model.save_changes();
+      };
+      interactionApi.addEventListener("click", onClick);
+      parameterSubscriptions.push(() =>
+        interactionApi.removeEventListener("click", onClick)
+      );
+    }
+  };
+
+  const onParameterValuesChange = () => {
+    if (syncingParameterValues || !api) {
+      return;
+    }
+    const values = model.get("parameter_values") || {};
+    for (const name of model.get("parameter_names") || []) {
+      if (!Object.prototype.hasOwnProperty.call(values, name)) {
+        continue;
+      }
+      try {
+        api.getParam(name).setValue(values[name]);
+      } catch (error) {
+        setError(error);
+      }
+    }
+  };
+
+  const applyDataset = async (descriptor) => {
+    const errorSource = `dataset:${descriptor.revision_trait}`;
+    const revision = model.get(descriptor.revision_trait) || 0;
+    const currentApi = api;
+    const currentRender = renderRevision;
+    if (!currentApi || revision === 0) {
+      return;
+    }
+
+    const payload = model.get(descriptor.payload_trait);
+    const format = model.get(descriptor.format_trait);
+    try {
+      const datasets = datasetApi(currentApi, descriptor);
+      if (format === "arrow") {
+        await datasets.load(descriptor.name, payload, { type: "arrow" });
+      } else if (format === "records") {
+        datasets.set(descriptor.name, payload);
+      } else {
+        throw new Error(`Unsupported dataset format: ${String(format)}`);
+      }
+      if (
+        signal.aborted ||
+        api !== currentApi ||
+        renderRevision !== currentRender ||
+        model.get(descriptor.revision_trait) !== revision
+      ) {
+        return;
+      }
+      clearError(errorSource);
+    } catch (error) {
+      if (
+        !signal.aborted &&
+        api === currentApi &&
+        renderRevision === currentRender &&
+        model.get(descriptor.revision_trait) === revision
+      ) {
+        setError(error, errorSource);
+      }
+    }
+  };
+
+  const renderSpec = async () => {
+    const revision = ++renderRevision;
+    const moduleUrl = model.get("bundle_url");
+    const options = model.get("embed_options") || {};
+    const controlNames = model.get("controls") || [];
+    const datasets = model.get("dataset_manifest") || [];
+    const hasInitialData = datasets.some(
+      (descriptor) => (model.get(descriptor.revision_trait) || 0) > 0
+    );
+
+    disposeCurrent();
+    setLoading(el, hasInitialData);
+    el.replaceChildren();
+
+    try {
+      const module = await import(moduleUrl);
+      const embed = module.embed ?? module.default?.embed ?? module.default;
+      if (typeof embed !== "function") {
+        throw new Error("GenomeSpy embed export was not found.");
+      }
+      const nextApi = await embed(el, model.get("spec"), options);
+      if (revision !== renderRevision || signal.aborted) {
+        nextApi?.finalize?.();
+        return;
+      }
+      api = nextApi;
+      clearError("render");
+      try {
+        const nextControls = await mountControls({
+          container: el,
+          api: nextApi,
+          names: controlNames,
+          definitions: model.get("_control_definitions") || {},
+          moduleUrls: {
+            core: model.get("controls_module_url"),
+            inspector: model.get("inspector_module_url"),
+          },
+        });
+        if (revision !== renderRevision || signal.aborted || api !== nextApi) {
+          try {
+            nextControls?.dispose?.();
+          } catch (error) {
+            console.error("GenomeSpy controls cleanup failed", error);
+          }
+          return;
+        }
+        mountedControls = nextControls;
+        clearError("controls");
+      } catch (error) {
+        if (revision === renderRevision && !signal.aborted && api === nextApi) {
+          setError(
+            `GenomeSpy controls failed to load: ${String(error)}`,
+            "controls"
+          );
+        }
+      }
+      attachInteractions();
+      await Promise.all(datasets.map((descriptor) => applyDataset(descriptor)));
+      if (revision === renderRevision && !signal.aborted) {
+        setLoading(el, false);
+      }
+    } catch (error) {
+      if (revision !== renderRevision || signal.aborted) {
+        return;
+      }
+      setLoading(el, false);
+      setError(error, "render");
+      throw error;
+    }
+  };
+
+  const onSpecChange = () => void renderSpec();
+
+  model.on("change:spec", onSpecChange);
+  model.on("change:bundle_url", onSpecChange);
+  model.on("change:embed_options", onSpecChange);
+  model.on("change:controls", onSpecChange);
+  model.on("change:controls_module_url", onSpecChange);
+  model.on("change:inspector_module_url", onSpecChange);
+  model.on("change:parameter_values", onParameterValuesChange);
+  model.on("change:parameter_names", attachInteractions);
+  model.on("change:enable_click_events", attachInteractions);
+  for (const descriptor of model.get("dataset_manifest") || []) {
+    const listener = () => void applyDataset(descriptor);
+    const event = `change:${descriptor.payload_trait}`;
+    model.on(event, listener);
+    datasetListeners.push([event, listener]);
+  }
+
+  signal.addEventListener("abort", () => {
+    renderRevision += 1;
+    model.off("change:spec", onSpecChange);
+    model.off("change:bundle_url", onSpecChange);
+    model.off("change:embed_options", onSpecChange);
+    model.off("change:controls", onSpecChange);
+    model.off("change:controls_module_url", onSpecChange);
+    model.off("change:inspector_module_url", onSpecChange);
+    model.off("change:parameter_values", onParameterValuesChange);
+    model.off("change:parameter_names", attachInteractions);
+    model.off("change:enable_click_events", attachInteractions);
+    for (const [event, listener] of datasetListeners) {
+      model.off(event, listener);
+    }
+    try {
+      clearInteractions();
+    } finally {
+      disposeCurrent({ reportErrors: false });
+      setLoading(el, false);
+    }
+  });
+
+  await renderSpec();
+}
+
+export default { render: renderChart };