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

genome_spy/_expressions.py

@@ -0,0 +1,271 @@
+"""Python authoring primitives for GenomeSpy expressions.
+
+The operator model follows Vega-Altair's expression API while keeping the
+serialized value a real ``str`` subclass. As a result, generated schema
+signatures that accept expression strings also accept ``Expression`` objects
+without transform-specific adapters or normalization rules.
+
+Portions are adapted from Vega-Altair's expression runtime:
+https://github.com/vega/altair/blob/main/altair/expr/core.py
+Copyright (c) 2015-2025, Vega-Altair Developers. BSD-3-Clause license; see
+``LICENSES/ALTAIR-BSD-3-Clause.txt``.
+"""
+
+from __future__ import annotations
+
+import sys
+from math import isinf, isnan
+from typing import Any, Protocol, Self, TypeAlias, runtime_checkable
+
+
+@runtime_checkable
+class ExpressionOperand(Protocol):
+    """A value that can provide a GenomeSpy expression reference."""
+
+    def _to_expr(self) -> Expression:
+        """Return this value's expression representation."""
+
+
+def _js_repr(value: Any) -> str:
+    """Return a JavaScript-safe expression representation."""
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if value is None:
+        return "null"
+    if isinstance(value, ExpressionOperand):
+        return str(value._to_expr())
+    if isinstance(value, float):
+        if isnan(value):
+            return "NaN"
+        if isinf(value):
+            return "Infinity" if value > 0 else "-Infinity"
+    if isinstance(value, list | tuple):
+        return "[" + ",".join(_js_repr(item) for item in value) + "]"
+    if isinstance(value, dict):
+        items = (f"{_js_repr(key)}:{_js_repr(item)}" for key, item in value.items())
+        return "{" + ",".join(items) + "}"
+    numpy = sys.modules.get("numpy")
+    if numpy is not None and isinstance(value, numpy.generic):
+        return _js_repr(value.item())
+    return repr(value)
+
+
+def _expression_string(value: str | ExpressionOperand) -> str:
+    """Return the string accepted by an upstream expression property."""
+    if isinstance(value, ExpressionOperand):
+        return str(value._to_expr())
+    return value
+
+
+def _function_expression(name: str, *arguments: Any) -> Expression:
+    """Build a function-call expression."""
+    rendered = ",".join(_js_repr(argument) for argument in arguments)
+    return Expression(f"{name}({rendered})")
+
+
+class ExpressionOperatorMixin:
+    """Python operators shared by expression strings and parameter handles."""
+
+    __hash__ = None  # type: ignore[assignment]
+
+    def _to_expr(self) -> Expression:
+        raise NotImplementedError
+
+    def __bool__(self) -> bool:
+        raise TypeError(
+            "GenomeSpy expressions cannot be converted to bool; use &, |, and ~ "
+            "instead of Python's and, or, and not."
+        )
+
+    def __getattr__(self, name: str) -> Expression:
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+        return Expression(f"{self._to_expr()}.{name}")
+
+    def __getitem__(self, key: Any) -> Expression:
+        return Expression(f"{self._to_expr()}[{_js_repr(key)}]")
+
+    def _binary(self, operator: str, other: Any) -> Expression:
+        return Expression(f"({self._to_expr()} {operator} {_js_repr(other)})")
+
+    def _reverse_binary(self, operator: str, other: Any) -> Expression:
+        return Expression(f"({_js_repr(other)} {operator} {self._to_expr()})")
+
+    def __add__(self, other: Any) -> Expression:
+        return self._binary("+", other)
+
+    def __radd__(self, other: Any) -> Expression:
+        return self._reverse_binary("+", other)
+
+    def __sub__(self, other: Any) -> Expression:
+        return self._binary("-", other)
+
+    def __rsub__(self, other: Any) -> Expression:
+        return self._reverse_binary("-", other)
+
+    def __mul__(self, other: Any) -> Expression:
+        return self._binary("*", other)
+
+    def __rmul__(self, other: Any) -> Expression:
+        return self._reverse_binary("*", other)
+
+    def __truediv__(self, other: Any) -> Expression:
+        return self._binary("/", other)
+
+    def __rtruediv__(self, other: Any) -> Expression:
+        return self._reverse_binary("/", other)
+
+    def __mod__(self, other: Any) -> Expression:
+        return self._binary("%", other)
+
+    def __rmod__(self, other: Any) -> Expression:
+        return self._reverse_binary("%", other)
+
+    def __pow__(self, other: Any) -> Expression:
+        return _function_expression("pow", self, other)
+
+    def __rpow__(self, other: Any) -> Expression:
+        return _function_expression("pow", other, self)
+
+    def __neg__(self) -> Expression:
+        return Expression(f"(-{self._to_expr()})")
+
+    def __pos__(self) -> Expression:
+        return Expression(f"(+{self._to_expr()})")
+
+    def __eq__(self, other: object) -> Expression:  # type: ignore[override]
+        return self._binary("===", other)
+
+    def __ne__(self, other: object) -> Expression:  # type: ignore[override]
+        return self._binary("!==", other)
+
+    def __lt__(self, other: Any) -> Expression:
+        return self._binary("<", other)
+
+    def __le__(self, other: Any) -> Expression:
+        return self._binary("<=", other)
+
+    def __gt__(self, other: Any) -> Expression:
+        return self._binary(">", other)
+
+    def __ge__(self, other: Any) -> Expression:
+        return self._binary(">=", other)
+
+    def __and__(self, other: Any) -> Expression:
+        return self._binary("&&", other)
+
+    def __rand__(self, other: Any) -> Expression:
+        return self._reverse_binary("&&", other)
+
+    def __or__(self, other: Any) -> Expression:
+        return self._binary("||", other)
+
+    def __ror__(self, other: Any) -> Expression:
+        return self._reverse_binary("||", other)
+
+    def __invert__(self) -> Expression:
+        return Expression(f"(!{self._to_expr()})")
+
+    def __abs__(self) -> Expression:
+        return _function_expression("abs", self)
+
+
+class Expression(ExpressionOperatorMixin, str):  # type: ignore[misc]
+    """A composable GenomeSpy expression string.
+
+    Python operators build the JavaScript-like expression syntax understood by
+    GenomeSpy. The class remains a string for direct compatibility with every
+    generated schema property whose upstream type is ``string``.
+
+    Args:
+        value: Serialized expression source.
+
+    Returns:
+        A composable expression value.
+
+    Raises:
+        TypeError: If Python evaluates an expression as a boolean.
+
+    Example:
+        >>> from genome_spy import datum
+        >>> str((datum.score >= 10) & (datum.kind == "PASS"))
+        "((datum.score >= 10) && (datum.kind === 'PASS'))"
+    """
+
+    def __repr__(self) -> str:
+        return str(self)
+
+    def _to_expr(self) -> Expression:
+        return self
+
+    def copy(self) -> Self:
+        """Return an equivalent expression value.
+
+        Returns:
+            A new expression with the same serialized source.
+
+        Raises:
+            No exceptions are raised.
+
+        Example:
+            >>> from genome_spy import datum
+            >>> str(datum.x.copy())
+            'datum.x'
+        """
+        return type(self)(self)
+
+    def to_dict(self) -> str:
+        """Return the schema-compatible expression string.
+
+        Returns:
+            The serialized expression source.
+
+        Raises:
+            No exceptions are raised.
+
+        Example:
+            >>> from genome_spy import datum
+            >>> datum.x.to_dict()
+            'datum.x'
+        """
+        return str(self)
+
+
+class DatumExpression:
+    """Expression-field behavior mixed into the generated datum helper."""
+
+    def __repr__(self) -> str:
+        return "datum"
+
+    def __getattr__(self, name: str) -> Expression:
+        if name.startswith("__") and name.endswith("__"):
+            raise AttributeError(name)
+        return Expression(f"datum.{name}")
+
+    def __getitem__(self, key: Any) -> Expression:
+        return Expression(f"datum[{_js_repr(key)}]")
+
+
+IntoExpression: TypeAlias = (
+    str
+    | int
+    | float
+    | bool
+    | None
+    | Expression
+    | list[Any]
+    | tuple[Any, ...]
+    | dict[str, Any]
+    | ExpressionOperand
+)
+
+
+__all__ = [
+    "DatumExpression",
+    "Expression",
+    "ExpressionOperand",
+    "ExpressionOperatorMixin",
+    "IntoExpression",
+]

genome_spy/_parameters.py

@@ -0,0 +1,267 @@
+"""Altair-style authoring handles for GenomeSpy parameters."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Self, cast
+
+from genome_spy._expressions import (
+    Expression,
+    ExpressionOperatorMixin,
+    _expression_string,
+)
+from genome_spy.schema import core
+from genome_spy.schemapi import (
+    SchemaBase,
+    SchemaValidationError,
+    Undefined,
+    normalize_schema_value,
+)
+
+
+class Parameter(ExpressionOperatorMixin, core.ExprRef):
+    """Represent a declared GenomeSpy parameter in Python expressions.
+
+    A parameter handle keeps its generated declaration in :attr:`param` and
+    supplies the parameter name when used in an expression. Attach handles to
+    charts with :meth:`genome_spy.TopLevelSpec.add_params`.
+
+    Args:
+        param: Exact generated GenomeSpy parameter declaration.
+        empty: Whether an empty selection matches when consumed as a predicate.
+
+    Returns:
+        A reusable parameter authoring handle.
+
+    Raises:
+        TypeError: If the declaration has no string name.
+
+    Example:
+        >>> threshold = param("threshold", value=0.5)
+        >>> str(threshold * 2)
+        '(threshold * 2)'
+    """
+
+    def __init__(
+        self,
+        param: SchemaBase,
+        *,
+        empty: bool = True,
+        _name_is_explicit: bool = True,
+    ) -> None:
+        from genome_spy.schema.ergonomics import (
+            _PARAMETER_TYPES,
+            _SELECTION_PARAMETER_TYPES,
+        )
+
+        if not isinstance(param, _PARAMETER_TYPES):
+            raise TypeError(
+                "Parameter requires a generated GenomeSpy parameter declaration."
+            )
+        values = param.to_dict(validate=False)
+        name = values.get("name")
+        if not isinstance(name, str):
+            raise TypeError("A parameter declaration must have a string name.")
+        self.param = param
+        self.empty = empty
+        self._name_is_explicit = _name_is_explicit
+        self._is_selection = isinstance(
+            param, _SELECTION_PARAMETER_TYPES
+        ) or _matches_parameter_type(values, _SELECTION_PARAMETER_TYPES)
+        core.ExprRef.__init__(self, expr=name)
+
+    @property
+    def name(self) -> str:
+        """Return the declared GenomeSpy parameter name."""
+        return cast(str, self._kwds["expr"])
+
+    @property
+    def is_selection(self) -> bool:
+        """Return whether this handle represents a selection parameter."""
+        return self._is_selection
+
+    @property
+    def name_is_explicit(self) -> bool:
+        """Return whether the parameter name was supplied by the user."""
+        return self._name_is_explicit
+
+    def _to_expr(self) -> Expression:
+        if self.is_selection:
+            raise TypeError("Selection parameters cannot be used as expressions.")
+        return Expression(self.name)
+
+    def copy(self, *, deep: bool = True, **kwds: Any) -> Self:
+        """Return an equivalent parameter handle.
+
+        Args:
+            deep: Copy nested values in the generated declaration.
+            **kwds: Updates for the generated declaration.
+
+        Returns:
+            A parameter handle with the same declaration and authoring metadata.
+
+        Raises:
+            TypeError: If the copied declaration is not a generated parameter.
+
+        Example:
+            >>> threshold = param("threshold", value=0.5)
+            >>> threshold.copy().param.to_dict()
+            {'name': 'threshold', 'value': 0.5}
+        """
+        definition = self.param.copy(deep=deep, **kwds)
+        name_is_explicit = self.name_is_explicit or "name" in kwds
+        if not name_is_explicit and kwds:
+            values = definition.to_dict(validate=False)
+            values.pop("name", None)
+            values["name"] = _stable_parameter_name(values)
+            definition = type(definition)(**values)
+        return type(self)(
+            definition,
+            empty=self.empty,
+            _name_is_explicit=name_is_explicit,
+        )
+
+    def to_dict(self, *, validate: bool = True) -> dict[str, Any]:
+        """Return an expression reference for expression-capable parameters.
+
+        Args:
+            validate: Validate the expression reference against its schema.
+
+        Returns:
+            A GenomeSpy expression-reference mapping.
+
+        Raises:
+            TypeError: If this is a selection parameter, which requires an
+                explicit condition or filter context.
+
+        Example:
+            >>> param("opacity", value=0.5).to_dict()
+            {'expr': 'opacity'}
+        """
+        if self.is_selection:
+            raise TypeError(
+                "Selection parameters require a condition or filter context; "
+                "attach declarations with chart.add_params(selection)."
+            )
+        return core.ExprRef(expr=self.name).to_dict(validate=validate)
+
+
+def _stable_parameter_name(properties: dict[str, Any]) -> str:
+    normalized = normalize_schema_value(properties, validate=False)
+    payload = json.dumps(
+        normalized,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=True,
+    )
+    digest = hashlib.sha256(payload.encode("utf-8")).hexdigest()[:10]
+    return f"param_{digest}"
+
+
+def _defined_properties(properties: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in properties.items() if value is not Undefined}
+
+
+def _matches_parameter_type(
+    properties: dict[str, Any],
+    variants: tuple[type[SchemaBase], ...],
+) -> bool:
+    for variant in variants:
+        try:
+            variant(**properties).to_dict(validate=True)
+        except SchemaValidationError:
+            continue
+        return True
+    return False
+
+
+def _select_parameter_class(
+    properties: dict[str, Any],
+    variants: tuple[type[SchemaBase], ...],
+) -> type[SchemaBase]:
+    supplied = set(properties)
+    matches: list[type[SchemaBase]] = []
+    for variant in variants:
+        schema = variant.resolve_references()
+        allowed = set(schema.get("properties", {}))
+        required = set(schema.get("required", ()))
+        if required <= supplied <= allowed:
+            matches.append(variant)
+    if len(matches) > 1:
+        validated: list[type[SchemaBase]] = []
+        for variant in matches:
+            try:
+                variant(**properties).to_dict(validate=True)
+            except SchemaValidationError:
+                continue
+            validated.append(variant)
+        matches = validated
+    if len(matches) != 1:
+        names = ", ".join(sorted(supplied)) or "no arguments"
+        if not matches:
+            raise TypeError(f"No GenomeSpy parameter variant accepts: {names}.")
+        choices = ", ".join(variant.__name__ for variant in matches)
+        raise TypeError(
+            f"Ambiguous GenomeSpy parameter arguments ({names}): {choices}."
+        )
+    return matches[0]
+
+
+def _make_parameter(
+    name: str | None = None,
+    /,
+    *,
+    _variants: tuple[type[SchemaBase], ...],
+    empty: bool = True,
+    **properties: Any,
+) -> Parameter:
+    """Create a reusable GenomeSpy parameter handle.
+
+    The supplied properties are matched against the concrete parameter leaves
+    in GenomeSpy's generated schema. The resulting declaration is available as
+    ``handle.param`` and is attached to charts with ``add_params()``.
+
+    Args:
+        name: Parameter name. A deterministic name is generated when omitted.
+        bind: Optional input binding for a value parameter.
+        description: Human-readable parameter description.
+        expr: Reactive expression for an expression parameter.
+        persist: Whether GenomeSpy App should persist the parameter.
+        push: Reuse and update an ancestor parameter with the same name.
+        ruler: Ruler configuration.
+        select: Point or interval selection configuration.
+        transition: Numeric interpolation configuration.
+        value: Initial parameter value.
+        empty: Whether an empty selection matches in conditions and filters.
+
+    Returns:
+        A reusable parameter handle containing the exact generated declaration.
+
+    Raises:
+        TypeError: If the supplied properties match no unique parameter branch.
+
+    Example:
+        >>> cutoff = param("cutoff", value=0.5)
+        >>> cutoff.param.to_dict()
+        {'name': 'cutoff', 'value': 0.5}
+    """
+    properties = _defined_properties(properties)
+    if "expr" in properties:
+        properties["expr"] = _expression_string(properties["expr"])
+    name_is_explicit = name is not None
+    properties["name"] = name or _stable_parameter_name(properties)
+    parameter_class = _select_parameter_class(properties, _variants)
+    definition = parameter_class(**properties)
+    return Parameter(
+        definition,
+        empty=empty,
+        _name_is_explicit=name_is_explicit,
+    )
+
+
+def _unwrap_parameter(value: Parameter | SchemaBase) -> SchemaBase:
+    return value.param if isinstance(value, Parameter) else value
+
+
+__all__ = ["Parameter"]