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

genome_spy/api.py

@@ -0,0 +1,198 @@
+"""Public API re-exports for the handwritten ergonomic layer."""
+
+from genome_spy.channels import Locus, compare, datum, locus, value
+from genome_spy._expressions import Expression
+from genome_spy._parameters import Parameter
+from genome_spy.arrow import to_arrow_ipc
+from genome_spy.chart import (
+    Chart,
+    ConcatChart,
+    HConcatChart,
+    ImportedView,
+    LayerChart,
+    MultiscaleChart,
+    TopLevelSpec,
+    VConcatChart,
+)
+from genome_spy.data import Data, lazy
+from genome_spy.helpers import (
+    axes,
+    config,
+    condition,
+    data_format,
+    dynamic_opacity,
+    expr,
+    parse,
+    scales,
+    step,
+    title,
+    view,
+    view_config,
+    when,
+)
+
+# BEGIN GENERATED INTERACTION IMPORTS
+from genome_spy.helpers import (
+    binding,
+    binding_checkbox,
+    binding_radio,
+    binding_range,
+    binding_select,
+    param,
+    ruler,
+    selection_interval,
+    selection_point,
+)
+
+# END GENERATED INTERACTION IMPORTS
+from genome_spy.jupyter import JupyterChart
+from genome_spy.schema.channels import (
+    Angle,
+    Color,
+    Direction,
+    Dx,
+    Dy,
+    FacetIndex,
+    Fill,
+    FillOpacity,
+    Key,
+    Opacity,
+    Sample,
+    Search,
+    SemanticScore,
+    Shape,
+    Size,
+    Stroke,
+    StrokeOpacity,
+    StrokeWidth,
+    Text,
+    Tooltip,
+    UniqueId,
+    X,
+    X2,
+    XOffset,
+    Y,
+    Y2,
+    YOffset,
+)
+from genome_spy.schema.core import (
+    AxisGenomeData,
+    BrushConfig,
+    DataFormat,
+    DynamicOpacity,
+    ExprRef,
+    GenomeAxis,
+    HandledTooltip,
+    Legend,
+    Paddings,
+    Parse,
+    RulerMarkConfig,
+    Scale,
+    SelectionDomainRef,
+    SizeDef,
+    Step,
+    Title,
+)
+from genome_spy.schema.composition import (
+    concat,
+    hconcat,
+    import_view,
+    layer,
+    multiscale,
+    vconcat,
+)
+
+__all__ = [
+    "Angle",
+    "axes",
+    "AxisGenomeData",
+    "BrushConfig",
+    "Chart",
+    "Color",
+    "condition",
+    "Direction",
+    "compare",
+    "ConcatChart",
+    "Data",
+    "DataFormat",
+    "DynamicOpacity",
+    "Dx",
+    "Dy",
+    "ExprRef",
+    "Expression",
+    "FacetIndex",
+    "Fill",
+    "FillOpacity",
+    "GenomeAxis",
+    "HandledTooltip",
+    "HConcatChart",
+    "ImportedView",
+    "JupyterChart",
+    "Key",
+    "LayerChart",
+    "Legend",
+    "Locus",
+    "MultiscaleChart",
+    "Opacity",
+    "Parameter",
+    "Paddings",
+    "Parse",
+    "Sample",
+    "Scale",
+    "SelectionDomainRef",
+    "Search",
+    "SemanticScore",
+    "Shape",
+    "Size",
+    "SizeDef",
+    "Step",
+    "Stroke",
+    "StrokeOpacity",
+    "StrokeWidth",
+    "Text",
+    "Tooltip",
+    "TopLevelSpec",
+    "to_arrow_ipc",
+    "Title",
+    "UniqueId",
+    "VConcatChart",
+    "X",
+    "X2",
+    "XOffset",
+    "Y",
+    "Y2",
+    "YOffset",
+    "concat",
+    "config",
+    "data_format",
+    "datum",
+    "dynamic_opacity",
+    "expr",
+    "hconcat",
+    "import_view",
+    "layer",
+    "lazy",
+    "locus",
+    "multiscale",
+    "parse",
+    "RulerMarkConfig",
+    "scales",
+    "step",
+    "title",
+    "value",
+    "view",
+    "view_config",
+    "vconcat",
+    "when",
+    # BEGIN GENERATED INTERACTION EXPORTS
+    "binding",
+    "binding_checkbox",
+    "binding_radio",
+    "binding_range",
+    "binding_select",
+    "param",
+    "ruler",
+    "selection_interval",
+    "selection_point",
+    # END GENERATED INTERACTION EXPORTS
+]

genome_spy/arrow.py

@@ -0,0 +1,155 @@
+"""Arrow IPC serialization helpers for notebook data transport."""
+
+from __future__ import annotations
+
+from io import BytesIO
+from typing import Any
+
+__all__ = ["to_arrow_ipc"]
+
+
+def _module_root(value: Any) -> str:
+    """Return the top-level module that defines a value's type."""
+    return type(value).__module__.partition(".")[0]
+
+
+def _is_polars_frame(value: Any) -> bool:
+    """Return whether a value is a Polars dataframe without importing Polars."""
+    return _module_root(value) == "polars" and callable(
+        getattr(value, "write_ipc", None)
+    )
+
+
+def _is_pandas_frame(value: Any) -> bool:
+    """Return whether a value is a pandas dataframe without importing pandas."""
+    return _module_root(value) == "pandas" and type(value).__name__ == "DataFrame"
+
+
+def _is_pyarrow_table(value: Any) -> bool:
+    """Return whether a value is a supported PyArrow tabular object."""
+    return _module_root(value) == "pyarrow" and type(value).__name__ in {
+        "Table",
+        "RecordBatch",
+    }
+
+
+def _validated_payload(value: Any) -> bytes:
+    """Return a nonempty immutable IPC payload or raise a contextual error."""
+    if hasattr(value, "getvalue"):
+        value = value.getvalue()
+    if not isinstance(value, bytes | bytearray | memoryview):
+        raise TypeError(
+            "Arrow IPC writer must return bytes or a binary buffer, "
+            f"not {type(value).__name__}."
+        )
+    payload = bytes(value)
+    if not payload:
+        raise ValueError("Arrow IPC writer returned an empty payload.")
+    return payload
+
+
+def _write_ipc_method(data: Any) -> bytes:
+    """Serialize an object that exposes Polars-compatible ``write_ipc``."""
+    try:
+        result = data.write_ipc(file=None, compression="uncompressed")
+    except (TypeError, ValueError) as error:
+        raise TypeError(
+            f"Could not write uncompressed Arrow IPC data from {type(data).__name__}."
+        ) from error
+    return _validated_payload(result)
+
+
+def _load_pyarrow() -> Any | None:
+    """Import PyArrow only when a recognized table requires it."""
+    try:
+        import pyarrow as pa
+    except ImportError:
+        return None
+    return pa
+
+
+def _write_pyarrow_ipc(data: Any, pa: Any) -> bytes:
+    """Serialize a PyArrow table or record batch as an uncompressed IPC file."""
+    table = (
+        pa.Table.from_batches([data]) if type(data).__name__ == "RecordBatch" else data
+    )
+    output = BytesIO()
+    options = pa.ipc.IpcWriteOptions(compression=None)
+    with pa.ipc.new_file(output, table.schema, options=options) as writer:
+        writer.write_table(table)
+    return _validated_payload(output.getvalue())
+
+
+def _write_pandas_ipc(data: Any, pa: Any) -> bytes:
+    """Serialize a pandas dataframe through optional PyArrow."""
+    table = pa.Table.from_pandas(data, preserve_index=False)
+    return _write_pyarrow_ipc(table, pa)
+
+
+def _try_to_arrow_ipc(data: Any) -> bytes | None:
+    """Return IPC bytes for an automatically supported table, if available.
+
+    ``None`` means the input is not an automatically supported Arrow producer
+    or pandas support is unavailable because PyArrow is not installed. Errors
+    from recognized writers intentionally propagate rather than falling back to
+    JSON records.
+    """
+    if _is_polars_frame(data):
+        return _write_ipc_method(data)
+    if _is_pyarrow_table(data):
+        pa = _load_pyarrow()
+        if pa is None:
+            raise RuntimeError("PyArrow table support requires the 'arrow' extra.")
+        return _write_pyarrow_ipc(data, pa)
+    if _is_pandas_frame(data):
+        pa = _load_pyarrow()
+        return None if pa is None else _write_pandas_ipc(data, pa)
+    return None
+
+
+def to_arrow_ipc(data: Any) -> bytes:
+    """Serialize a DataFrame-like object as uncompressed Arrow IPC bytes.
+
+    Description:
+        Supports Polars dataframes, PyArrow tables and record batches, pandas
+        dataframes when the optional ``arrow`` extra is installed, and custom
+        objects with a Polars-compatible ``write_ipc`` method. The helper
+        intentionally writes uncompressed IPC because GenomeSpy's Arrow decoder
+        does not support compressed IPC buffers yet.
+
+    Args:
+        data: A supported table or compatible object with
+            ``write_ipc(file=None, compression="uncompressed")``.
+
+    Returns:
+        The complete Arrow IPC file payload as immutable bytes.
+
+    Raises:
+        TypeError: If the object does not provide a compatible writer or the
+            writer does not return a bytes-like payload.
+        ValueError: If the writer returns an empty payload.
+
+    Example:
+        >>> import polars as pl
+        >>> payload = to_arrow_ipc(pl.DataFrame({"x": [1, 2]}))
+        >>> payload[:6]
+        b'ARROW1'
+    """
+
+    payload = _try_to_arrow_ipc(data)
+    if payload is not None:
+        return payload
+
+    if _is_pandas_frame(data):
+        raise TypeError(
+            "Serializing pandas DataFrames as Arrow IPC requires PyArrow. "
+            "Install genome-spy-python[arrow]."
+        )
+
+    writer = getattr(data, "write_ipc", None)
+    if not callable(writer):
+        raise TypeError(
+            "Arrow IPC serialization requires an object with "
+            'write_ipc(file=None, compression="uncompressed").'
+        )
+    return _write_ipc_method(data)

genome_spy/channels.py

@@ -0,0 +1,193 @@
+"""Channel helpers for the first handwritten GenomeSpy API."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Self, cast
+
+from genome_spy._utils import is_mapping, parse_shorthand
+from genome_spy.schema._kwds import CompareParamsKwds
+from genome_spy.schema.core import CompareParams
+from genome_spy.schema.ergonomics import (
+    DatumChannelMethodMixin,
+    Locus,
+    LocusChannelMethodMixin,
+    ValueChannelMethodMixin,
+    compare,
+    datum,
+    locus,
+    value,
+)
+from genome_spy.schemapi import (
+    SchemaBase,
+    Undefined,
+    merge_mapping_value,
+    normalize_schema_value,
+)
+
+_MISSING = Undefined
+
+__all__ = [
+    "Channel",
+    "LocusChannel",
+    "Locus",
+    "channel",
+    "compare",
+    "datum",
+    "locus",
+    "value",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Channel:
+    """A serializable GenomeSpy encoding channel definition.
+
+    This class is mostly a small runtime backend for generated channel wrappers
+    and the handwritten locus helper, not the main authoring surface users
+    should build on directly.
+    """
+
+    definition: dict[str, Any] = field(default_factory=dict)
+    encoding_name: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Return the JSON-serializable channel definition."""
+        return dict(self.definition)
+
+    def _with_sort(
+        self,
+        value: CompareParams | CompareParamsKwds | str | list[str] | None | object,
+        /,
+        properties: dict[str, Any],
+    ) -> Self:
+        """Return a channel with a normalized ``sort`` configuration."""
+        definition = self.to_dict()
+        definition["sort"] = _merge_sort_value(
+            definition.get("sort", Undefined),
+            value,
+            **properties,
+        )
+        return self._replace_definition(definition)
+
+    def _with_nested(
+        self,
+        key: str,
+        value: SchemaBase | dict[str, Any] | None | object = _MISSING,
+        /,
+        **kwargs: Any,
+    ) -> Self:
+        definition = self.to_dict()
+        definition[key] = merge_mapping_value(
+            definition.get(key, Undefined),
+            key,
+            value,
+            **kwargs,
+        )
+        return self._replace_definition(definition)
+
+    def _with_property(self, key: str, value: Any) -> Self:
+        definition = self.to_dict()
+        definition[key] = normalize_schema_value(value, validate=False)
+        return self._replace_definition(definition)
+
+    def _replace_definition(self, definition: dict[str, Any]) -> Self:
+        if type(self) is Channel:
+            return cast(Self, Channel(definition, self.encoding_name))
+        return self.__class__(definition)
+
+
+@dataclass(frozen=True, slots=True)
+class LocusChannel(LocusChannelMethodMixin, Channel):
+    """A handwritten locus channel with generated-style fluent setters.
+
+    GenomeSpy's genomic locus channels are intentionally kept as a small
+    handwritten ergonomic layer rather than forced into the ordinary generated
+    channel shape.
+    """
+
+    def title(self, value: str | None) -> Self:
+        """Return a locus channel with ``title`` updated."""
+        return self._with_property("title", value)
+
+    def chrom(self, value: str) -> Self:
+        """Return a locus channel with ``chrom`` updated."""
+        return self._with_property("chrom", value)
+
+    def pos(self, value: str | None) -> Self:
+        """Return a locus channel with ``pos`` updated."""
+        return self._with_property("pos", value)
+
+    def offset(self, value: float) -> Self:
+        """Return a locus channel with ``offset`` updated."""
+        return self._with_property("offset", value)
+
+    def band(self, value: float) -> Self:
+        """Return a locus channel with ``band`` updated."""
+        return self._with_property("band", value)
+
+
+@dataclass(frozen=True, slots=True)
+class DatumChannel(DatumChannelMethodMixin, Channel):
+    """A constant-datum channel with schema-derived fluent methods."""
+
+
+@dataclass(frozen=True, slots=True)
+class ValueChannel(ValueChannelMethodMixin, Channel):
+    """A constant-value channel with schema-derived fluent methods."""
+
+
+def channel(
+    value: Channel | SchemaBase | str | dict[str, Any],
+    /,
+    *,
+    encoding_name: str | None = None,
+    **kwargs: Any,
+) -> Channel:
+    """Create a generic channel definition from shorthand or a raw mapping."""
+    if isinstance(value, Channel):
+        definition = value.to_dict()
+        encoding_name = encoding_name or value.encoding_name
+    elif isinstance(value, SchemaBase):
+        definition = cast(dict[str, Any], normalize_schema_value(value, validate=False))
+    elif isinstance(value, str):
+        definition = parse_shorthand(value)
+    elif is_mapping(value):
+        definition = cast(dict[str, Any], normalize_schema_value(value, validate=False))
+    else:
+        raise TypeError(f"Unsupported channel value: {type(value)!r}")
+
+    definition.update(kwargs)
+    return Channel(definition, encoding_name=encoding_name)
+
+
+def _merge_sort_value(
+    current: Any,
+    value: CompareParams
+    | CompareParamsKwds
+    | str
+    | list[str]
+    | None
+    | object = _MISSING,
+    /,
+    **kwargs: Any,
+) -> Any:
+    if value is _MISSING or value is None or isinstance(value, CompareParams | dict):
+        try:
+            return merge_mapping_value(current, "sort", value, **kwargs)
+        except TypeError as error:
+            message = str(error)
+            if "null 'sort'" in message or "non-mapping value" in message:
+                raise
+            raise TypeError(
+                f"Unsupported nested 'sort' value: {type(value)!r}"
+            ) from error
+
+    if isinstance(value, str | list):
+        if kwargs:
+            raise TypeError(
+                "Cannot merge keyword properties into simple 'sort' values."
+            )
+        return normalize_schema_value(value, validate=False)
+
+    raise TypeError(f"Unsupported nested 'sort' value: {type(value)!r}")